TuyaOS
|
HTTP Client Module 更多...
结构体 | |
struct | parsed_url_t |
枚举 | |
enum | http_hdr_field_sel_t { HDR_ADD_DEFAULT_USER_AGENT = 0x0001 , HDR_ADD_CONN_KEEP_ALIVE = 0x0002 , HDR_ADD_CONN_CLOSE = 0x0004 , HDR_ADD_TYPE_CHUNKED = 0x0008 , HDR_ADD_CONTENT_TYPE_JSON = 0x0010 , HDR_ADD_CONTENT_TYPE_FORM_URLENCODE = 0x0020 , HRD_ADD_DOWNLOAD_RANGE = 0x0040 , HRD_ADD_HTTP_RAW = 0x0080 } |
enum | http_method_t { HTTP_OPTIONS , HTTP_GET , HTTP_HEAD , HTTP_POST , HTTP_PUT , HTTP_DELETE , HTTP_TRACE , HTTP_CONNECT } |
enum | http_open_flags_t { TLS_ENABLE = 0x01 } |
enum | http_ver_t { HTTP_VER_1_0 , HTTP_VER_1_1 } |
enum | wm_httpc_errno { WM_SUCCESS = 0 , WM_E_INVAL , WM_FAIL , WM_E_IO , WM_E_AGAIN , WM_E_BADF , WM_E_NOMEM , WM_E_HTTPC_TCP_CONNECT_FAIL , WM_E_HTTPC_TCP_TLS_CONNECT_FAIL , WM_E_HTTPC_FILE_NOT_FOUND , WM_E_HTTPC_BAD_REQUEST , WM_E_HTTPC_TLS_NOT_ENABLED , WM_E_HTTPC_SOCKET_ERROR , WM_E_HTTPC_SOCKET_SHUTDOWN , WM_E_HTTPC_SOCKET_TIMEOUT , WM_E_HTTPC_DNS_PARSE_FAILED , WM_E_HTTPC_SOCKET_CREAT_FAILED , WM_E_HTTPC_URL_PARSE_FAILED } |
函数 | |
int | http_add_header (http_session_t handle, const http_req_t *req, const char *name, const char *value) |
void | http_close_session (http_session_t *handle) |
int | http_get_response_hdr (http_session_t handle, http_resp_t **resp) |
int | http_get_response_hdr_all (http_session_t handle, http_header_pair_t *arr, int *count) |
int | http_get_response_hdr_value (http_session_t handle, const char *header_name, char **value) |
BOOL_T | http_is_session_closed (http_session_t *handle) |
int | http_lowlevel_read (http_session_t handle, void *buf, unsigned maxlen) |
int | http_lowlevel_write (http_session_t handle, const void *buf, unsigned len) |
int | http_open_session (http_session_t *handle, const char *hostname, int flags, int retry_cnt) |
int | http_open_session_with_config (http_session_t *handle, const char *hostname, tuya_tls_config_t *tls_config, int flags, int retry_cnt) |
int | http_parse_URL (const char *URL, char *tmp_buf, int tmp_buf_len, parsed_url_t *parsed_url) |
int | http_prepare_req (http_session_t handle, const http_req_t *req, http_hdr_field_sel_t field_flags) |
int | http_read_content (http_session_t handle, void *buf, unsigned int max_len) |
UINT8_T | http_recv_timeout_get (void) |
This API is used to GET HTTP recv timeout 更多... | |
OPERATE_RET | http_recv_timeout_set (IN UINT8_T timeout_s) |
This API is used to SET HTTP recv timeout 更多... | |
UINT8_T | http_redirect_limit_get (void) |
This API is used to GET HTTP Redirect Limit Count 更多... | |
OPERATE_RET | http_redirect_limit_set (IN UINT8_T cnt) |
This API is used to SET HTTP Redirect Limit Count 更多... | |
void | http_reset_session_state (http_session_t handle) |
int | http_send_request (http_session_t handle, const http_req_t *req, int send_content) |
int | http_write_standard (http_session_t handle, const void *buf, unsigned len) |
int | httpc_write_chunked (http_session_t handle, const char *data, int len) |
HTTP Client Module
The HTTP Client module is a software component layered atop basic BSD socket API and CyaSSL (a TLS library). The HTTP Client module (hereafter called the module) provides a set of API and data structures to provide an easy way of communication with any web server supporting the HTTP protocol.
Some examples of the HTTP client users (hereafter called the users) of this module are: an email client, a websockets library, OTA firmware upgrade module, and all the myriad web services users.
The module implements a session based API. The users open a session with the server which internally sets up a TCP stream with the server. The user gets a handle to this session. All the other operations viz. sending HTTP headers, sending HTTP content, reading HTTP content, etc. are then performed on the same session through the session handle. The server also supports multiple HTTP transactions on the same server (which uses the keep-alive mechanism through persistent connections). A transaction is defined as a request and a response activity. Interleaved transactions are also supported. The module also supports chunked encoding transparently to the user.
An important feature supported by the module is HTTPS connections. This allows a user to perform his HTTP transactions securely. To help support this the module works with an external TLS library. During session open, the user optionally needs to supply a root certificate to verify the server certificate. The user can also provide the module with its own client certificate if the server is expected to do client verification. Apart from session the initialization API, the remaining API's handle secure and non-secure connections transparently to the user.
Lastly, the module also provides some API's to deal with HTTP session directly. i.e. it provides users access to the socket directly.
A typical HTTP Client usage scenario is as follows:
enum http_hdr_field_sel_t |
The OR of zero or more flags below is passed to the API http_prepare_req(). If the a flag is passed the corresponding HTTP header field is added to the HTTP header. The values added will be default ones.
enum http_open_flags_t |
enum wm_httpc_errno |
HTTPC Error Codes
int http_add_header | ( | http_session_t | handle, |
const http_req_t * | req, | ||
const char * | name, | ||
const char * | value | ||
) |
Add custom http headers to the partially generated header.
This API allows the caller to add custom headers to the partial http header generated by earlier call to http_prepare_req()
[in] | handle | Handle returned from the call to http_open_session() |
[in] | req | Structure of the type http_req_t passed earlier to http_prepare_req() |
[in] | name | The name of the field. e.g User-Agent or If-Modified-Since |
[in] | value | Value associated with the name given above. |
void http_close_session | ( | http_session_t * | handle | ) |
Close the session.
This API will close the session represented by the given handle. The socket associated with this session will be closed and thus the TCP connection with the server will be terminated. No requests on this same session will succeed after this API is called.
[in] | handle | Handle returned from the previous call to http_new_session(). The handle will be set to NULL by the callee thus effectively blocking futher requests on the same session handle. |
int http_get_response_hdr | ( | http_session_t | handle, |
http_resp_t ** | resp | ||
) |
Get the HTTP response header
This API received the response header from the server and parses it. It then populates the http_resp_t structure and returns the pointer to this structure. The structure http_resp_t is allocated by the callee.
[in] | handle | Handle returned from the call to http_new_session() |
[in,out] | resp | Pointer to a pointer of type http_resp_t .The structure will be allocated by the callee. Note that the caller does not need to free the structure allocated and returned from this API. The allocation and free is done by the callee automatically. |
int http_get_response_hdr_all | ( | http_session_t | handle, |
http_header_pair_t * | arr, | ||
int * | count | ||
) |
Get requested number of HTTP response header name-value pairs.
[in] | handle | Handle returned from the call to http_new_session() |
[in,out] | arr | A pointer that points to an array of the structure to hold the response header name-value pairs. This array needs to be pre-allocated and its pointer is to be passed, this pointer shall point to the array of requested number of response header name-value pairs. |
[in,out] | count | An integer pointer that points to the number of response header name-value pairs that the user wants. This has to be passed by the user and it is later updated to the actual number of response header name-value pairs that were filled in the array mentioned above. |
int http_get_response_hdr_value | ( | http_session_t | handle, |
const char * | header_name, | ||
char ** | value | ||
) |
Get a particular HTTP response header value.
This API parses the response header received from the server and returns the value corresponding to a given name. This can help the caller get value of a particular field not parsed automatically in http_resp_t
[in] | handle | Handle returned from the call to http_new_session |
[in] | header_name | The name of the field whose value you wish to know |
[in,out] | value | A pointer which will point to the value corresponding to the name passed as second parameter. |
BOOL_T http_is_session_closed | ( | http_session_t * | handle | ) |
Check wether the session is closed.
This API checks to see if a given session handle is closed.
[in] | handle | Handle returned from the call to http_new_session() |
int http_lowlevel_read | ( | http_session_t | handle, |
void * | buf, | ||
unsigned | maxlen | ||
) |
HTTP lowlevel read
This API is present to serve clients which want to handle the HTTP stream directly. This is useful for handling websockets for e.g.
[in] | handle | Handle returned from the call to http_new_session() |
[in,out] | buf | Pointer to an allocated buffer of size equal to or more than the value of the third parameter maxlen |
[in] | maxlen | The maximum number of bytes to be read from the network. Note that the actual read bytes can be less than this. |
int http_lowlevel_write | ( | http_session_t | handle, |
const void * | buf, | ||
unsigned | len | ||
) |
HTTP lowlevel write
This API is present to serve clients which want to handle the HTTP stream directly. This is useful for handling websockets for e.g.
[in] | handle | Handle returned from the call to http_new_session() |
[in,out] | buf | Pointer to a buffer which has the data to be written out. |
[in] | len | The number of bytes to be written to the network. |
int http_open_session | ( | http_session_t * | handle, |
const char * | hostname, | ||
int | flags, | ||
int | retry_cnt | ||
) |
Start an HTTP session.
[in,out] | handle | Pointer to a handle for the session. Will be assigned by the callee. |
[in] | hostname | Host name or IP address. The hostname should be in the format [http://]hostname[:portno][/path/to/resource]. The fields between the square brackets above are optional. The part specifying the path to resource will be ignored as it is of no use during session setup. |
[in] | flags | Pass OR of the flags mentioned in enum http_open_flags_t. |
[in] | cfg | This is a pointer of the type tls_init_config_t. Please refer to file wm-tls.h for the structure internals. This pointer will be passed verbatim to the tls API tls_session_init(). If TLS (secure connection) is not needed please pass NULL value. |
[in] | retry_cnt | There are limited sockets available due to memory constraints. A socket creation can fail if all sockets are currently used up. If the socket creation fails, http_open_session() will wait for some time and try to create the socket again for retry_cnt number of times. 0 is default value which lets the SDK decide the count. |
int http_parse_URL | ( | const char * | URL, |
char * | tmp_buf, | ||
int | tmp_buf_len, | ||
parsed_url_t * | parsed_url | ||
) |
Parse the given string into URL subcomponents.
The hostname string syntax is: [scheme://]hostname[:port][/path_to_resource?query_string::fragment_id] The fields between the square brackets above are optional.
[in] | URL | Pointer to the string containing the URL. This API will not modify this argument. |
[in] | tmp_buf | A buffer where the strings will be stored after parsing. Needs to be allocated by the caller and should be of size atleast 10 greater than size of the URL string passed as first argument. |
[in] | tmp_buf_len | Size of the caller allocated, temporary buffer sent as second argument. |
[in,out] | parsed_url | Pointer to an allocated structure. The member pointers will point to the appropriate address in the temporary buffer holding the NULL terminated string corresponding to the subcomponent. |
int http_prepare_req | ( | http_session_t | handle, |
const http_req_t * | req, | ||
http_hdr_field_sel_t | field_flags | ||
) |
Prepare the HTTP header for sending to the server.
This API will prepare an HTTP request for sending it out through http_send_request(). Calling this API is mandatory before calling http_send_request().
[in] | handle | Handle returned from the call to http_open_session() |
[in] | req | Allocated and initialized http_req_t structure. |
[in] | field_flags | Bitwise OR of flags of enum http_hdr_field_sel_t as required by the caller. |
int http_read_content | ( | http_session_t | handle, |
void * | buf, | ||
unsigned int | max_len | ||
) |
Read data content from the stream.
This API will read the data sent by the server and pass it back to the caller.
[in] | handle | Handle returned from the call to http_new_session() |
[in,out] | buf | Caller allocated buffer of size max_len |
[in] | max_len | Size of the buffer. The data read will be less than or equal to this size, depending on the size of the resource. |
UINT8_T http_recv_timeout_get | ( | void | ) |
This API is used to GET HTTP recv timeout
[in] |
OPERATE_RET http_recv_timeout_set | ( | IN UINT8_T | timeout_s | ) |
This API is used to SET HTTP recv timeout
[in] | timeout_s | timeout (unit:s) |
UINT8_T http_redirect_limit_get | ( | void | ) |
This API is used to GET HTTP Redirect Limit Count
[in] |
OPERATE_RET http_redirect_limit_set | ( | IN UINT8_T | cnt | ) |
This API is used to SET HTTP Redirect Limit Count
[in] | cnt | The count of redirect, the max value should <= REDIRECT_CNT_MAX Set as zero, means disable http redirect function. |
int http_send_request | ( | http_session_t | handle, |
const http_req_t * | req, | ||
int | send_content | ||
) |
Perform an HTTP request.
This API sends the prepared request header and content if applicable.
[in] | handle | Handle returned from the call to http_open_session() |
[in] | req | The http_req_t structure filled up with appropriate parameters. |
int httpc_write_chunked | ( | http_session_t | handle, |
const char * | data, | ||
int | len | ||
) |
HTTP write chunked
This API is used for chunked transfer encoding
[in] | handle | Handle retrieved from the call to http_open_session() |
[in] | data | Pointer to the buffer to be written. |
[in] | len | The number of bytes to be written. |