 |
HTTP Client Middleware Library
|
|
HTTP Client Middleware Library
|
C APIs provided by the HTTP Client library.
Functions | |
| cy_rslt_t | cy_http_client_init (void) |
| Initializes the Http Client library and its components. More... | |
| cy_rslt_t | cy_http_client_create (cy_awsport_ssl_credentials_t *security, cy_awsport_server_info_t *server_info, cy_http_disconnect_callback_t disconn_cb, void *user_data, cy_http_client_t *handle) |
| Creates a HTTP Client instance and initializes its members based on the input arguments. More... | |
| cy_rslt_t | cy_http_client_connect (cy_http_client_t handle, uint32_t send_timeout_ms, uint32_t receive_timeout_ms) |
| Connects to the given HTTP server and establishes a connection. More... | |
| cy_rslt_t | cy_http_client_write_header (cy_http_client_t handle, cy_http_client_request_header_t *request, cy_http_client_header_t *header, uint32_t num_header) |
| Generates the request Header used as HTTP Client request header during cy_http_client_send. More... | |
| cy_rslt_t | cy_http_client_send (cy_http_client_t handle, cy_http_client_request_header_t *request, uint8_t *payload, uint32_t payload_len, cy_http_client_response_t *response) |
| Sends the HTTP request to the server and returns the received HTTP response from the server. More... | |
| cy_rslt_t | cy_http_client_read_header (cy_http_client_t handle, cy_http_client_response_t *response, cy_http_client_header_t *header, uint32_t num_header) |
| Parses the headers received in the HTTP response. More... | |
| cy_rslt_t | cy_http_client_disconnect (cy_http_client_t handle) |
| Disconnects the HTTP Client network connection. More... | |
| cy_rslt_t | cy_http_client_delete (cy_http_client_t handle) |
| Deletes the HTTP Client library Object. More... | |
| cy_rslt_t | cy_http_client_deinit (void) |
| De-initializes the global resources used by the HTTP Client library. More... | |
| cy_rslt_t cy_http_client_init | ( | void | ) |
Initializes the Http Client library and its components.
This function must be called before using any other HTTP Client library functions.
| cy_rslt_t cy_http_client_create | ( | cy_awsport_ssl_credentials_t * | security, |
| cy_awsport_server_info_t * | server_info, | ||
| cy_http_disconnect_callback_t | disconn_cb, | ||
| void * | user_data, | ||
| cy_http_client_t * | handle | ||
| ) |
Creates a HTTP Client instance and initializes its members based on the input arguments.
The handle to the HTTP Client instance is returned via the handle pointer supplied by the user on success. This handle is used for connect, disconnect, and sending HTTP Client requests. This function must be called after calling cy_http_client_init.
| security | [in] : Credentials for TLS secure connection. For non-secure connection, set it to NULL. The application must allocate memory for keys and should not be freed until the HTTP Client object is deleted. |
| server_info | [in] : Pointer for the HTTP Client Server information required during connect and send. |
| disconn_cb | [in] : Pointer to the callback function to be invoked on disconnect. |
| user_data | [in] : User data to be sent while invoking the disconnect callback. |
| handle | [out] : Pointer to store the HTTP Client handle allocated by this function on a successful return. Caller should not free the handle directly. User needs to invoke cy_http_client_delete to free the handle. |
| cy_rslt_t cy_http_client_connect | ( | cy_http_client_t | handle, |
| uint32_t | send_timeout_ms, | ||
| uint32_t | receive_timeout_ms | ||
| ) |
Connects to the given HTTP server and establishes a connection.
This function must be called after calling cy_http_client_create.
Note: send_timeout_ms & receive_timeout_ms timeout is used by underlying network stack to receive/send the complete data asked by application or return when timeout happens. Since application/HTTP client library is not aware about the amount of data to read from network stack it will ask for some number of bytes. If network stack has those many number of bytes available it will return immediately with number of bytes. In case when number of bytes are not available, network stack waits for data till receive_timeout_ms expires. When receive_timeout_ms value is set to higher value, network stack will wait till timeout even though the data is received. This will lead to delay in processing the HTTP response. To avoid such issues, recommendation is to configure send_timeout_ms & receive_timeout_ms in range of 100~500ms.
Now when HTTP response is larger which cannot be read/sent in timeout configured, HTTP client library provides another set of timeout which will be used by HTTP client library to keep sending/receiving remaining number of bytes till timeout occurs. HTTP client library provides HTTP_SEND_RETRY_TIMEOUT_MS & HTTP_RECV_RETRY_TIMEOUT_MS configuration which value can be set in application makefile.
| handle | [in] : HTTP Client handle created using cy_http_client_create. |
| send_timeout_ms | [in] : Socket send timeout in milliseconds. |
| receive_timeout_ms | [in] : Socket receive timeout in milliseconds. |
| cy_rslt_t cy_http_client_write_header | ( | cy_http_client_t | handle, |
| cy_http_client_request_header_t * | request, | ||
| cy_http_client_header_t * | header, | ||
| uint32_t | num_header | ||
| ) |
Generates the request Header used as HTTP Client request header during cy_http_client_send.
This function must be called after calling cy_http_client_create.
Note: This function will automatically add the host header to request buffer. Additional headers are added to the buffer based on the header and num_header arguments. If additional headers are not required, pass header as NULL and num_header as 0.
| handle | [in] : HTTP Client handle created using cy_http_client_create. |
| request | [in/out] : Pointer to the HTTP request structure. The list of HTTP request headers are stored in the HTTP protocol header format. |
| header | [in] : Pointer to the list of headers to be updated in the request buffer. |
| num_header | [in] : Indicates the number of headers in the header list. |
| cy_rslt_t cy_http_client_send | ( | cy_http_client_t | handle, |
| cy_http_client_request_header_t * | request, | ||
| uint8_t * | payload, | ||
| uint32_t | payload_len, | ||
| cy_http_client_response_t * | response | ||
| ) |
Sends the HTTP request to the server and returns the received HTTP response from the server.
This function must be called after calling cy_http_client_connect. This API will return if the data is not sent or the response is not received within the timeout configured in cy_http_client_connect. This is a synchronous API. For a given HTTP Client instance, the caller has to wait till this API returns to initiate a new cy_http_client_send.
| handle | [in] : HTTP Client handle created using cy_http_client_create. |
| request | [in] : Pointer containing the HTTP request header updated at cy_http_client_write_header. |
| payload | [in] : Pointer to the payload which must be sent with the HTTP request. |
| payload_len | [in] : Length of the payload. |
| response | [out] : Pointer updated with the response of the request with the header and body on success. |
| cy_rslt_t cy_http_client_read_header | ( | cy_http_client_t | handle, |
| cy_http_client_response_t * | response, | ||
| cy_http_client_header_t * | header, | ||
| uint32_t | num_header | ||
| ) |
Parses the headers received in the HTTP response.
This function must be called after calling cy_http_client_send. While parsing the headers from the response, if any error occurs, the particular header/value entries in the output array will have the value and length fields set to NULL and 0 respectively.
| handle | [in] : HTTP Client handle created using cy_http_client_create. |
| response | [in] : Pointer to the HTTP response updated during cy_http_client_send. |
| header | [out] : Pointer to the header list to store the header fields parsed from the response. |
| num_header | [in] : Indicates the number of headers to be parsed. |
| cy_rslt_t cy_http_client_disconnect | ( | cy_http_client_t | handle | ) |
Disconnects the HTTP Client network connection.
This function must be called after calling cy_http_client_connect.
| handle | [in] : HTTP Client handle created using cy_http_client_create. |
| cy_rslt_t cy_http_client_delete | ( | cy_http_client_t | handle | ) |
Deletes the HTTP Client library Object.
Frees the resources assigned during object creation. This function must be called after calling cy_http_client_create.
| handle | [in] : HTTP Client handle created using cy_http_client_create. |
| cy_rslt_t cy_http_client_deinit | ( | void | ) |
De-initializes the global resources used by the HTTP Client library.
Removes the resources assigned for the library during initialization.