HttpClient Class

Description
A class to use HttpClient

Syntax
class HttpClient

Members

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.