Class HttpClient
Description
Defines a class of using HttpClient
Syntax
class HttpClient
Members
Public Constructors |
|
|---|---|
HttpClient::HttpClient |
Constructs a HttpClient object |
Public Methods |
|
HttpClient::beginRequest |
Start a more complex request |
HttpClient::endRequest |
End a more complex request |
HttpClient::get |
Connect to the server and start to send a GET request |
HttpClient::post |
Connect to the server and start to send a POST request |
HttpClient::put |
Connect to the server and start to send a PUT request |
HttpClient::startRequest |
Connect to the server and start to send the request |
HttpClient::sendHeader |
Send an additional header line |
HttpClient::sendBasicAuth |
Send a basic authentication header |
HttpClient::finishRequest |
Finish sending the HTTP request |
HttpClient::responseStatusCode |
Get the HTTP status code contained in the response |
HttpClient::readHeader |
Read the next character of the response headers |
HttpClient::skipResponseHeaders |
Skip any response headers to get to the body |
HttpClient::endOfHeadersReached |
Test whether all of the response headers have been consumed |
HttpClient::endOfBodyReached |
Test whether the end of the body has been reached |
HttpClient::contentLength |
Return the length of the body |
- HttpClient::HttpClient
Description
Constructs a HttpClient object. If Marco “PROXY_ENABLED” is defined,currently disabled as introduces a dependency on DNS.h in Ethernet.
Syntax
HttpClient::HttpClient(Client& aClient, const char* aProxy = NULL,uint16_t aProxyPort = 0);
HttpClient::HttpClient(Client& aClient);
Parameters
aClient: The object of class WiFiClient.
aProxy: The proxy name. The default proxy name is “NULL”.
aProxyPort : The proxy port. The default value for the proxy port is 0.
Returns
The function returns nothing.
Example Code
The example demonstrate how to download the content from URL indicated in kHostname[].
1#include "HttpClient.h"
2#include "WiFi.h"
3#include "WiFiClient.h"
4char ssid[] = "YourNetwork"; // your network SSID (name)
5char pass[] = "password"; // your network password (use for WPA, or use as key for WEP)
6int keyIndex = 0; // your network key Index number (needed only for WEP)
7//Name of the server we want to connect to
8const char kHostname[] = "www.google.com";
9const char kPath[] = "/";
10//Number of milliseconds to wait without receiving any data before we give up
11const int kNetworkTimeout = 30*1000;
12//Number of milliseconds to wait if no data is available before trying again
13const int kNetworkDelay = 1000;
14int status = WL_IDLE_STATUS;
15void setup() {
16
17Serial.begin(9600);
18while ( status != WL_CONNECTED) {
19 Serial.print("Attempting to connect to SSID: ");
20 Serial.println(ssid);
21 status = WiFi.begin(ssid, pass);
22 // wait 10 seconds for connection:
23 delay(10000);
24}
25Serial.println("Connected to wifi");
26printWifiStatus();
27
28void loop() {
29
30int err =0;
31WiFiClient c;
32HttpClient http(c);
33err = http.get(kHostname, kPath);
34if (err == 0)
35{
36 Serial.println("startedRequest ok");
37 err = http.responseStatusCode();
38 if (err >= 0)
39 {
40 Serial.print("Got status code: ");
41 Serial.println(err);
42 // Usually you'd check that the response code is 200 or a
43 // similar "success" code (200-299) before carrying on,
44 // but we'll print out whatever response we get
45 err = http.skipResponseHeaders();
46 if (err >= 0)
47 {
48 int bodyLen = http.contentLength();
49 Serial.print("Content length is: ");
50 Serial.println(bodyLen);
51 Serial.println();
52 Serial.println("Body returned follows:");
53
54 // Now we've got to the body, so we can print it out
55 unsigned long timeoutStart = millis();
56 char c;
57 // Whilst we haven't timed out & haven't reached the end of the body
58 while ( (http.connected() || http.available()) &&
59 ((millis() - timeoutStart) < kNetworkTimeout) )
60 {
61 if (http.available())
62 {
63 c = http.read();
64 // Print out this character
65 Serial.print(c);
66
67 bodyLen--;
68 // We read something, reset the timeout counter
69 timeoutStart = millis();
70 }
71 else
72 {
73 // We haven't got any data, so let's pause to allow some to arrive
74 delay(kNetworkDelay);
75 }
76 }
77 }
78 else
79 {
80 Serial.print("Failed to skip response headers: ");
81 Serial.println(err);
82 }
83 }
84 else
85 {
86 Serial.print("Getting response failed: ");
87 Serial.println(err);
88 }
89}
90else
91{
92 Serial.print("Connect failed: ");
93 Serial.println(err);
94 }
95 http.stop();
96 // And just stop, now that we've tried a download
97 while(1);
98}
99void printWifiStatus() {
100 // print the SSID of the network you're attached to:
101 Serial.print("SSID: ");
102 Serial.println(WiFi.SSID());
103 // print your WiFi shield's IP address:
104 IPAddress ip = WiFi.localIP();
105 Serial.print("IP Address: ");
106 Serial.println(ip);
107 // print the received signal strength:
108 long rssi = WiFi.RSSI();
109 Serial.print("signal strength (RSSI):");
110 Serial.print(rssi);
111 Serial.println(" dBm");
112}
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::beginRequest
Description
Start a more complex request. Use this when you need to send additional headers in the request, but you will also need to call endRequest() when you are finished.
Syntax
void HttpClient::beginRequest(void);
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL indicated in kHostname[]. Details of the code can be found in the previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::endRequest
Description
End a more complex request. Use this when you need to have sent additional headers in the request, but you will also need to call beginRequest() at the start.
Syntax
void HttpClient::endRequest(void);
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL indicated in kHostname[]. Details of the code can be found in the previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::get
Description
Connect to the server and start to send a GET request. If the input
parameter contains aServerAddress, the connection will not perform a
DNS lookup and just purely connect to the given IP address.
Syntax
int HttpClient::get(const char* aServerName, uint16_t aServerPort,const char* aURLPath, const char* aUserAgent = 0);
int HttpClient::get(const char* aServerName, const char* aURLPath,const char* aUserAgent=0);
int HttpClient::get(const IPAddress& aServerAddress, const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aUserAgent = NULL);
int HttpClient::get(const IPAddress& aServerAddress, const char* aServerName, const char* aURLPath, const char* aUserAgent = NULL);
Parameters
aServerName: The name of the server being connected to. If aServerName
is “NULL”, the “Host” header line will not be sent.
aServerPort: The port on which server connected.
aURLPath: The URL to request.
aUserAgent: User-Agent string to be sent. If aUserAgent indicated as
“NULL”, the default user-agent kUserAgent will be sent.
aServerAddress: IP address of the server to connect to.
Returns
Return 0 if successful, otherwise indicates an error occurs.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL
indicated in kHostname[]. Details of the code can be found in the
previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::post
Description
Connect to the server and start to send a “POST” request. If the input
parameter has “aServerAddress”, connects doesn’t perform a DNS lookup
and just connects to the given IP address.
Syntax
int HttpClient::post(const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aUserAgent = NULL);
int HttpClient::post(const char* aServerName, const char* aURLPath,const char* aUserAgent = NULL);
int HttpClient::post(const IPAddress& aServerAddress, const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aUserAgent = NULL);
int HttpClient::post(const IPAddress& aServerAddress, const char* aServerName, const char* aURLPath, const char* aUserAgent = NULL);
Parameters
aServerName : Name of the server being connected to. If NULL, the Host header line won’t be sent.
aServerPort : Port to connect to on the server.
aURLPath : Url to request.
aUserAgent : User-Agent string to be sent. If aUserAgent indicated as NULL, the default user-agent kUserAgent will be sent.
aServerAddress : IP address of the server to connect to.
Returns
Return 0 if successful, otherwise indicates an error occurs.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL
indicated in kHostname[]. Details of the code can be found in the
previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::put
Description
Connect to the server and start to send a PUT request. If the input parameter has “aServerAddress”, connects doesn’t perform a DNS lookup and just connects to the given IP address.
Syntax
int HttpClient::put(const char* aServerName, uint16_t aServerPort,const cha* aURLPath, const char* aUserAgent = NULL);
int HttpClient::put(const char* aServerName, const char* aURLPath,const char* aUserAgent = NULL);
int HttpClient::put(const IPAddress& aServerAddress, const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aUserAgent = NULL);
int HttpClient::put(const IPAddress& aServerAddress, const char* aServerName, const char* aURLPath, const char* aUserAgent = NULL);
Parameters
aServerName: Name of the server being connected to. If NULL, the Host header line won’t be sent.
aServerPort: Port to connect to on the server.
aURLPath: Url to request.
aUserAgent: User-Agent string to be sent. If aUserAgent indicated as “NULL”, the default user-agent kUserAgent will be sent.
aServerAddress : IP address of the server to connect to.
Returns
Return 0 if successful, otherwise indicates an error occurs.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL
indicated in kHostname[]. Details of the code can be found in the
previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::startRequest
Description
Connect to the server and start to send the request.
Syntax
int HttpClient::startRequest(const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aHttpMethod, constchar* aUserAgent);
int HttpClient::startRequest(const IPAddress& aServerAddress, const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aHttpMethod, const char* aUserAgent);
Parameters
aServerAddress: IP address of the server to connect to.
aServerName: Name of the server being connected to. If NULL, the Host header line won’t be sent.
aServerPort: Port to connect to on the server.
aURLPath: Url to request.
aHttpMethod: Type of HTTP request to make, e.g. “GET”, “POST”, etc.
aUserAgent: User-Agent string to send. If NULL the default user-agent kUserAgent will be sent.
Returns
Return 0 if successful, else error.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL
indicated in kHostname[]. Details of the code can be found in the
previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::sendHeader
Description
The function sends an additional header line.The function void HttpClient:: sendHeader(const char* aHeader);can only be called in between the calls to startRequest and finishRequest.The other 2 functions void HttpClient::sendHeader(const char* aHeaderName, const char* aHeaderValue); and void HttpClient::sendHeader(const char* aHeaderName, const int aHeaderValue); are alternate form the previous one, which takes the header name and content as separately (as strings or integer). For example, to send an XXXXXX header, user might call sendHeader(“XXXXX”, “Something”) or sendHeader(“XXXXX”, 123).And the call will add the “: ” in the log to separate different header in the case of multiple headers.
Syntax
void HttpClient::sendHeader(const char* aHeader);
void HttpClient::sendHeader(const char* aHeaderName, const char* aHeaderValue);
void HttpClient::sendHeader(const char* aHeaderName, const int aHeaderValue);
Parameters
aHeader : Header line to send, in its entirety (but without the trailing CRLF. E.g. “Authorization: Basic YQDDCAIGES”.
aHeaderName : Type of header being sent.
aHeaderValue : Value for that header.
Returns
The function returns nothing.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URLindicated in kHostname[]. Details of the code can be found in the previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::sendBasicAuth
Description
The function sends a basic authentication header which will encode the given username and password, and send them in a suitable header line for doing Basic Authentication.
Syntax
void HttpClient::sendBasicAuth(const char* aUser, const char* aPassword);
Parameters
aUser: Username for the authorization.
aPassword : Password for the user aUser.
Returns
The function returns nothing.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL indicated in kHostname[]. Details of the code can be found in the previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::finishRequest
Description
Finish sending the HTTP request. The function sends a blank line to signify the end of the request.
Syntax
void HttpClient::finishRequest(void);
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL
indicated in kHostname[]. Details of the code can be found in the
previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::responseStatusCode
Description
Get the HTTP status code contained in the response. For example, “200” for successful requests, “404” for file not found, etc.
Syntax
int HttpClient::responseStatusCode(void);
Parameters
The function requires no input parameter.
Returns
Return 0 if successful, else error.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL
indicated in kHostname[]. Details of the code can be found in the
previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::readHeader
Description
The function reads the next character of the response headers. This functions the same as read() but to be used when reading through the headers which are slightly less efficient. The user might check whether the end of the headers has been reached by calling endOfHeadersReached(), although after that point this will still return data as read() would.
Syntax
int HttpClient::readHeader(void);
Parameters
The function requires no input parameter.
Returns
Return the next character of the response headers.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL
indicated in kHostname[]. Details of the code can be found in the
previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::skipResponseHeaders
Description
Skip any response headers to get to the body. Use this if you don’t want to do any special processing of the headers returned in the response. You can also use it after you’ve found all of the headers you’re interested in, and just want to get on with processing the body.
Syntax
int HttpClient::skipResponseHeaders(void);
Parameters
The function requires no input parameter.
Returns
Return 0 if successful, else error.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL
indicated in kHostname[]. Details of the code can be found in the
previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::endOfHeadersReached
Description
Test whether all of the response headers have been consumed.
Syntax
bool HttpClient::endOfHeadersReached(void);
Parameters
The function requires no input parameter.
Returns
Return true if we are now processing the response body, else false.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL
indicated in kHostname[]. Details of the code can be found in the
previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::endOfBodyReached
Description
Test whether the end of the body has been reached. It only works if the Content-Length header was returned by the server.
Syntax
bool HttpClient::endOfBodyReached(void);
Parameters
The function requires no input parameter.
Returns
Return true if we are now at the end of the body, else false.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL
indicated in kHostname[]. Details of the code can be found in the
previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.
- HttpClient::contentLength
Description
The function returns the length of the body.
Syntax
int HttpClient::contentLength(void);
Parameters
The function requires no input parameter.
Returns
Return Length of the body, in bytes, or kNoContentLengthHeader if no Content-Length header was returned by the server.
Example Code
Example: SimpleHttpExample
The example demonstrates how to download the content from the URL indicated in kHostname[]. Details of the code can be found in the previous section of HttpClient:: HttpClient.
Notes and Warnings
Include “HttpClient.h” to use the class function.