HTTP Client Library
1.00.01.04
|
HTTP/1.1 Client interface. More...
Classes | |
struct | HTTPCli_Field |
HTTPCli Request Header Field. More... | |
struct | HTTPCli_StatusHandler |
HTTPCli Response status code handlers. More... | |
struct | HTTPCli_ContentHandler |
HTTPCli Content Handler type. More... | |
struct | HTTPCli_Struct |
HTTPCli instance type. More... | |
struct | HTTPCli_Params |
HTTPCli instance paramaters. More... | |
struct | HTTPCli_SecureParams |
HTTPCli secure parameters for TLS. More... | |
Macros | |
#define | HTTPCli_BUF_LEN 128 |
#define | HTTPCli_CERT_NAME_LEN 16 |
#define | HTTPCli_ESOCKETFAIL (-101) |
Socket create failed. | |
#define | HTTPCli_ECONNECTFAIL (-102) |
Connect failed. | |
#define | HTTPCli_ESENDFAIL (-103) |
Send failed. | |
#define | HTTPCli_ERECVFAIL (-104) |
Recieve failed. | |
#define | HTTPCli_ETLSFAIL (-105) |
TLS create failed. | |
#define | HTTPCli_EHOSTNAME (-106) |
Cannot get IP address from host name. | |
#define | HTTPCli_ESENDBUFSMALL (-107) |
Send buffer is not big enough. | |
#define | HTTPCli_ERECVBUFSMALL (-108) |
Recieve buffer is not big enough. | |
#define | HTTPCli_EASYNCMODE (-109) |
Cannot call getResponseStatus in async mode. | |
#define | HTTPCli_ETHREADFAIL (-110) |
Thread create failed. | |
#define | HTTPCli_EPROXYTUNNELFAIL (-111) |
Cannot create tunnel through proxy. | |
#define | HTTPCli_ERESPONSEINVALID (-112) |
Response recieved is not HTTP/1.1 response. | |
#define | HTTPCli_ECONTENTLENLARGE (-114) |
Content length returned is too large. | |
#define | HTTPCli_EREDIRECTURILONG (-115) |
Redirection URI returned is too long to be read into buffer. | |
#define | HTTPCli_ECONTENTTYPELONG (-116) |
Content type returned is too long to be read into buffer. | |
#define | HTTPCli_ENOCONTENTCALLBACK (-117) |
Recieved content type does not match any registered callback. | |
#define | HTTPCli_ENOTCHUNKDATA (-118) |
Encoded data is not of chunked type. | |
#define | HTTPCli_EINPROGRESS (-119) |
Operation could not be completed. Try again. | |
#define | HTTPCli_EINTERNALBUFSMALL (-120) |
Internal instance buffer to send/recieve data is too small. | |
#define | HTTPCli_ESETNOTIFYFAIL (-121) |
Could not setup the notify callbacks. | |
#define | HTTPCli_EURILENLONG (-120) |
Input URI length is too long to read into buffer. | |
#define | HTTPCli_METHOD_GET "GET" |
#define | HTTPCli_METHOD_POST "POST" |
#define | HTTPCli_METHOD_HEAD "HEAD" |
#define | HTTPCli_METHOD_OPTIONS "OPTIONS" |
#define | HTTPCli_METHOD_PUT "PUT" |
#define | HTTPCli_METHOD_DELETE "DELETE" |
#define | HTTPCli_METHOD_CONNECT "CONNECT" |
#define | HTTPCli_FIELD_NAME_ACCEPT "Accept" |
#define | HTTPCli_FIELD_NAME_ACCEPT_CHARSET "Accept-Charset" |
#define | HTTPCli_FIELD_NAME_ACCEPT_ENCODING "Accept-Encoding" |
#define | HTTPCli_FIELD_NAME_ACCEPT_LANGUAGE "Accept-Language" |
#define | HTTPCli_FIELD_NAME_ACCEPT_RANGES "Accept-Ranges" |
#define | HTTPCli_FIELD_NAME_AGE "Age" |
#define | HTTPCli_FIELD_NAME_ALLOW "Allow" |
#define | HTTPCli_FIELD_NAME_AUTHORIZATION "Authorization" |
#define | HTTPCli_FIELD_NAME_CACHE_CONTROL "Cache-Control" |
#define | HTTPCli_FIELD_NAME_CONNECTION "Connection" |
#define | HTTPCli_FIELD_NAME_CONTENT_ENCODING "Content-Encoding" |
#define | HTTPCli_FIELD_NAME_CONTENT_LANGUAGE "Content-Language" |
#define | HTTPCli_FIELD_NAME_CONTENT_LENGTH "Content-Length" |
#define | HTTPCli_FIELD_NAME_CONTENT_LOCATION "Content-Location" |
#define | HTTPCli_FIELD_NAME_CONTENT_MD5 "Content-MD5" |
#define | HTTPCli_FIELD_NAME_CONTENT_RANGE "Content-Range" |
#define | HTTPCli_FIELD_NAME_CONTENT_TYPE "Content-Type" |
#define | HTTPCli_FIELD_NAME_COOKIE "Cookie" |
#define | HTTPCli_FIELD_NAME_DATE "Date" |
#define | HTTPCli_FIELD_NAME_ETAG "ETag" |
#define | HTTPCli_FIELD_NAME_EXPECT "Expect" |
#define | HTTPCli_FIELD_NAME_EXPIRES "Expires" |
#define | HTTPCli_FIELD_NAME_FROM "From" |
#define | HTTPCli_FIELD_NAME_HOST "Host" |
#define | HTTPCli_FIELD_NAME_IF_MATCH "If-Match" |
#define | HTTPCli_FIELD_NAME_IF_MODIFIED_SINCE "If-Modified-Since" |
#define | HTTPCli_FIELD_NAME_IF_NONE_MATCH "If-None-Match" |
#define | HTTPCli_FIELD_NAME_IF_RANGE "If-Range" |
#define | HTTPCli_FIELD_NAME_IF_UNMODIFIED_SINCE "If-Unmodified-Since" |
#define | HTTPCli_FIELD_NAME_LAST_MODIFIED "Last-Modified" |
#define | HTTPCli_FIELD_NAME_LOCATION "Location" |
#define | HTTPCli_FIELD_NAME_MAX_FORWARDS "Max-Forwards" |
#define | HTTPCli_FIELD_NAME_ORIGIN "Origin" |
#define | HTTPCli_FIELD_NAME_PRAGMA "Pragma" |
#define | HTTPCli_FIELD_NAME_PROXY_AUTHENTICATE "Proxy-Authenticate" |
#define | HTTPCli_FIELD_NAME_PROXY_AUTHORIZATION "Proxy-Authorization" |
#define | HTTPCli_FIELD_NAME_RANGE "Range" |
#define | HTTPCli_FIELD_NAME_REFERER "Referer" |
#define | HTTPCli_FIELD_NAME_RETRY_AFTER "Retry-After" |
#define | HTTPCli_FIELD_NAME_SERVER "Server" |
#define | HTTPCli_FIELD_NAME_TE "TE" |
#define | HTTPCli_FIELD_NAME_TRAILER "Trailer" |
#define | HTTPCli_FIELD_NAME_TRANSFER_ENCODING "Transfer-Encoding" |
#define | HTTPCli_FIELD_NAME_UPGRADE "Upgrade" |
#define | HTTPCli_FIELD_NAME_USER_AGENT "User-Agent" |
#define | HTTPCli_FIELD_NAME_VARY "Vary" |
#define | HTTPCli_FIELD_NAME_VIA "Via" |
#define | HTTPCli_FIELD_NAME_WWW_AUTHENTICATE "WWW-Authenticate" |
#define | HTTPCli_FIELD_NAME_WARNING "Warning" |
#define | HTTPCli_FIELD_NAME_X_FORWARDED_FOR "X-Forwarded-For" |
#define | HTTPCli_TYPE_TLS (0x02) |
#define | HTTPCli_TYPE_IPV6 (0x04) |
#define | HTTPCli_FIELD_ID_DUMMY (-11) |
#define | HTTPCli_FIELD_ID_END (-12) |
Typedefs | |
typedef struct HTTPCli_Field | HTTPCli_Field |
HTTPCli Request Header Field. | |
typedef void(* | HTTPCli_StatusCallback) (void *cli, int status) |
HTTPCli callback function prototype for status handling. More... | |
typedef struct HTTPCli_StatusHandler | HTTPCli_StatusHandler |
HTTPCli Response status code handlers. | |
typedef int(* | HTTPCli_ContentCallback) (void *cli, int status, char *body, int len, bool moreFlag) |
HTTPCli callback function prototype for content handling. More... | |
typedef struct HTTPCli_ContentHandler | HTTPCli_ContentHandler |
HTTPCli Content Handler type. | |
typedef void(* | HTTPCli_RedirectCallback) (void *cli, int status, char *uri) |
HTTPCli callback function prototype for redirection handling. More... | |
typedef void(* | HTTPCli_Notify) (long skt, void *cli) |
HTTPCli callback function prototype for asynchronous notify Supported for 6LoWPAN stack only. More... | |
typedef struct HTTPCli_Struct | HTTPCli_Struct |
HTTPCli instance type. | |
typedef struct HTTPCli_Params | HTTPCli_Params |
HTTPCli instance paramaters. | |
typedef struct HTTPCli_SecureParams | HTTPCli_SecureParams |
HTTPCli secure parameters for TLS. | |
typedef HTTPCli_Struct * | HTTPCli_Handle |
Functions | |
int | HTTPCli_initSockAddr (struct sockaddr *addr, const char *uri, int flags) |
Initialize the socket address structure for the given URI. Supported URI formats are: "http://www.example.com:8000", "https://www.example.com:8000", "https://www.example.com", "www.example.com:8000", "www.example.com". For cases where port is not provided, the default port number is set. More... | |
void | HTTPCli_construct (HTTPCli_Struct *cli) |
Create a new instance object in the provided structure. More... | |
HTTPCli_Handle | HTTPCli_create () |
Allocate and initialize a new instance object and return its handle. More... | |
int | HTTPCli_connect (HTTPCli_Struct *cli, const struct sockaddr *addr, int flags, const HTTPCli_Params *params) |
Open a connection to a HTTP server. More... | |
void | HTTPCli_delete (HTTPCli_Handle cli) |
Destory the HTTP client instance and free the previously allocated instance object. More... | |
void | HTTPCli_destruct (HTTPCli_Struct *cli) |
Destory the HTTP client instance. More... | |
void | HTTPCli_disconnect (HTTPCli_Struct *cli) |
Disconnect from the HTTP server and destroy the HTTP client instance. More... | |
HTTPCli_Field * | HTTPCli_setRequestFields (HTTPCli_Handle cli, const HTTPCli_Field *fields) |
Set an array of header fields to be sent for every HTTP request. More... | |
char ** | HTTPCli_setResponseFields (HTTPCli_Handle cli, const char *fields[]) |
Set the header fields to filter the response headers. More... | |
int | HTTPCli_sendRequest (HTTPCli_Handle cli, const char *method, const char *requestURI, bool moreFlag) |
Make a HTTP 1.1 request to the HTTP server. More... | |
int | HTTPCli_sendField (HTTPCli_Handle cli, const char *name, const char *value, bool lastFlag) |
Send a header field to the HTTP server. More... | |
int | HTTPCli_sendRequestBody (HTTPCli_Handle cli, const char *body, int len) |
Send the request message body to the HTTP server. More... | |
int | HTTPCli_getResponseStatus (HTTPCli_Handle cli) |
Process the response header from the HTTP server and return status. More... | |
int | HTTPCli_getResponseField (HTTPCli_Handle cli, char *value, int len, bool *moreFlag) |
Process the response header from the HTTP server and return field. More... | |
int | HTTPCli_readResponseBody (HTTPCli_Handle cli, char *body, int len, bool *moreFlag) |
Read the parsed response body data from the HTTP server. More... | |
int | HTTPCli_readRawResponseBody (HTTPCli_Handle cli, char *body, int len) |
Read the raw response message body from the HTTP server. More... | |
void | HTTPCli_setSecureParams (HTTPCli_SecureParams *sparams) |
Set the secure communication paramaters. More... | |
void | HTTPCli_setProxy (const struct sockaddr *addr) |
Set the proxy address. More... | |
Detailed Description
HTTP/1.1 Client interface.
This module provides a HTTP client implementation of IETF standard for HTTP/1.1 - RFC 2616 and TLS support to interact with HTTP/1.1 servers.
Features
- Supports GET, POST, PUT, HEAD, OPTIONS, DELETE methods, request and response headers/bodies, and redirection response handling.
- Using this module, connections can be opened/closed to HTTP servers. Each connection is an instance which can be configured with a set of repeated requests/responses parameters so that they can be used across multiple transactions.
- For supporting small memory devices, the module has been specially designed with split request/response APIs which enable sending requests and responses in smaller chunks, and static memory based APIs to eliminate the need for dynamic memory allocations.
- Supports security features which include TLS and communication through proxy.
- Supports two types of programming model: synchronous and asynchronous modes. In the default synchronous mode, an application uses APIs to make request to the server and blocks till the server responds. With asynchronous mode, a thread to handle the response is created which invokes callbacks registered with the module.
- Supports TI-RTOS NDK, SimpleLink WiFi and Linux networking stacks. At IP level supports both IPv4 and IPv6.
- Supports conditional compilation of the module to include/exclude some of the features mentioned above.
Limitations
- HTTP client on SimpleLink WiFi supports IPv4 only.
- HTTP client on TI-RTOS NDK does not support host name resolution. So the API HTTPCli_initSockAddr() does not resolve host name. The API can be used only if an IP string is passed instead of the host name.
### GET Example
POST Example
Macro Definition Documentation
#define HTTPCli_BUF_LEN 128 |
Typedef Documentation
typedef int(* HTTPCli_ContentCallback) (void *cli, int status, char *body, int len, bool moreFlag) |
HTTPCli callback function prototype for content handling.
- Parameters
-
[in] cli Instance of the HTTP connection [in] status Response status code [in] body Data from the response body [in] len Length of response body buffer [in] moreFlag Set if more response data is available
- Returns
- 1 to continue or 0 to stop further processing.
typedef void(* HTTPCli_Notify) (long skt, void *cli) |
HTTPCli callback function prototype for asynchronous notify Supported for 6LoWPAN stack only.
- Parameters
-
[in] skt socket handle [in] cli Instance of the HTTP connection
typedef void(* HTTPCli_RedirectCallback) (void *cli, int status, char *uri) |
HTTPCli callback function prototype for redirection handling.
- Parameters
-
[in] cli Instance of the HTTP connection [in] status Response status code [in] uri The new URI string
typedef void(* HTTPCli_StatusCallback) (void *cli, int status) |
HTTPCli callback function prototype for status handling.
- Parameters
-
[in] cli Instance of the HTTP connection [in] status Response status code
Function Documentation
int HTTPCli_connect | ( | HTTPCli_Struct * | cli, |
const struct sockaddr * | addr, | ||
int | flags, | ||
const HTTPCli_Params * | params | ||
) |
Open a connection to a HTTP server.
- Parameters
-
[in] cli Instance of a HTTP client [in] addr IP address of the server [in] flags Sets the type of HTTP instance (ex: HTTPCli_TYPE_TLS). Multiple types can be OR'ed together. [in] params Per-instance config params, or NULL for default values
- Returns
- 0 on success or error code on failure.
void HTTPCli_construct | ( | HTTPCli_Struct * | cli | ) |
Create a new instance object in the provided structure.
- Parameters
-
[out] cli Instance of a HTTP client
HTTPCli_Handle HTTPCli_create | ( | ) |
Allocate and initialize a new instance object and return its handle.
- Returns
- handle of the HTTP client instance on success or NULL on failure.
void HTTPCli_delete | ( | HTTPCli_Handle | cli | ) |
Destory the HTTP client instance and free the previously allocated instance object.
- Parameters
-
[in] cli Instance of the HTTP client
void HTTPCli_destruct | ( | HTTPCli_Struct * | cli | ) |
Destory the HTTP client instance.
- Parameters
-
[in] cli Instance of the HTTP client
void HTTPCli_disconnect | ( | HTTPCli_Struct * | cli | ) |
Disconnect from the HTTP server and destroy the HTTP client instance.
- Parameters
-
[in] cli Instance of the HTTP client
int HTTPCli_getResponseField | ( | HTTPCli_Handle | cli, |
char * | value, | ||
int | len, | ||
bool * | moreFlag | ||
) |
Process the response header from the HTTP server and return field.
Filters the response headers based on the array of fields (see HTTPCli_setResponseFields()).
Repeatedly call this function till HTTPCli_FIELD_ID_END is returned.
- Parameters
-
[in] cli Instance of a HTTP client [out] value Field value string. [in] len Length of field value string [out] moreFlag Flag set if the field value could not be completely read into value
. A subsequent call to this function will read the remaining field value intovalue
and will return HTTPCli_FIELD_ID_DUMMY.
- Returns
- On Success, the index of the field set in the HTTPCli_setResponseFields() or HTTPCli_FIELD_ID_END or HTTPCli_FIELD_ID_DUMMY, or error code on failure.
int HTTPCli_getResponseStatus | ( | HTTPCli_Handle | cli | ) |
Process the response header from the HTTP server and return status.
- Remarks
- Do not call in asyncronous mode. This function will return HTTPCli_EASYNCMODE.
- Parameters
-
[in] cli Instance of a HTTP client
- Returns
- The status code from the server (1xx, 2xx, 3xx, 4xx, 5xx) on success or error code on failure.
int HTTPCli_initSockAddr | ( | struct sockaddr * | addr, |
const char * | uri, | ||
int | flags | ||
) |
Initialize the socket address structure for the given URI. Supported URI formats are: "http://www.example.com:8000", "https://www.example.com:8000", "https://www.example.com", "www.example.com:8000", "www.example.com". For cases where port is not provided, the default port number is set.
- Parameters
-
[out] addr Handle to the sockaddr structure [in] uri A null terminated URI string [in] flags Set HTTPCli_TYPE_IPV6 for IPv6 addresses.
- Returns
- 0 on success or error code on failure.
int HTTPCli_readRawResponseBody | ( | HTTPCli_Handle | cli, |
char * | body, | ||
int | len | ||
) |
Read the raw response message body from the HTTP server.
Make a call to this function only after the call to HTTPCli_getResponseStatus() and HTTPCli_getResponseField().
Repeatedly call this function till entire response message is read.
- Parameters
-
[in] cli Instance of a HTTP client [out] body Response body buffer [in] len Length of response body buffer
- Returns
- The number of characters read on success or error code on failure
int HTTPCli_readResponseBody | ( | HTTPCli_Handle | cli, |
char * | body, | ||
int | len, | ||
bool * | moreFlag | ||
) |
Read the parsed response body data from the HTTP server.
This function parses the response body if the content type is chunked transfer encoding or if the content length field is returned by the HTTP server.
Make a call to this function only after the call to HTTPCli_getResponseStatus() and HTTPCli_getResponseField().
- Parameters
-
[in] cli Instance of a HTTP client [out] body Response body buffer [in] len Length of response body buffer [out] moreFlag Set if more data is available
- Returns
- The number of characters read on success or error code on failure
int HTTPCli_sendField | ( | HTTPCli_Handle | cli, |
const char * | name, | ||
const char * | value, | ||
bool | lastFlag | ||
) |
Send a header field to the HTTP server.
This is a complementary function to HTTPCli_sendRequest() when more header fields are to be sent to the server.
- Parameters
-
[in] cli Instance of a HTTP client [in] name HTTP 1.1 request header field (ex: HTTPCli_FIELD_NAME_HOST) [in] value HTTP 1.1 request header field value [in] lastFlag Set this flag when sending the last header field
- Returns
- 0 on success or error code on failure
int HTTPCli_sendRequest | ( | HTTPCli_Handle | cli, |
const char * | method, | ||
const char * | requestURI, | ||
bool | moreFlag | ||
) |
Make a HTTP 1.1 request to the HTTP server.
Sends a HTTP 1.1 request-line and the header fields from the user set array (see HTTPCli_setRequestFields()) to the server.
Additionally, more fields apart from the user set array of header fields can be sent to the server. To send more fields, set the moreFlag
when calling this function and then call HTTPCli_sendField() with more fields.
- Parameters
-
[in] cli Instance of a HTTP client [in] method HTTP 1.1 method (ex: HTTPCli_METHOD_GET) [in] requestURI the path on the server to open and any CGI parameters [in] moreFlag Set this flag when more fields will sent to the server
- Returns
- 0 on success or error code on failure
int HTTPCli_sendRequestBody | ( | HTTPCli_Handle | cli, |
const char * | body, | ||
int | len | ||
) |
Send the request message body to the HTTP server.
Make a call to this function after HTTPCli_sendRequest() (always) and HTTPCli_sendField() (if applicable).
- Parameters
-
[in] cli Instance of a HTTP client [in] body Request body buffer [in] len Length of the request body buffer
- Returns
- 0 on success or error code on failure
void HTTPCli_setProxy | ( | const struct sockaddr * | addr | ) |
Set the proxy address.
- Parameters
-
[in] addr IP address of the proxy server
HTTPCli_Field* HTTPCli_setRequestFields | ( | HTTPCli_Handle | cli, |
const HTTPCli_Field * | fields | ||
) |
Set an array of header fields to be sent for every HTTP request.
- Parameters
-
[in] cli Instance of a HTTP client [in] fields An array of HTTP request header fields terminated by an object with NULL fields, or NULL to get previously set array.
- Remarks
- The array should be persistant for the lifetime of HTTP instance.
- Returns
- previously set array
char** HTTPCli_setResponseFields | ( | HTTPCli_Handle | cli, |
const char * | fields[] | ||
) |
Set the header fields to filter the response headers.
- Parameters
-
[in] cli Instance of a HTTP client [in] fields An array of HTTP response header field strings terminated by a NULL, or NULL to get previously set array.
- Remarks
- The array should be persistant for the lifetime of HTTP instance.
- Returns
- previously set array
void HTTPCli_setSecureParams | ( | HTTPCli_SecureParams * | sparams | ) |
Set the secure communication paramaters.
- Parameters
-
[in] sparams pointer to secure communication params struct
Generated on Tue Jan 13 2015 14:42:03 for HTTP Client Library by 1.8.9.1