HttpClient Class
HttpClient Class
Description
A class to use 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 | Check whether the end of the headers have been reached.. |
| HttpClient::endOfBodyReached | Check 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(Client& aClient, const char* aProxy = NULL, uint16_t aProxyPort = 0);
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
NA
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included 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 beginRequest(void);
Parameters
NA
Returns
NA
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included 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 endRequest(void);
Parameters
NA
Returns
NA
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included 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”, DNS lookup will not be performed and just purely connect to the given IP address.
Syntax
int get(const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aUserAgent = NULL);
int get(const char* aServerName, const char* aURLPath, const char* aUserAgent = NULL);
int get(const IPAddress& aServerAddress, const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aUserAgent = NULL);
int 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
This function returns 0 if successful, else returns an error.
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included 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”, DNS lookup will not be performed and just purely connect to the given IP address.
Syntax
int post(const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aUserAgent = NULL);
int post(const char* aServerName, const char* aURLPath, const char* aUserAgent = NULL);
int post(const IPAddress& aServerAddress, const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aUserAgent = NULL);
int 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. Default value: NULL.
aServerAddress: IP address of the server to connect to.
Returns
This function returns 0 if successful, else returns error.
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included 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”, DNS lookup will not be performed and just connect to the given IP address.
Syntax
int put(const char* aServerName, uint16_t aServerPort,const char* aURLPath, const char* aUserAgent = NULL);
int put(const char* aServerName, const char* aURLPath, const char* aUserAgent = NULL);
int put(const IPAddress& aServerAddress,const char* aServerName, uint16_t aServerPort, const char* aURLPath, const char* aUserAgent = NULL);
int 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. Default value: NULL.
aServerAddress: IP address of the server to connect to.
Returns
This function returns 0 if successful, else returns error.
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included to use the class function.
HttpClient::startRequest
Description
Connect to the server and start to send the request.
Syntax
int startRequest(const char* aServerName, uint16_t aServerPort,const char* aURLPath, const char* aHttpMethod, const char* aUserAgent);
int 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
This function returns 0 if successful, else returns error.
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included to use the class function.
HttpClient::sendHeader
Description
The function sends an additional header line.
The function can only be called in between startRequest and finishRequest functions.
The other 2 functions,
void sendHeader(const char* aHeaderName, const char* aHeaderValue);
void sendHeader(const char* aHeaderName, const int aHeaderValue);
are alternate form from the void HttpClient::sendHeader(const char* aHeader); which takes the header name and content as separate strings. The call will add the “:” in the log to separate different header in the case of multiple headers.
Syntax
void sendHeader(const char* aHeader);
void sendHeader(const char* aHeaderName, const char* aHeaderValue);
void 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
NA
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included 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 Basic Authentication.
Syntax
void sendBasicAuth(const char* aUser, const char* aPassword);
Parameters
aUser: Username for the authorization.
aPassword: Password for the user aUser.
Returns
NA
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included 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 finishRequest(void);
Parameters
NA
Returns
NA
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included 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 responseStatusCode(void);
Parameters
NA
Returns
This function returns 0 if successful, else returns error.
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included to use the class function.
HttpClient::readHeader
Description
The function reads the next character of the response headers. This function is 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 endOfHeadersReached() is called, data return will be the same as read().
Syntax
int readHeader(void);
Parameters
NA
Returns
This function returns the next character of the response headers.
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included 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 skipResponseHeaders(void);
Parameters
NA
Returns
This function returns 0 if successful, else returns error.
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included to use the class function.
HttpClient::endOfHeadersReached
Description
Check whether the end of the headers have been reached.
Syntax
bool endOfHeadersReached(void);
Parameters
NA
Returns
This function returns true if the end of response header has reached, else false.
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included to use the class function.
HttpClient::endOfBodyReached
Description
Check 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);
bool endOfBodyReached(void);
Parameters
NA
Returns
This function returns true if the end of the body has been reached, else false.
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included to use the class function.
HttpClient::contentLength
Description
Length of the contents of the body.
Syntax
int contentLength(void);
Parameters
NA
Returns
This function returns the length of the body, in bytes.
Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/amb1_arduino/blob/dev/Arduino_package/hardware/libraries/Http/examples/SimpleHttpExample/SimpleHttpExample.ino)
Notes and Warnings
“HttpClient.h” must be included to use the class function.
