HttpClient Class

HttpClient Class

Description
A class to use HttpClient

Syntax
class HttpClient

Members

Public Constructors 
HttpClient::HttpClientConstructs a HttpClient object.
Public Methods 
HttpClient::stopDisconnect from the server.
HttpClient::beginRequestStart a more complex request.
HttpClient::startRequestConnect to the server and start to send the request.
HttpClient::sendHeaderSend an additional header line.
HttpClient::sendBasicAuthSend a basic authentication header.
HttpClient::finishHeadersLet the server know that we’ve reached the end of the headers.
HttpClient::endRequestEnd a more complex request.
HttpClient::responseStatusCodeGet the HTTP status code contained in the response.
HttpClient::getConnect to the server and start to send a GET request.
HttpClient::postConnect to the server and start to send a POST request.
HttpClient::putConnect to the server and start to send a PUT request.
HttpClient::skipResponseHeadersSkip any response headers to get to the body.
HttpClient::endOfBodyReachedCheck whether the end of the body has been reached.
HttpClient::readReturns the incoming byte from the server that the client is connected to.
HttpClient::readHeaderRead the next character of the response headers.
HttpClient::finishRequestFinish sending the HTTP request.
HttpClient::endOfHeadersReachedThe function reads the next character of the response headers.
HttpClient::endOfStreamCheck whether the end of the body has been reached.
HttpClient::completedCheck whether the end of the body has been reached.
HttpClient::contentLengthThis function returns the length of the body.
HttpClient::availableGet the number of bytes available for reading.
HttpClient::connectedCheck if client is connected.

HttpClient::HttpClient

Description
Constructs a HttpClient object. The macro “PROXY_ENABLED” is defined and currently disabled as introduces a dependency on DNS.h in Ethernet.

Syntax
HttpClient(Client& aClient, const char* aProxy = NULL, uint16_t aProxyPort);
HttpClient(Client& aClient);

Parameters
aClient: The object of class WiFiClient.
aProxy: The proxy name. (The default proxy name is set to “NULL”).
aProxyPort: The proxy port. (Default value: 0).

Returns
NA

Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/ambd_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::stop

Description
Disconnect from the server and reset the status.

Syntax
void stop(void);

Parameters
NA

Returns
NA

Example Code
NA

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/ambd_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/ambd_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/ambd_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/ambd_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::finishHeaders

Description
Let the server know that we’ve reached the end of the headers.

Syntax
void finishHeaders(void);

Parameters
NA

Returns
NA

Example Code
NA

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/ambd_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/ambd_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/ambd_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/ambd_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
his function returns 0 indicates “HTTP_SUCCESS”, else returns other negative error codes.
• -1: HTTP_ERROR_CONNECTION_FAILED
• -2: HTTP_ERROR_API
• -3: HTTP_ERROR_TIMED_OUT
• -4: HTTP_ERROR_INVALID_RESPONSE

Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/ambd_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 indicates “HTTP_SUCCESS”, else returns other negative error codes.
• -1: HTTP_ERROR_CONNECTION_FAILED
• -2: HTTP_ERROR_API
• -3: HTTP_ERROR_TIMED_OUT
• -4: HTTP_ERROR_INVALID_RESPONSE

Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/ambd_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/ambd_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::read

Description
Returns the incoming byte recving from the server that the client is connected to.

Syntax
int read (void);
int read(uint8_t *buf, size_t size);

Parameters
buf: buffer to hold incoming byte.
size: maximum size of the buffer.

Returns
Returns the incoming byte from the server that the client is connected to.

Example Code
NA

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/ambd_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.

Syntax
int finishRequest(void);

Parameters
NA

Returns
This function returns the blank line to signify the end of the request.

Example Code
NA

Notes and Warnings
“HttpClient.h” must be included to use the class function.

HttpClient::endOfHeadersReached

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 endOfHeadersReached(void);

Parameters
NA

Returns
This function returns true if we are at the end of the header, else false.

Example Code
NA

Notes and Warnings
“HttpClient.h” must be included to use the class function.

HttpClient::endOfStream

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 endOfStream(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/ambd_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::completed

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 completed(void);

Parameters
NA

Returns
This function returns true if the end of the body has been reached, else false.

Example Code
NA

Notes and Warnings
“HttpClient.h” must be included to use the class function.

HttpClient::contentLength

Description
This function returns the length of the body.

Syntax
int contentLength(void);

Parameters
NA

Returns
This function returns the length of the body (in bytes) or NoContentLengthHeader if no Content-Length header was returned by the server.

Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/ambd_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::available

Description
Get the number of bytes available for reading.

Syntax
int available(void);

Parameters
NA

Returns
This function returns 1 and number of bytes available for reading if there are available data, else returns 0.

Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/ambd_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::connected

Description
Check if the client is connected.

Syntax
Uint_8 connected(void);

Parameters
NA

Returns
This function returns “1” if connected, returns “0” if not connected.

Example Code
Example: SimpleHttpExample
(https://github.com/ambiot/ambd_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.

請先確認已安裝QQ通訊軟體