TI-RTOS Network Services  2.14.04.31
Data Structures | Macros | Typedefs | Functions
HTTP client

HTTP/1.1 client API. More...

Data Structures

struct  HTTPCli_Field
 HTTPCli request header field. More...
 
struct  HTTPCli_StatusHandler
 HTTPCli response status code handler type. More...
 
struct  HTTPCli_ContentHandler
 HTTPCli content handler type. More...
 
struct  HTTPCli_Struct
 HTTPCli instance type. More...
 
struct  HTTPCli_Params
 HTTPCli instance paramaters. More...
 

Macros

#define HTTPCli_BUF_LEN   128
 

Typedefs

typedef struct HTTPCli_Field HTTPCli_Field
 HTTPCli request header field. More...
 
typedef void(* HTTPCli_StatusCallback) (void *cli, int status)
 HTTPCli callback function for status handling. More...
 
typedef struct HTTPCli_StatusHandler HTTPCli_StatusHandler
 HTTPCli response status code handler type. More...
 
typedef int(* HTTPCli_ContentCallback) (void *cli, int status, char *body, int len, bool moreFlag)
 HTTPCli callback function for content handling. More...
 
typedef struct HTTPCli_ContentHandler HTTPCli_ContentHandler
 HTTPCli content handler type. More...
 
typedef void(* HTTPCli_RedirectCallback) (void *cli, int status, char *uri)
 HTTPCli callback function prototype for redirection handling. More...
 
typedef struct HTTPCli_Struct HTTPCli_Struct
 HTTPCli instance type. More...
 
typedef struct HTTPCli_Params HTTPCli_Params
 HTTPCli instance paramaters. More...
 
typedef HTTPCli_StructHTTPCli_Handle
 

Functions

int HTTPCli_initSockAddr (struct sockaddr *addr, const char *uri, int flags)
 Initialize the socket address structure for the given URI. 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_Handle cli, const struct sockaddr *addr, int flags, const HTTPCli_Params *params)
 Open a connection to an 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_Handle cli)
 Disconnect from the HTTP server and destroy the HTTP client instance. More...
 
HTTPCli_FieldHTTPCli_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 an HTTP 1.1 request to the HTTP server. More...
 
int HTTPCli_sendField (HTTPCli_Handle cli, const char *name, const char *value, bool lastFlag)
 Send an 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_setProxy (const struct sockaddr *addr)
 Set the proxy address. More...
 
int HTTPCli_getSocketError (HTTPCli_Handle cli)
 Get the error code from the socket/TLS layer. More...
 

HTTP Client Error Codes

#define HTTPCli_ESOCKETFAIL   (-101)
 Socket create failed. More...
 
#define HTTPCli_ECONNECTFAIL   (-102)
 Cannot connect to the remote host. More...
 
#define HTTPCli_ESENDFAIL   (-103)
 Cannot send to the remote host. More...
 
#define HTTPCli_ERECVFAIL   (-104)
 Cannot recieve data from the remote host. More...
 
#define HTTPCli_ETLSFAIL   (-105)
 Failed to configure the socket with TLS parameters. More...
 
#define HTTPCli_EHOSTNAME   (-106)
 Failed to resolve host name. More...
 
#define HTTPCli_ESENDBUFSMALL   (-107)
 Internal send buffer is not big enough. More...
 
#define HTTPCli_ERECVBUFSMALL   (-108)
 Recieve buffer is not big enough. More...
 
#define HTTPCli_EASYNCMODE   (-109)
 HTTPCli_getResponseStatus() should not be called in async mode More...
 
#define HTTPCli_ETHREADFAIL   (-110)
 Thread create failed. More...
 
#define HTTPCli_EPROXYTUNNELFAIL   (-111)
 Failed to create an HTTP tunnel through proxy. More...
 
#define HTTPCli_ERESPONSEINVALID   (-112)
 Response recieved from the server is not a valid HTTP/1.1 response. More...
 
#define HTTPCli_ECONTENTLENLARGE   (-114)
 Content length returned is too large. More...
 
#define HTTPCli_EREDIRECTURILONG   (-115)
 Redirection URI returned is too long to be read into the buffer. More...
 
#define HTTPCli_ECONTENTTYPELONG   (-116)
 Content type returned is too long to be read into buffer. More...
 
#define HTTPCli_ENOCONTENTCALLBACK   (-117)
 Recieved content type does not match any registered callback. More...
 
#define HTTPCli_ENOTCHUNKDATA   (-118)
 Data is not of chunked type. More...
 
#define HTTPCli_EINPROGRESS   (-119)
 Operation could not be completed. Try again. More...
 
#define HTTPCli_EINTERNALBUFSMALL   (-120)
 Internal instance buffer to send/recieve data is too small. More...
 
#define HTTPCli_ESETNOTIFYFAIL   (-121)
 Could not setup the notify callbacks. More...
 
#define HTTPCli_EURILENLONG   (-122)
 Input domain name length is too long to be read into buffer. More...
 
#define HTTPCli_EHOSTFIELDNOTFOUND   (-123)
 Request Field 'Host' is not found in the set array. More...
 

HTTP Client Configuration Types

#define HTTPCli_TYPE_TLS   (0x02)
 
#define HTTPCli_TYPE_IPV6   (0x04)
 

HTTP Client Field ID

Special return codes for HTTPCli_getResponseField().

#define HTTPCli_FIELD_ID_DUMMY   (-11)
 
#define HTTPCli_FIELD_ID_END   (-12)
 

Detailed Description

HTTP/1.1 client API.

This module provides an HTTP client implementation of IETF standard for HTTP/1.1 - RFC 2616 and TLS support to interact with HTTP/1.1 servers.

Features

Limitations

Deprecated Macros

The macros HTTPCli_METHOD* and HTTPCli_FIELD_NAME* have been deprecated. Use HTTPStd_* macros from the HTTP Standard Definitions link below.

For backward compatibility, the old macros can still be used if -Dti_net_http_HTTPCli__deprecated is added to the compile options.

Minimal HTTP Client library

A minimal flavor of the library without asynchronous callback support which includes status handling, content handling and redirection handling can be built. The default library has support for these features.

To rebuild the library, add "-DHTTPCli_LIBTYPE_MIN" to the compile line and rebuild. The same option has to be added on application compile line also.

See also

Examples

The basic flow of managing an HTTP client is shown in the pseudo codes below. For clarity, return values are ignored - in a real application, these should be checked for errors.

Macro Definition Documentation

#define HTTPCli_BUF_LEN   128

Modify the HTTP client object's internal buffer length and rebuild the library if needed.

#define HTTPCli_ESOCKETFAIL   (-101)

Socket create failed.

See also
HTTPCli_getSocketError()
#define HTTPCli_ECONNECTFAIL   (-102)

Cannot connect to the remote host.

See also
HTTPCli_getSocketError()
#define HTTPCli_ESENDFAIL   (-103)

Cannot send to the remote host.

See also
HTTPCli_getSocketError()
#define HTTPCli_ERECVFAIL   (-104)

Cannot recieve data from the remote host.

See also
HTTPCli_getSocketError()
#define HTTPCli_ETLSFAIL   (-105)

Failed to configure the socket with TLS parameters.

See also
HTTPCli_getSocketError()
#define HTTPCli_EHOSTNAME   (-106)

Failed to resolve host name.

#define HTTPCli_ESENDBUFSMALL   (-107)

Internal send buffer is not big enough.

Modify the SEND_BUFLEN macro in the httpcli.c and rebuild the library if needed.

#define HTTPCli_ERECVBUFSMALL   (-108)

Recieve buffer is not big enough.

The length of buffer parameter in HTTPCli_getResponseField() should be alteast 16

#define HTTPCli_EASYNCMODE   (-109)

HTTPCli_getResponseStatus() should not be called in async mode

#define HTTPCli_ETHREADFAIL   (-110)

Thread create failed.

#define HTTPCli_EPROXYTUNNELFAIL   (-111)

Failed to create an HTTP tunnel through proxy.

#define HTTPCli_ERESPONSEINVALID   (-112)

Response recieved from the server is not a valid HTTP/1.1 response.

#define HTTPCli_ECONTENTLENLARGE   (-114)

Content length returned is too large.

The length of buffer parameter in HTTPCli_getResponseField() is not sufficient

#define HTTPCli_EREDIRECTURILONG   (-115)

Redirection URI returned is too long to be read into the buffer.

Modify the URI_BUFLEN macro in the httpcli.c and rebuild the library if needed.

#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.

Modify the CONTENT_BUFLEN macro in the httpcli.c and rebuild the library if needed.

#define HTTPCli_ENOTCHUNKDATA   (-118)

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   (-122)

Input domain name length is too long to be read into buffer.

Modify the DOMAIN_BUFLEN macro in the httpcli.c and rebuild the library if needed.

#define HTTPCli_EHOSTFIELDNOTFOUND   (-123)

Request Field 'Host' is not found in the set array.

'Host' should be set in the 'fields' parameter of HTTPCli_setRequestFields(). This is used to set up an HTTP tunnel through proxy servers.

#define HTTPCli_TYPE_TLS   (0x02)
#define HTTPCli_TYPE_IPV6   (0x04)
#define HTTPCli_FIELD_ID_DUMMY   (-11)
#define HTTPCli_FIELD_ID_END   (-12)

Typedef Documentation

typedef struct HTTPCli_Field HTTPCli_Field

HTTPCli request header field.

typedef void(* HTTPCli_StatusCallback) (void *cli, int status)

HTTPCli callback function for status handling.

Parameters
[in]cliInstance of the HTTP connection
[in]statusResponse status code

HTTPCli response status code handler type.

typedef int(* HTTPCli_ContentCallback) (void *cli, int status, char *body, int len, bool moreFlag)

HTTPCli callback function for content handling.

Parameters
[in]cliInstance of the HTTP connection
[in]statusResponse status code
[in]bodyData from the response body
[in]lenLength of response body buffer
[in]moreFlagSet if more response data is available
Returns
1 to continue or 0 to stop further processing.

HTTPCli content handler type.

typedef void(* HTTPCli_RedirectCallback) (void *cli, int status, char *uri)

HTTPCli callback function prototype for redirection handling.

Parameters
[in]cliInstance of the HTTP connection
[in]statusResponse status code
[in]uriThe new URI string

HTTPCli instance type.

Remarks
This doxygen does not document all data fields. See httpcli.h for complete details.

HTTPCli instance paramaters.

Remarks
This doxygen does not document all data fields. See httpcli.h for complete details.

Function Documentation

int HTTPCli_initSockAddr ( struct sockaddr *  addr,
const char *  uri,
int  flags 
)

Initialize the socket address structure for the given URI.

The supported URI format is:

  • [http[s]://]host_name[:port_number][/request_uri]

For cases where port is not provided, the default port number is set.

Parameters
[out]addrHandle to the sockaddr structure
[in]uriA null terminated URI string
[in]flagsSet HTTPCli_TYPE_IPV6 for IPv6 addresses.
Remarks
SimpleLink stack does not support IPv6.
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]cliInstance of an 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.
int HTTPCli_connect ( HTTPCli_Handle  cli,
const struct sockaddr *  addr,
int  flags,
const HTTPCli_Params params 
)

Open a connection to an HTTP server.

Parameters
[in]cliInstance of an HTTP client
[in]addrIP address of the server. Can be NULL when proxy is set.
[in]flagsSets the type of HTTP instance (ex: HTTPCli_TYPE_TLS). Multiple types can be OR'ed together.
[in]paramsPer-instance config params, or NULL for default values
Returns
0 on success or error code on failure.
void HTTPCli_delete ( HTTPCli_Handle cli)

Destory the HTTP client instance and free the previously allocated instance object.

Parameters
[in]cliPointer to the HTTP client instance
void HTTPCli_destruct ( HTTPCli_Struct cli)

Destory the HTTP client instance.

Parameters
[in]cliInstance of the HTTP client
void HTTPCli_disconnect ( HTTPCli_Handle  cli)

Disconnect from the HTTP server and destroy the HTTP client instance.

Parameters
[in]cliInstance of the HTTP client
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]cliInstance of an HTTP client
[in]fieldsAn 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 lifetime of the 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]cliInstance of an HTTP client
[in]fieldsAn 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 lifetime of the HTTP instance.
Returns
previously set array
int HTTPCli_sendRequest ( HTTPCli_Handle  cli,
const char *  method,
const char *  requestURI,
bool  moreFlag 
)

Make an HTTP 1.1 request to the HTTP server.

Sends an 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]cliInstance of an HTTP client
[in]methodHTTP 1.1 method (ex: HTTPStd_GET)
[in]requestURIthe path on the server to open and any CGI parameters
[in]moreFlagSet this flag when more fields will sent to the server
Returns
0 on success or error code on failure
int HTTPCli_sendField ( HTTPCli_Handle  cli,
const char *  name,
const char *  value,
bool  lastFlag 
)

Send an 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]cliInstance of an HTTP client
[in]nameHTTP 1.1 request header field (ex: HTTPStd_FIELD_NAME_HOST)
[in]valueHTTP 1.1 request header field value
[in]lastFlagSet this flag when sending the last header field
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]cliInstance of an HTTP client
[in]bodyRequest body buffer
[in]lenLength of the request body buffer
Returns
0 on success 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]cliInstance of an HTTP client
Returns
On success, status code from the server or error code on failure.
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 until HTTPCli_FIELD_ID_END is returned.

Parameters
[in]cliInstance of an HTTP client
[out]valueField value string.
[in]lenLength of field value string
[out]moreFlagFlag set if the field value could not be completely read into value. A subsequent call to this function will read the remaining field value into value 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_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]cliInstance of an HTTP client
[out]bodyResponse body buffer
[in]lenLength of response body buffer
[out]moreFlagSet if more data is available
Returns
The number of characters read 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 until entire response message is read.

Parameters
[in]cliInstance of an HTTP client
[out]bodyResponse body buffer
[in]lenLength of response body buffer
Returns
The number of characters read on success or error code on failure
void HTTPCli_setProxy ( const struct sockaddr *  addr)

Set the proxy address.

Parameters
[in]addrIP address of the proxy server
int HTTPCli_getSocketError ( HTTPCli_Handle  cli)

Get the error code from the socket/TLS layer.

If the returned error from the HTTPCli APIs is either a socket failure code (HTTPCli_ESOCKETFAIL or HTTPCli_ECONNECTFAIL or HTTPCli_ESENDFAIL or HTTPCli_ERECVFAIL) or a TLS failure code (HTTPCli_ETLSFAIL), a call to this function may provide the socket/TLS layer error code.

Parameters
[in]cliInstance of an HTTP client
Returns
The error code from the socket/TLS layer or zero.
Remarks
errno set by the network stacks are not returned by this function. The application has to check errno for such stacks.
Copyright 2015, Texas Instruments Incorporated