Network Services API
2.20.00.11
|
The HTTP client provides APIs to connect to, and communicate with, HTTP Servers. More...
Data Structures | |
struct | HTTPClient_extSecParams |
Typedefs | |
typedef struct HTTPClient_extSecParams | HTTPClient_extSecParams |
typedef int16_t(* | HTTPClient_authenticationCallback) (const char *serverAuthBuff, uint32_t serverAuthLen, char *clientAuthBuff, uint32_t *clientAuthLen) |
HTTPClient callback for server authentication handling This function is responsible for generating the value for the authorization request header. More... | |
typedef void * | HTTPClient_Handle |
Functions | |
HTTPClient_Handle | HTTPClient_create (int16_t *status, void *params) |
Allocate and initialize a new HTTPClient instance object and return its handle. More... | |
int16_t | HTTPClient_destroy (HTTPClient_Handle client) |
Destroy the HTTP client instance and free the previously allocated instance object. More... | |
int16_t | HTTPClient_connect (HTTPClient_Handle client, const char *hostName, HTTPClient_extSecParams *exSecParams, uint32_t flags) |
Open a connection to an HTTP server. A user can connect to a HTTP server using TLS,proxy or both. More... | |
int16_t | HTTPClient_disconnect (HTTPClient_Handle client) |
Disconnect from the HTTP server. More... | |
int16_t | HTTPClient_sendRequest (HTTPClient_Handle client, const char *method, const char *requestURI, const char *body, uint32_t bodyLen, uint32_t flags) |
Make an HTTP request to the HTTP server. More... | |
int16_t | HTTPClient_readResponseBody (HTTPClient_Handle client, char *body, uint32_t bodyLen, bool *moreDataFlag) |
Read the response body data from the HTTP server The function handles both oneshot and chunked body responses. More... | |
int16_t | HTTPClient_setHeader (HTTPClient_Handle client, uint32_t option, void *value, uint32_t len, uint32_t flags) |
Setting HTTP Client Header-field configurations. More... | |
int16_t | HTTPClient_getHeader (HTTPClient_Handle client, uint32_t option, void *value, uint32_t *len, uint32_t flags) |
Getting HTTP Client Header-field configurations. More... | |
int16_t | HTTPClient_setOpt (HTTPClient_Handle client, uint32_t option, void *value, uint32_t len, uint32_t flags) |
Setting HTTP Client configurations. More... | |
int16_t | HTTPClient_getOpt (HTTPClient_Handle client, uint32_t option, void *value, uint32_t *len, uint32_t flags) |
Getting HTTP Client configurations. More... | |
void | HTTPClient_setProxy (const SlNetSock_Addr_t *addr) |
Set the proxy address. More... | |
Variables | |
const char * | HTTP_METHOD_GET |
const char * | HTTP_METHOD_POST |
const char * | HTTP_METHOD_HEAD |
const char * | HTTP_METHOD_OPTIONS |
const char * | HTTP_METHOD_PUT |
const char * | HTTP_METHOD_DELETE |
const char * | HTTP_METHOD_CONNECT |
The HTTP client provides APIs to connect to, and communicate with, HTTP Servers.
To use the HTTPClient APIs, the application should include its header file as follows:
And, add the following HTTP library to the link line:
#define HTTPClient_DOMAIN_BUFLEN (100) |
#define HTTPClient_RES_HFIELD_BUFFER_SIZE (300) |
Size of the buffer which is used to store response values
#define HTTPClient_MIN_USER_WORKSPACE_SIZE (500) |
Minimum workspace size user should alloc in order to create client handle
#define HTTPClient_MAX_REDIRECTION_ATTEMPTS (3) |
#define HTTPClient_MAX_REQUEST_ATTEMPTS (2) |
#define HTTPClient_MAX_RESPONSE_HEADER_FILEDS (25) |
#define HTTPClient_PORT (80) |
#define HTTPClient_SECURE_PORT (443) |
#define HTTPClient_HFIELD_RES_AGE (0) |
#define HTTPClient_HFIELD_RES_ALLOW (1) |
#define HTTPClient_HFIELD_RES_CACHE_CONTROL (2) |
#define HTTPClient_HFIELD_RES_CONNECTION (3) |
#define HTTPClient_HFIELD_RES_CONTENT_ENCODING (4) |
#define HTTPClient_HFIELD_RES_CONTENT_LANGUAGE (5) |
#define HTTPClient_HFIELD_RES_CONTENT_LENGTH (6) |
#define HTTPClient_HFIELD_RES_CONTENT_LOCATION (7) |
#define HTTPClient_HFIELD_RES_CONTENT_RANGE (8) |
#define HTTPClient_HFIELD_RES_CONTENT_TYPE (9) |
#define HTTPClient_HFIELD_RES_DATE (10) |
#define HTTPClient_HFIELD_RES_ETAG (11) |
#define HTTPClient_HFIELD_RES_EXPIRES (12) |
#define HTTPClient_HFIELD_RES_LAST_MODIFIED (13) |
#define HTTPClient_HFIELD_RES_LOCATION (14) |
#define HTTPClient_HFIELD_RES_PROXY_AUTHENTICATE (15) |
#define HTTPClient_HFIELD_RES_RETRY_AFTER (16) |
#define HTTPClient_HFIELD_RES_SERVER (17) |
#define HTTPClient_HFIELD_RES_SET_COOKIE (18) |
#define HTTPClient_HFIELD_RES_TRAILER (19) |
#define HTTPClient_HFIELD_RES_TRANSFER_ENCODING (20) |
#define HTTPClient_HFIELD_RES_UPGRADE (21) |
#define HTTPClient_HFIELD_RES_VARY (22) |
#define HTTPClient_HFIELD_RES_VIA (23) |
#define HTTPClient_HFIELD_RES_WWW_AUTHENTICATE (24) |
#define HTTPClient_HFIELD_RES_WARNING (25) |
#define HTTPClient_REQUEST_HEADER_MASK (0x80000000) |
#define HTTPClient_HFIELD_REQ_ACCEPT (26 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_ACCEPT_CHARSET (27 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_ACCEPT_ENCODING (28 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_ACCEPT_LANGUAGE (29 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_ALLOW (HTTPClient_HFIELD_RES_ALLOW | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_AUTHORIZATION (30 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_CACHE_CONTROL (HTTPClient_HFIELD_RES_CACHE_CONTROL | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_CONNECTION (HTTPClient_HFIELD_RES_CONNECTION | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_CONTENT_ENCODING (HTTPClient_HFIELD_RES_CONTENT_ENCODING | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_CONTENT_LANGUAGE (HTTPClient_HFIELD_RES_CONTENT_LANGUAGE | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_CONTENT_LOCATION (HTTPClient_HFIELD_RES_CONTENT_LOCATION | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_CONTENT_TYPE (HTTPClient_HFIELD_RES_CONTENT_TYPE | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_COOKIE (31 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_DATE (HTTPClient_HFIELD_RES_DATE | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_EXPECT (32 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_FORWARDED (33 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_FROM (34 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_HOST (35 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_IF_MATCH (36 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_IF_MODIFIED_SINCE (37 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_IF_NONE_MATCH (38 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_IF_RANGE (39 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_IF_UNMODIFIED_SINCE (40 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_ORIGIN (41 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_PROXY_AUTHORIZATION (42 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_RANGE (43 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_TE (44 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_TRANSFER_ENCODING (HTTPClient_HFIELD_RES_TRANSFER_ENCODING | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_UPGRADE (HTTPClient_HFIELD_RES_UPGRADE | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_USER_AGENT (45 | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_VIA (HTTPClient_HFIELD_RES_VIA | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_HFIELD_REQ_WARNING (HTTPClient_HFIELD_RES_WARNING | HTTPClient_REQUEST_HEADER_MASK) |
#define HTTPClient_MAX_NUMBER_OF_HEADER_FIELDS (46) |
#define HTTPClient_REDIRECT_FEATURE (48) |
Enable / Disable redirect feature
#define HTTPClient_RESPONSE_FILTER_CLEAR (49) |
Clear response filter to default(all enabled)
#define HTTPClient_REDIRECT_TLS_DOWNGRADE (50) |
Enable / Disable the option for tls downgrade
#define HTTPClient_AUTHENTICATE_SERVER_CALLBACK (51) |
Attaches callback which will handle the server authentication response (401)
#define HTTPClient_ESENDBUFSMALL (-3001) |
Internal send buffer is not big enough.
Define HTTPClient_BUF_LEN in httpclient_internal.h and rebuild the library.
#define HTTPClient_EGETOPTBUFSMALL (-3002) |
Buffer inserted into HTTPClient_getOpt() is not big enough.
#define HTTPClient_ERESPONSEINVALID (-3003) |
Response recieved from the server is not a valid HTTP/1.1 or HTTP/1.0 response.
#define HTTPClient_EINPROGRESS (-3004) |
Operation could not be completed. Try again.
#define HTTPClient_EDOMAINBUFSMALL (-3005) |
Input domain name length is too long to be read into buffer.
Modify the HTTPClient_DOMAIN_BUFLEN and rebuild the library.
#define HTTPClient_ECBALLOCATIONFAILED (-3006) |
Allocation failed during the CB creation.
Check whether there is free memory for CB allocation.
#define HTTPClient_EBODYBUFSMALL (-3008) |
Body size is too small.
Body which was entered into the request was too small, This error won't occur if the body size will be at least HTTPClient_BUF_LEN.
#define HTTPClient_ENULLPOINTER (-3009) |
Invalid de-referencing a NULL pointer.
Check that a NULL pointer wasn't dereferenced in the function.
#define HTTPClient_EREQUESTHEADERALLOCFAILED (-3010) |
Request header allocation failed.
#define HTTPClient_EREQHEADERNOTFOUND (-3011) |
Request header wasn't found in the req header list.
#define HTTPClient_EHOSTNOTFOUND (-3012) |
Host request header wasn't found.
Host header-field is mandatory.
#define HTTPClient_ECLIENTALREADYCONNECTED (-3013) |
Client is already connected.
#define HTTPClient_ERESPONSEISNOTREDIRECTABLE (-3014) |
Response is not redirectable.
#define HTTPClient_ESENDERROR (-3015) |
Send couldn't be completed.
#define HTTPClient_EREDIRECTLOCATIONFAIL (-3016) |
Location Header fields value couldn't be read completely.
Since the "Location" header-field is essential for the redirect mechanism it is imposible to complete the redirect without it. This error indicates that the buffer for the Location header field value was too small. Enlarge HTTPClient_BUF_LEN in order to fix this error, or disable the redirect mechanism.
#define HTTPClient_ETLSDOWNGRADEISFORBIDDEN (-3017) |
TLS downgrade is forbidden.
This error indicates that after redirect occured, the server asked the client to redirect from secured server into non-secured server. This option is forbidden by default, to enable use HTTPClient_setOpt()
#define HTTPClient_EWRONGAPIPARAMETER (-3018) |
Wrong API parameter.
Wrong parameter entered into the API.
#define HTTPClient_EHOSTHEADERALREADYEXIST (-3019) |
HOST already exist.
Host header is already exist, having multiple Host headers is invalid. Remove the existing host Header.
#define HTTPClient_ENOCONNECTION (-3020) |
Client is disconnected.
SlNetSock_recv return 0 which means the client is disconnected.
#define HTTPClient_ENOTABSOLUTEURI (-3021) |
URI is not absolute.
When Host header is not found, reconnection can be established only with absolute URI.
#define HTTPClient_ECANTCREATESECATTRIB (-3022) |
Error during creation of security attribute.
Error occured during the creationg of security attribue
#define HTTPClient_IGNORE_PROXY (0x01) |
If proxy is set, this flag makes the connection without the proxy
#define HTTPClient_HOST_EXIST (0x02) |
#define HTTPClient_HFIELD_NOT_PERSISTENT (0x01) |
Header Field added is not persistent
#define HTTPClient_HFIELD_PERSISTENT (0x02) |
Header Field added is persistent
#define HTTPClient_CHUNK_START (0x01) |
Sets the client's request state into chunked body
#define HTTPClient_CHUNK_END (0x02) |
Sets the client's request state out of chunked body and sends last chunk
#define HTTPClient_DROP_BODY (0x04) |
Flushes the response body
typedef struct HTTPClient_extSecParams HTTPClient_extSecParams |
typedef int16_t(* HTTPClient_authenticationCallback) (const char *serverAuthBuff, uint32_t serverAuthLen, char *clientAuthBuff, uint32_t *clientAuthLen) |
HTTPClient callback for server authentication handling This function is responsible for generating the value for the authorization request header.
[in] | serverAuthBuff | Buffer containing authentication information (Www-Authenticate response header) received from server. |
[in] | serverAuthLen | Server authentication buffer length. |
[out] | clientAuthBuff | Buffer containing Authorization request header. |
[in,out] | clientAuthLen | Input is the maximum size of the client Authorization request header buffer (HTTPClient_BUF_LEN), Output is the actual size of the client Authorization request header buffer. |
typedef void* HTTPClient_Handle |
enum HTTP_STATUS_CODE |
HTTPClient_Handle HTTPClient_create | ( | int16_t * | status, |
void * | params | ||
) |
Allocate and initialize a new HTTPClient instance object and return its handle.
[out] | status | pointer to return status |
[in] | params | Special parameters for creating the instance (currently there are no special parameters) |
int16_t HTTPClient_destroy | ( | HTTPClient_Handle | client | ) |
Destroy the HTTP client instance and free the previously allocated instance object.
[in] | client | Pointer to the HTTP client instance |
int16_t HTTPClient_connect | ( | HTTPClient_Handle | client, |
const char * | hostName, | ||
HTTPClient_extSecParams * | exSecParams, | ||
uint32_t | flags | ||
) |
Open a connection to an HTTP server. A user can connect to a HTTP server using TLS,proxy or both.
[in] | client | Instance of an HTTP client |
[in] | hostName | IP address or URL of the HTTP server. |
[in] | exSecParams | external parameters for configuring security. |
[in] | flags | Special flags for connection:
|
int16_t HTTPClient_disconnect | ( | HTTPClient_Handle | client | ) |
Disconnect from the HTTP server.
[in] | client | Instance of the HTTP client |
int16_t HTTPClient_sendRequest | ( | HTTPClient_Handle | client, |
const char * | method, | ||
const char * | requestURI, | ||
const char * | body, | ||
uint32_t | bodyLen, | ||
uint32_t | flags | ||
) |
Make an HTTP request to the HTTP server.
Sends an HTTP request-line, header fields and body to the requested URI. After sending the request, the request function waits for the response Status and Header-Fields. According to the response status, the request function determines whether to return to user or to call a redirect/callback pre-defined function.
[in] | client | Instance of an HTTP client. |
[in] | method | HTTP method. |
[in] | requestURI | The path on the server to open. |
[in] | body | The body the user wishes to send in in the request, The body can be chunked or one body buffer. |
[in] | bodyLen | Length of the body sent in the request. |
[in] | flags | Special flags when the user wishes not to use the default settings.
|
int16_t HTTPClient_readResponseBody | ( | HTTPClient_Handle | client, |
char * | body, | ||
uint32_t | bodyLen, | ||
bool * | moreDataFlag | ||
) |
Read the response body data from the HTTP server The function handles both oneshot and chunked body responses.
Make a call to this function only after the call to HTTPClient_sendRequest().
[in] | client | Instance of an HTTP client |
[out] | body | Response body buffer |
[in] | bodyLen | Length of response body buffer |
[out] | moreDataFlag | Set if more data is available |
moreDataFlag
will be false(All data was read).int16_t HTTPClient_setHeader | ( | HTTPClient_Handle | client, |
uint32_t | option, | ||
void * | value, | ||
uint32_t | len, | ||
uint32_t | flags | ||
) |
Setting HTTP Client Header-field configurations.
[in] | client | Instance of an HTTP client |
[in] | option | Options for setting could be one of the following: -Header-Fields ID - Request - headers - sets the headers-fields which will be used in requests. Response - headers - sets the headers-fields wanted to be filtered in a response. (if no request headers are set, all the headers will be available with size constraints) |
[in] | value | Value for setting could be any related value for the corresponding option. Value can be set to NULL when request header wanted to be removed. |
[in] | len | Length of the value. |
[in] | flags | Flags for settings need be one of the following:
|
int16_t HTTPClient_getHeader | ( | HTTPClient_Handle | client, |
uint32_t | option, | ||
void * | value, | ||
uint32_t * | len, | ||
uint32_t | flags | ||
) |
Getting HTTP Client Header-field configurations.
[in] | client | Instance of an HTTP client |
[in] | option | Options for getting could be one of the following: -Header-Fields ID Response - headers - getting response headers-field value (only if value was received in a filtered response). |
[out] | value | Value for getting, could be any related value for the corresponding option. |
[in,out] | len | Inputs Length of the value and output the actual length. |
[in] | flags | Flags for getting special configurations. |
int16_t HTTPClient_setOpt | ( | HTTPClient_Handle | client, |
uint32_t | option, | ||
void * | value, | ||
uint32_t | len, | ||
uint32_t | flags | ||
) |
Setting HTTP Client configurations.
[in] | client | Instance of an HTTP client |
[in] | option | Options for setting could be one of the following: -Client instance parameters:
|
[in] | value | Value for setting could be any related value for the corresponding option. |
[in] | len | Length of the value. |
[in] | flags | Flags for settings special configurations. |
int16_t HTTPClient_getOpt | ( | HTTPClient_Handle | client, |
uint32_t | option, | ||
void * | value, | ||
uint32_t * | len, | ||
uint32_t | flags | ||
) |
Getting HTTP Client configurations.
[in] | client | Instance of an HTTP client |
[in] | option | Options for getting client settings. |
[out] | value | Value for getting, could be any related value for the corresponding option. |
[in,out] | len | Inputs Length of the value and output the actual length. |
[in] | flags | Flags for getting special configurations |
void HTTPClient_setProxy | ( | const SlNetSock_Addr_t * | addr | ) |
Set the proxy address.
[in] | addr | IP address of the proxy server |
const char* HTTP_METHOD_GET |
const char* HTTP_METHOD_POST |
const char* HTTP_METHOD_HEAD |
const char* HTTP_METHOD_OPTIONS |
const char* HTTP_METHOD_PUT |
const char* HTTP_METHOD_DELETE |
const char* HTTP_METHOD_CONNECT |