This is the documentation for the latest (main) development branch. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

HTTP Client API Reference

API reference

wm_http_client_t wm_http_client_open_request(const wm_http_client_config_t *client_config)

Allocate memory for a new HTTP Session.

Parameters:

client_config – HTTP config.

Returns:

HTTP Session handle

int wm_http_client_close_request(wm_http_client_t *session)

Closes any active connection and free any used memory.

Parameters:

session – HTTP client handle.

Returns:

HTTP Status

int wm_http_client_set_no_cache(wm_http_client_t session, bool no_cache)

Set the HTTP client to tell the browser that it does not cache directly, but must request it from the server.

Parameters:

  • session – HTTP client handle.

  • no_cache – TRUE: enable no_cache header. FALSE: disable no_cache header.

Returns:

HTTP Status

int wm_http_client_set_keepalive(wm_http_client_t session, bool keepalive)

Set the keepalive on the HTTP client.

Parameters:

  • session – HTTP client handle.

  • keepalive – TRUE: enable keepalive header. FALSE: disable keepalive header.

Returns:

HTTP Status

int wm_http_client_set_auth(wm_http_client_t session, wm_http_auth_schema_t auth_schema, void *reserved)

Sets the HTTP authentication schema.

Parameters:

  • session – HTTP client handle.

  • auth_schema – HTTP Supported authentication methods.

  • reserved – Reserved parameter.

Returns:

HTTP Status

int wm_http_client_set_credentials(wm_http_client_t session, char *user_name, char *password)

Sets credentials for the target host.

Parameters:

  • session – HTTP client handle.

  • user_name – User name.

  • password – Password.

Returns:

HTTP Status

int wm_http_client_set_proxy(wm_http_client_t session, char *proxy_name, UINT16 port, char *user_name, char *password)

Sets all the proxy related parameters.

Parameters:

  • session – HTTP client handle.

  • proxy_name – The host name.

  • port – The proxy port number.

  • user_name – User name for proxy authentication (can be null).

  • password – User password for proxy authentication (can be null).

Returns:

HTTP Status

int wm_http_client_set_verb(wm_http_client_t session, wm_http_request_type_e http_verb)

Sets the HTTP verb for the outgoing request.

Parameters:

  • session – HTTP client handle.

  • http_verb – HTTP supported verbs.

Returns:

HTTP Status

int wm_http_client_add_request_headers(wm_http_client_t session, char *header_name, char *header_data)

Add headers to the outgoing request.

Parameters:

  • session – HTTP client handle.

  • header_name – The Headers name.

  • header_data – The headers data.

Returns:

HTTP Status

int wm_http_client_send_request(wm_http_client_t session, char *url, void *data, uint32_t data_len, bool total_len, uint32_t time_out, uint32_t client_port)

This function builds the request headers, performs a DNS resolution , opens the connection (if it was not opened yet by a previous request or if it has closed) and sends the request headers.

Parameters:

  • session – HTTP client handle.

  • url – The requested URL.

  • data – Data to post to the server.

  • data_len – Length of posted data.

  • total_len – Valid only when HTTP method is post. TRUE: Post data to HTTP server. FALSE: In a post request without knowing the total length in advance so return error or use chunking.

  • time_out – Operation timeout.

  • client_port – Client side port 0 for none.

Returns:

HTTP Status

int wm_http_client_write_data(wm_http_client_t session, void *buffer, uint32_t buffer_len, uint32_t time_out)

Write data to the remote server.

Parameters:

  • session – HTTP client handle.

  • buffer – Data to write to the server.

  • buffer_len – Length of wtitten data.

  • time_out – Timeout for the operation.

Returns:

HTTP Status

int wm_http_client_recv_response(wm_http_client_t session, uint32_t time_out)

Receives the response header on the connection and parses it. Performs any required authentication.

Parameters:

  • session – HTTP client handle.

  • time_out – Timeout for the operation.

Returns:

HTTP Status

int wm_http_client_read_data(wm_http_client_t session, void *buffer, uint32_t bytes_to_read, uint32_t time_out, uint32_t *bytes_recived)

Read data from the server. Parse out the chunks data.

Parameters:

  • session – [in] HTTP client handle.

  • buffer – [out] A pointer to a buffer that will be filled with the servers response.

  • bytes_to_read – [in] The size of the buffer (numbers of bytes to read).

  • time_out – [in] Timeout for the operation.

  • bytes_recived – [out] Count of the bytes that were received in this operation.

Returns:

HTTP Status

int wm_http_client_get_info(wm_http_client_t session, wm_http_client_info_t *http_client)

Fill the users structure with the session information.

Parameters:

  • session – [in] HTTP client handle.

  • http_client – [out] The session information.

Returns:

HTTP Status

int wm_http_client_find_first_header(wm_http_client_t session, char *search_clue, char *header_buffer, uint32_t *length)

Initiate the headr searching functions and find the first header.

Parameters:

  • session – [in] HTTP client handle.

  • search_clue – [in] Search clue.

  • header_buffer – [out] A pointer to a buffer that will be filled with the header name and value.

  • length – [out] Count of the bytes that were received in this operation.

Returns:

HTTP Status

int wm_http_client_get_next_header(wm_http_client_t session, char *header_buffer, uint32_t *length)

Find the next header.

Parameters:

  • session – [in] HTTP client handle.

  • header_buffer – [out] A pointer to a buffer that will be filled with the header name and value.

  • length – [out] Count of the bytes that were received in this operation.

Returns:

HTTP Status

int wm_http_client_find_close_header(wm_http_client_t session)

Terminate a headers search session.

Parameters:

session – HTTP client handle.

Returns:

HTTP Status

Data Structure Reference

Http client APIs.

Copyright (c) 2014 Winner Microelectronics Co., Ltd.

Author

wanghf

Typedefs

typedef HTTP_SESSION_HANDLE wm_http_client_t
typedef HTTP_CLIENT wm_http_client_info_t
typedef enum wm_http_auth_achema wm_http_auth_schema_t
typedef struct wm_http_client_config wm_http_client_config_t

Enums

enum wm_http_auth_achema

Values:

enumerator WM_HTTP2_AUTH_NONE

HTTP not use authentication.

enumerator WM_HTTP2_AUTH_BASIC

HTTP use basic authentication.

enumerator WM_HTTP2_AUTH_DIGEST

HTTP use digest authentication.

enumerator WM_HTTP2_AUTH_KERBEROS

HTTP use kerberos authentication.

enumerator WM_HTTP2_AUTH_MAX

HTTP not support authentication.

enumerator WM_HTTP_AUTH_NONE

HTTP not use authentication.

enumerator WM_HTTP_AUTH_BASIC

HTTP use basic authentication.

enumerator WM_HTTP_AUTH_DIGEST

HTTP use digest authentication.

enumerator WM_HTTP_AUTH_KERBEROS

HTTP use kerberos authentication.

enumerator WM_HTTP_AUTH_MAX

HTTP not support authentication.

enum wm_http_request_type_e

Values:

enumerator WM_HTTP_REQUEST_TYPE_GET

HTTP Client GET request.

enumerator WM_HTTP_REQUEST_TYPE_HEAD

HTTP Client HEAD request.

enumerator WM_HTTP_REQUEST_TYPE_POST

HTTP Client POST request.

enumerator WM_HTTP_REQUEST_TYPE_PUT

HTTP Client PUT request.

enumerator WM_HTTP_REQUEST_TYPE_DELETE

HTTP Client DELETE request.

Functions

wm_http_client_t wm_http_client_open_request(const wm_http_client_config_t *client_config)

Allocate memory for a new HTTP Session.

Parameters:

client_config – HTTP config.

Returns:

HTTP Session handle

int wm_http_client_close_request(wm_http_client_t *session)

Closes any active connection and free any used memory.

Parameters:

session – HTTP client handle.

Returns:

HTTP Status

int wm_http_client_set_no_cache(wm_http_client_t session, bool no_cache)

Set the HTTP client to tell the browser that it does not cache directly, but must request it from the server.

Parameters:

  • session – HTTP client handle.

  • no_cache – TRUE: enable no_cache header. FALSE: disable no_cache header.

Returns:

HTTP Status

int wm_http_client_set_keepalive(wm_http_client_t session, bool keepalive)

Set the keepalive on the HTTP client.

Parameters:

  • session – HTTP client handle.

  • keepalive – TRUE: enable keepalive header. FALSE: disable keepalive header.

Returns:

HTTP Status

int wm_http_client_set_auth(wm_http_client_t session, wm_http_auth_schema_t auth_schema, void *reserved)

Sets the HTTP authentication schema.

Parameters:

  • session – HTTP client handle.

  • auth_schema – HTTP Supported authentication methods.

  • reserved – Reserved parameter.

Returns:

HTTP Status

int wm_http_client_set_credentials(wm_http_client_t session, char *user_name, char *password)

Sets credentials for the target host.

Parameters:

  • session – HTTP client handle.

  • user_name – User name.

  • password – Password.

Returns:

HTTP Status

int wm_http_client_set_proxy(wm_http_client_t session, char *proxy_name, UINT16 port, char *user_name, char *password)

Sets all the proxy related parameters.

Parameters:

  • session – HTTP client handle.

  • proxy_name – The host name.

  • port – The proxy port number.

  • user_name – User name for proxy authentication (can be null).

  • password – User password for proxy authentication (can be null).

Returns:

HTTP Status

int wm_http_client_set_verb(wm_http_client_t session, wm_http_request_type_e http_verb)

Sets the HTTP verb for the outgoing request.

Parameters:

  • session – HTTP client handle.

  • http_verb – HTTP supported verbs.

Returns:

HTTP Status

int wm_http_client_add_request_headers(wm_http_client_t session, char *header_name, char *header_data)

Add headers to the outgoing request.

Parameters:

  • session – HTTP client handle.

  • header_name – The Headers name.

  • header_data – The headers data.

Returns:

HTTP Status

int wm_http_client_send_request(wm_http_client_t session, char *url, void *data, uint32_t data_len, bool total_len, uint32_t time_out, uint32_t client_port)

This function builds the request headers, performs a DNS resolution , opens the connection (if it was not opened yet by a previous request or if it has closed) and sends the request headers.

Parameters:

  • session – HTTP client handle.

  • url – The requested URL.

  • data – Data to post to the server.

  • data_len – Length of posted data.

  • total_len – Valid only when HTTP method is post. TRUE: Post data to HTTP server. FALSE: In a post request without knowing the total length in advance so return error or use chunking.

  • time_out – Operation timeout.

  • client_port – Client side port 0 for none.

Returns:

HTTP Status

int wm_http_client_write_data(wm_http_client_t session, void *buffer, uint32_t buffer_len, uint32_t time_out)

Write data to the remote server.

Parameters:

  • session – HTTP client handle.

  • buffer – Data to write to the server.

  • buffer_len – Length of wtitten data.

  • time_out – Timeout for the operation.

Returns:

HTTP Status

int wm_http_client_recv_response(wm_http_client_t session, uint32_t time_out)

Receives the response header on the connection and parses it. Performs any required authentication.

Parameters:

  • session – HTTP client handle.

  • time_out – Timeout for the operation.

Returns:

HTTP Status

int wm_http_client_read_data(wm_http_client_t session, void *buffer, uint32_t bytes_to_read, uint32_t time_out, uint32_t *bytes_recived)

Read data from the server. Parse out the chunks data.

Parameters:

  • session – [in] HTTP client handle.

  • buffer – [out] A pointer to a buffer that will be filled with the servers response.

  • bytes_to_read – [in] The size of the buffer (numbers of bytes to read).

  • time_out – [in] Timeout for the operation.

  • bytes_recived – [out] Count of the bytes that were received in this operation.

Returns:

HTTP Status

int wm_http_client_get_info(wm_http_client_t session, wm_http_client_info_t *http_client)

Fill the users structure with the session information.

Parameters:

  • session – [in] HTTP client handle.

  • http_client – [out] The session information.

Returns:

HTTP Status

int wm_http_client_find_first_header(wm_http_client_t session, char *search_clue, char *header_buffer, uint32_t *length)

Initiate the headr searching functions and find the first header.

Parameters:

  • session – [in] HTTP client handle.

  • search_clue – [in] Search clue.

  • header_buffer – [out] A pointer to a buffer that will be filled with the header name and value.

  • length – [out] Count of the bytes that were received in this operation.

Returns:

HTTP Status

int wm_http_client_get_next_header(wm_http_client_t session, char *header_buffer, uint32_t *length)

Find the next header.

Parameters:

  • session – [in] HTTP client handle.

  • header_buffer – [out] A pointer to a buffer that will be filled with the header name and value.

  • length – [out] Count of the bytes that were received in this operation.

Returns:

HTTP Status

int wm_http_client_find_close_header(wm_http_client_t session)

Terminate a headers search session.

Parameters:

session – HTTP client handle.

Returns:

HTTP Status

struct wm_http_client_config

Public Members

char *proxy_host

HTTP proxy host name.

uint32_t use_proxy

Whether to use the HTTP proxy.

uint32_t proxy_port

HTTP proxy port name.

char *username

User name of the HTTP session.

char *password

Password of the HTTP session.

wm_http_auth_schema_t auth_type

HTTP Supported authentication methods.

wm_http_request_type_e method

Request type of the HTTP client.

uint8_t content_type

Format of HTTP data. 0: application/x-www-form-urlencoded; 1: application/json; 2: multipart/form-data; 3: text/xml; other: not set content type header.

char *user_agent

The User Agent string to send with HTTP requests.

char keep_alive

Set the keep alive header.

char no_cache

Set the no cache header.

wm_http_event_handle event_handler

client event handler.

void *priv

This is an optional temporary parameter.