HTTP Client API#
HTTPc_ConfigureConnParam()#
Description#
Overwrite the Connection configuration object for HTTP client.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_ConfigureConnParam (HTTPc_CONN_CFG *p_conn_cfg)Arguments#
p_conn_cfg
Pointer to structure containing the connection parameters.
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_ConfigureMemSeg()#
Description#
Configure the memory segment that will be used to allocate internal data needed by HTTP client module instead of the default memory segment.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_ConfigureMemSeg (MEM_SEG *p_mem_seg)Arguments#
p_mem_seg
Pointer to the memory segment from which the internal data will be allocated. If DEF_NULL, the internal data will be allocated from the global Heap.
Returned Value#
None.
Notes / Warnings#
This function is optional. If it is called, it must be called before
HTTPc_Init(). If it is not called, default values will be used to initialize the module.
HTTPc_ConfigureTaskStk()#
Description#
Configure the HTTP client task stack properties to use the parameters contained in the passed structure instead of the default parameters.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_ConfigureTaskStk (CPU_STK_SIZE stk_size_elements,
void *p_stk_base)Arguments#
stk_size_elements
Size of the stack, in CPU_STK elements.
p_stk_base
Pointer to base of the stack.
Returned Value#
None.
Notes / Warnings#
This function is optional. If it is called, it must be called before
HTTPc_Init(). If it is not called, default values will be used to initialize the module.
HTTPc_ConfigureQty()#
Description#
Overwrite the Quantity configuration object for HTTP client.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_ConfigureQty (HTTPc_QTY_CFG *p_qty_cfg)Arguments#
p_qty_cfg
Pointer to a structure containing the quantity parameters.
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_Init()#
Description#
Initializes the HTTP Client Suite by following these steps :
(a) Validate Configuration.
(b) Create HTTP Client Task, if necessary.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_Init (RTOS_ERR *p_err)Arguments#
p_err
Pointer to the variable that will receive one of the following error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_ALREADY_INITRTOS_ERR_SEG_OVFRTOS_ERR_BLK_ALLOC_CALLBACKRTOS_ERR_OS_ILLEGAL_RUN_TIME
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_TaskPrioSet()#
Description#
Sets priority of the HTTP client task.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_TaskPrioSet (RTOS_TASK_PRIO prio,
RTOS_ERR *p_err)Arguments#
prio
New priority for the HTTP client task.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_INVALID_ARG
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_TaskDlySet()#
Description#
Sets delay of the HTTP client task.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_TaskDlySet (CPU_INT08U dly_ms,
RTOS_ERR *p_err)Arguments#
dly_ms
New delay in millisecond for the HTTP client task.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function.
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_ConnClose()#
Description#
Closes a persistent HTTP client connection.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_ConnClose (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_FLAGS flags,
RTOS_ERR *p_err)Arguments#
p_conn_obj
Pointer to the HTTPc Connection to close.
flags
Configuration flags :
HTTPc_FLAG_CONN_NO_BLOCK
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_INVALID_HANDLERTOS_ERR_POOL_EMPTYRTOS_ERR_BLK_ALLOC_CALLBACKRTOS_ERR_SEG_OVFRTOS_ERR_NOT_AVAILRTOS_ERR_NO_MORE_RSRCRTOS_ERR_INVALID_TYPERTOS_ERR_NET_RETRY_MAXRTOS_ERR_NET_SOCK_CLOSEDRTOS_ERR_NOT_SUPPORTEDRTOS_ERR_OS_SCHED_LOCKEDRTOS_ERR_NET_INVALID_ADDR_SRCRTOS_ERR_WOULD_OVFRTOS_ERR_NET_IF_LINK_DOWNRTOS_ERR_WOULD_BLOCKRTOS_ERR_INVALID_STATERTOS_ERR_ABORTRTOS_ERR_TIMEOUTRTOS_ERR_TXRTOS_ERR_NOT_FOUNDRTOS_ERR_NET_INVALID_CONNRTOS_ERR_RXRTOS_ERR_NOT_READYRTOS_ERR_OS_OBJ_DELRTOS_ERR_NET_NEXT_HOP
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_ConnClr()#
Description#
Clears an HTTP client connection object before the first usage.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_ConnClr (HTTPc_CONN_OBJ *p_conn_obj,
RTOS_ERR *p_err)Arguments#
p_conn_obj
Pointer to the current HTTPc Connection object.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function:
RTOS_ERR_NONERTOS_ERR_NOT_INIT
Returned Value#
None.
Notes / Warnings#
This function MUST be called before the
HTTPc_CONNobject is used for the first time.
HTTPc_ConnSetParam()#
Description#
Sets the parameters related to the HTTP Client Connection.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_ConnSetParam (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_PARAM_TYPE type,
void *p_param,
RTOS_ERR *p_err)Arguments#
p_conn
Pointer to the current HTTPc Connection object.
type
Parameter type :
HTTPc_PARAM_TYPE_SERVER_PORTHTTPc_PARAM_TYPE_PERSISTENTHTTPc_PARAM_TYPE_CONNECT_TIMEOUTHTTPc_PARAM_TYPE_INACTIVITY_TIMEOUTHTTPc_PARAM_TYPE_SECURE_COMMON_NAMEHTTPc_PARAM_TYPE_SECURE_TRUST_CALLBACKHTTPc_PARAM_TYPE_CONN_CONNECT_CALLBACKHTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK
p_param
Pointer to the parameter.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_OWNERSHIP
Returned Value#
None
Notes / Warnings#
None.
HTTPc_ConnOpen()#
Description#
Opens a new HTTP connection.
Files#
http_client.h/http_client.c
Prototype#
CPU_BOOLEAN HTTPc_ConnOpen (HTTPc_CONN_OBJ *p_conn_obj,
CPU_CHAR *p_buf,
CPU_INT16U buf_len,
CPU_CHAR *p_hostname_str,
CPU_INT16U hostname_str_len,
HTTPc_FLAGS flags,
RTOS_ERR *p_err)Arguments#
p_conn_obj
Pointer to the HTTPc Connection object to open.
p_buf
Pointer to the HTTP buffer that sends (TX) and receives (RX) data.
buf_len
Length of the HTTP buffer.
p_hostname_str
Pointer to the hostname string.
hostname_str_len
Length of the hostname string.
flags
Configuration flags :
HTTPc_FLAG_CONN_NO_BLOCK
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_OWNERSHIPRTOS_ERR_POOL_EMPTYRTOS_ERR_BLK_ALLOC_CALLBACKRTOS_ERR_SEG_OVFRTOS_ERR_NOT_AVAILRTOS_ERR_OS_ILLEGAL_RUN_TIMERTOS_ERR_NO_MORE_RSRCRTOS_ERR_OS_OBJ_DELRTOS_ERR_WOULD_BLOCKRTOS_ERR_OS_SCHED_LOCKEDRTOS_ERR_ABORTRTOS_ERR_TIMEOUTRTOS_ERR_INVALID_TYPERTOS_ERR_NOT_SUPPORTEDRTOS_ERR_FAILRTOS_ERR_NET_INVALID_ADDR_SRCRTOS_ERR_NET_IF_LINK_DOWNRTOS_ERR_INVALID_HANDLERTOS_ERR_INVALID_STATERTOS_ERR_NET_OP_IN_PROGRESSRTOS_ERR_TXRTOS_ERR_ALREADY_EXISTSRTOS_ERR_NOT_FOUNDRTOS_ERR_NET_INVALID_CONNRTOS_ERR_RXRTOS_ERR_NOT_READYRTOS_ERR_NET_ADDR_UNRESOLVEDRTOS_ERR_NET_NEXT_HOPRTOS_ERR_NET_CONN_CLOSED_FAULT
Returned Value#
DEF_OK, if the connection opening has successfully completed.DEF_FAIL, otherwise.
Notes / Warnings#
None.
HTTPc_ReqClr()#
Description#
Clears the Request object members.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_ReqClr (HTTPc_REQ_OBJ *p_req_obj,
RTOS_ERR *p_err)Arguments#
p_req_obj
Pointer to the request object to clear.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INIT
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_ReqSetParam()#
Description#
Sets a parameter related to a given HTTP Request.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_ReqSetParam (HTTPc_REQ_OBJ *p_req_obj,
HTTPc_PARAM_TYPE type,
void *p_param,
RTOS_ERR *p_err)Arguments#
p_req_obj
Pointer to the request object.
type
Parameter type :
HTTPc_PARAM_TYPE_REQ_QUERY_STR_TBLHTTPc_PARAM_TYPE_REQ_QUERY_STR_HOOKHTTPc_PARAM_TYPE_REQ_HDR_TBLHTTPc_PARAM_TYPE_REQ_HDR_HOOKHTTPc_PARAM_TYPE_REQ_FORM_TBLHTTPc_PARAM_TYPE_REQ_BODY_CONTENT_TYPEHTTPc_PARAM_TYPE_REQ_BODY_CONTENT_LENHTTPc_PARAM_TYPE_REQ_BODY_CHUNKHTTPc_PARAM_TYPE_REQ_BODY_HOOKHTTPc_PARAM_TYPE_RESP_HDR_HOOKHTTPc_PARAM_TYPE_RESP_BODY_HOOKHTTPc_PARAM_TYPE_TRANS_COMPLETE_CALLBACKHTTPc_PARAM_TYPE_TRANS_ERR_CALLBACK
p_param
Pointer to the parameter.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_OWNERSHIP
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_ReqSend()#
Description#
Sends an HTTP request.
Files#
http_client.h/http_client.c
Prototype#
CPU_BOOLEAN HTTPc_ReqSend (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTPc_RESP_OBJ *p_resp_obj,
HTTP_METHOD method,
CPU_CHAR *p_resource_path,
CPU_INT16U resource_path_len,
HTTPc_FLAGS flags,
RTOS_ERR *p_err)Arguments#
p_conn_obj
Pointer to the valid HTTPc Connection on which request will be sent.
p_req_obj
Pointer to the request to send.
p_resp_obj
Pointer to the response object that will be filled with the received response.
method
HTTP method of the request.
p_resource_path
Pointer to the complete URI (or only resource path) of the request.
resource_path_len
Resource path length.
flags
Configuration flags :
HTTPc_FLAG_REQ_NO_BLOCK
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_OWNERSHIPRTOS_ERR_BLK_ALLOC_CALLBACKRTOS_ERR_SEG_OVFRTOS_ERR_OS_SCHED_LOCKEDRTOS_ERR_NOT_AVAILRTOS_ERR_OS_ILLEGAL_RUN_TIMERTOS_ERR_POOL_EMPTYRTOS_ERR_WOULD_OVFRTOS_ERR_OS_OBJ_DELRTOS_ERR_INVALID_HANDLERTOS_ERR_WOULD_BLOCKRTOS_ERR_NO_MORE_RSRCRTOS_ERR_ABORTRTOS_ERR_TIMEOUT
Returned Value#
DEF_YES, if the HTTP Response received successfully.DEF_NO, otherwise.
Notes / Warnings#
None.
HTTPc_FormAppFmt()#
Description#
Formats an application type form based on an array containing the form fields.
Files#
http_client.h/http_client.c
Prototype#
CPU_INT32U HTTPc_FormAppFmt (CPU_CHAR *p_buf,
CPU_INT16U buf_len,
HTTPc_FORM_TBL_FIELD *p_form_tbl,
CPU_INT16U form_tbl_size,
RTOS_ERR *p_err)Arguments#
p_buf
Pointer to the buffer where the form will be written.
buf_len
Buffer length.
p_form_tbl
Pointer to the form field's table.
form_tbl_size
Table size.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_INVALID_TYPERTOS_ERR_WOULD_OVFRTOS_ERR_FAIL
Returned Value#
Length of the formatted form, if no errors. 0 , otherwise.
Notes / Warnings#
To format the form, only standard Key-Value Pair objects are supported in the table.
HTTPc_FormMultipartFmt()#
Description#
Formats a multipart type form based on an array containing the form fields.
Files#
http_client.h/http_client.c
Prototype#
CPU_INT32U HTTPc_FormMultipartFmt (CPU_CHAR *p_buf,
CPU_INT16U buf_len,
HTTPc_FORM_TBL_FIELD *p_form_tbl,
CPU_INT16U form_tbl_size,
RTOS_ERR *p_err)Arguments#
p_buf
Pointer to the buffer where the form will be written.
buf_len
Buffer length.
p_form_tbl
Pointer to the form field's table.
form_tbl_size
Table size.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_INVALID_TYPERTOS_ERR_WOULD_OVFRTOS_ERR_FAIL
Returned Value#
Length of the formatted form, if no errors. 0 , otherwise.
Notes / Warnings#
To format the form, only standard Key-Value Pair object are supported in the table.
HTTPc_FormAddKeyVal()#
Description#
Adds a Key-Value Pair object to the form table.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_FormAddKeyVal (HTTPc_FORM_TBL_FIELD *p_form_tbl,
HTTPc_KEY_VAL *p_key_val,
RTOS_ERR *p_err)Arguments#
p_form_tbl
Pointer to the the form table.
p_kvp
Pointer to the Key-Value Pair object to put in table.
p_err
Pointer to the the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONE
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_FormAddKeyValExt()#
Description#
Adds an Extended Key-Value Pair object to the form table.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_FormAddKeyValExt (HTTPc_FORM_TBL_FIELD *p_form_tbl,
HTTPc_KEY_VAL_EXT *p_key_val_ext,
RTOS_ERR *p_err)Arguments#
p_form_tbl
Pointer to the form table.
p_key_val_ext
Pointer to the Extended Key-Value Pair object to put in table.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONE
Returned Value#
None.
Notes / Warnings#
HTTPc_KVP_BIGtype object allows you to setup a Hook function that will be called when the form is sent. This lets the application write the value directly into the buffer.
HTTPc_FormAddFile()#
Description#
Adds a multipart file object to the form table.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_FormAddFile (HTTPc_FORM_TBL_FIELD *p_form_tbl,
HTTPc_MULTIPART_FILE *p_file_obj,
RTOS_ERR *p_err)Arguments#
p_form_tbl
Pointer to the form table.
p_file_obj
Pointer to the multipart file object to put in table.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONE
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_WebSockSetParam()#
Description#
Sets a parameter related to a given WebSocket object.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_WebSockSetParam (HTTPc_WEBSOCK_OBJ *p_ws_obj,
HTTPc_PARAM_TYPE type,
void *p_param,
RTOS_ERR *p_err)Arguments#
p_ws_obj
Pointer to the WebSocket object.
type
Parameter type :
HTTPc_PARAM_TYPE_WEBSOCK_ON_OPENHTTPc_PARAM_TYPE_WEBSOCK_ON_CLOSEHTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_INITHTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_DATAHTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_COMPLETEHTTPc_PARAM_TYPE_WEBSOCK_ON_ERRHTTPc_PARAM_TYPE_WEBSOCK_ON_PONG
p_param
Pointer to the parameter.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_OWNERSHIP
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_WebSockMsgSetParam()#
Description#
Sets a parameter related to a given WebSocket message object.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_WebSockMsgSetParam (HTTPc_WEBSOCK_MSG_OBJ *p_msg_obj,
HTTPc_PARAM_TYPE type,
void *p_param,
RTOS_ERR *p_err)Arguments#
p_msg_obj
Pointer to the WebSocket message object.
type
Parameter type :
HTTPc_PARAM_TYPE_WEBSOCK_MSG_USER_DATAHTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_TX_INITHTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_TX_DATAHTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_TX_COMPLETE
p_param
Pointer to the parameter.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_OWNERSHIP
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_WebSockUpgrade()#
Description#
Upgrades an HTTP client connection to a WebSocket.
Files#
http_client.h/http_client.c
Prototype#
CPU_BOOLEAN HTTPc_WebSockUpgrade (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTPc_RESP_OBJ *p_resp_obj,
HTTPc_WEBSOCK_OBJ *p_ws_obj,
CPU_CHAR *p_resource_path,
CPU_INT16U resource_path_len,
HTTPc_FLAGS flags,
RTOS_ERR *p_err)Arguments#
p_conn_obj
Pointer to a valid HTTPc Connection on which request will occurred.
p_req_obj
Pointer to a request to send.
p_resp_obj
Pointer to a response object that will be filled with the received response.
p_ws_obj
Pointer to a WebSocket object.
p_resource_path
Pointer to a complete URI (or only resource path) of the request.
resource_path_len
Resource path length.
flags
Configuration flags :
HTTPc_FLAG_WEBSOCK_NO_BLOCK
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_OWNERSHIPRTOS_ERR_ALREADY_EXISTSRTOS_ERR_NET_INVALID_CONNRTOS_ERR_BLK_ALLOC_CALLBACKRTOS_ERR_SEG_OVFRTOS_ERR_OS_SCHED_LOCKEDRTOS_ERR_NOT_AVAILRTOS_ERR_OS_ILLEGAL_RUN_TIMERTOS_ERR_POOL_EMPTYRTOS_ERR_WOULD_OVFRTOS_ERR_OS_OBJ_DELRTOS_ERR_INVALID_HANDLERTOS_ERR_WOULD_BLOCKRTOS_ERR_NO_MORE_RSRCRTOS_ERR_INVALID_STATERTOS_ERR_ABORTRTOS_ERR_TIMEOUT
Returned Value#
DEF_OK, if the operation is successful.DEF_FAIL, if the operation has failed.
Notes / Warnings#
Connection Object:
(a) Since the WebSocket Upgrade handshake is based on a HTTP request, the connection object
p_conn_objMUST have already established a connection to the desired host server.Request and Response Object.
(a) Any HTTP request/response features available can be used during the WebSocket Upgrade Request.
WebSocket Upgrade related Header field
(a) During a WebSocket Upgrade handshake, the following mandatory header fields are managed by the WebSocket module and MUST NOT be set by the Application:
Connection
Upgrade
Sec-WebSocket-Key
Sec-WebSocket-Accept
Sec-WebSocket-Version
(b) During a WebSocket Upgrade Handshake, the following optional header fields MAY be managed by the Application using the standard HTTPc Request/Response API:
Sec-WebSocket-Protocol
Sec-WebSocket-Extensions
If the WebSocket Upgrade Handshake is successful, the Status Code in the response object should be '101'. This means that the Host server has switched to the WebSocket protocol. Otherwise, the response object will TYPICALLY be described the reason of the failure.
When the WebSocket Upgrade is completed, any HTTP request is no more allowed and it is not possible to switch the connection protocol to HTTP. However, if an HTTP request is required to be sent by the Application, it SHOULD do one of the following procedure:
(a) Close the current WebSocket Connection by sending a Close Frame and open again the HTTP connection.
(b) Open a different HTTP connection with the Host Server.
HTTPc_WebSockSend()#
Description#
Sends a WebSocket message.
Files#
http_client.h/http_client.c
Prototype#
CPU_BOOLEAN HTTPc_WebSockSend (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_WEBSOCK_MSG_OBJ *p_msg_obj,
HTTPc_WEBSOCK_MSG_TYPE msg_type,
CPU_CHAR *p_data,
CPU_INT32U payload_len,
HTTPc_FLAGS flags,
RTOS_ERR *p_err)Arguments#
p_conn_obj
Pointer to the valid HTTPc Connection upgraded to WebSocket.
p_msg_obj
Pointer to the valid WebSocket message object.
msg_type
Type of message to send.
p_data
Pointer to the payload to send.
payload_len
Length of the payload to send.
flags
Configuration flags :
HTTPc_FLAG_WEBSOCK_NO_BLOCK
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_OWNERSHIPRTOS_ERR_NET_INVALID_CONNRTOS_ERR_BLK_ALLOC_CALLBACKRTOS_ERR_SEG_OVFRTOS_ERR_OS_SCHED_LOCKEDRTOS_ERR_NOT_AVAILRTOS_ERR_OS_ILLEGAL_RUN_TIMERTOS_ERR_FAILRTOS_ERR_POOL_EMPTYRTOS_ERR_WOULD_OVFRTOS_ERR_OS_OBJ_DELRTOS_ERR_INVALID_HANDLERTOS_ERR_WOULD_BLOCKRTOS_ERR_NO_MORE_RSRCRTOS_ERR_ABORTRTOS_ERR_TIMEOUT
Returned Value#
DEF_OK, the operation is successful.DEF_FAIL, the operation has failed.
Notes / Warnings#
The connection object p_conn MUST has been previously upgraded to WebSocket to use this function. Refer to the
HTTPc_WebSockUpgrade()function.The available Message Types are as follows :
HTTPc_WEBSOCK_MSG_TYPE_TXT_FRAMEHTTPc_WEBSOCK_MSG_TYPE_BIN_FRAMEHTTPc_WEBSOCK_MSG_TYPE_CLOSEHTTPc_WEBSOCK_MSG_TYPE_PINGHTTPc_WEBSOCK_MSG_TYPE_PONG
Payload Content:
(a) The "Payload data" (argument p_data) is defined as "Extension data" concatenated with "Application data".
(b) Extension data length is 0 Bytes unless an extension has been negotiated during the handshake.
(c) "Extension data" content and length are defines by the extension negotiated.
(d) If negotiated, the "Extension data" must be handled by the application.
Data message Restrictions:
(a) Even if the RFC6455 allows you to sent a message payload of up to 2^64 bytes. Only 2^32 bytes is allowed in the current implementation.
Control message Restrictions:
(a) According to the RFC 6455 section 5.5:
"All control frames MUST have a payload length of 125 bytes or less and MUST NOT be fragmented."
(b) Closed frames have a specific payload format. For more information, refer to the
HTTPc_WebSockFmtCloseMsg()function.Client-to-Server Masking:
(a) According to the RFC 6455 section 5.2:
"All frames sent from the client to the server are masked by a 32-bit value that is contained within the frame."
(b) The application DO NOT need to mask the payload since it's handled by the WebSocket module.
HTTPc_WebSockClr()#
Description#
Clears an HTTPc WebSock object before its first usage.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_WebSockClr (HTTPc_WEBSOCK_OBJ *p_ws_obj,
RTOS_ERR *p_err)Arguments#
p_ws_obj
Pointer to the current HTTPc Websock object.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INIT
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_WebSockMsgClr()#
Description#
Clears an HTTPc WebSock Message object before its first usage.
Files#
http_client.h/http_client.c
Prototype#
void HTTPc_WebSockMsgClr (HTTPc_WEBSOCK_MSG_OBJ *p_msg_obj,
RTOS_ERR *p_err)Arguments#
p_msg_obj
Pointer to the WebSock Message object to clear.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INIT
Returned Value#
None.
Notes / Warnings#
None.
HTTPc_WebSockFmtCloseMsg()#
Description#
Formats a Close Frame.
Files#
http_client.h/http_client.c
Prototype#
CPU_INT16U HTTPc_WebSockFmtCloseMsg (HTTPc_WEBSOCK_CLOSE_CODE close_code,
CPU_CHAR *p_reason,
CPU_CHAR *p_buf,
CPU_INT16U buf_len,
RTOS_ERR *p_err)Arguments#
close_code
Value that defines the origin of connection closure.
p_reason
Pointer to the string that contains a reason of the connection closure.
p_buf
Pointer to the destination buffer.
buf_len
Length of the destination buffer.
p_err
Pointer to the variable that will receive one of the following error code(s) from this function :
RTOS_ERR_NONERTOS_ERR_NOT_INITRTOS_ERR_WOULD_OVF
Returned Value#
Payload length, if the operation is successful.
0, if the operation has failed.
Notes / Warnings#
Close Frames have a specific format. According to the RFC 6455 section :
"If there is a body, the first two bytes of the body MUST be a 2-byte unsigned integer (in network byte order) representing a status code with value /code/ defined in Section 7.4. Following the 2-byte integer,the body MAY contain UTF-8-encoded data with value /reason/, the interpretation of which is not defined by this specification."
The following Close Codes are available :
HTTPc_WEBSOCK_CLOSE_CODE_NORMALHTTPc_WEBSOCK_CLOSE_CODE_GOING_AWAYHTTPc_WEBSOCK_CLOSE_CODE_PROTOCOL_ERRHTTPc_WEBSOCK_CLOSE_CODE_DATA_TYPE_NOT_ALLOWEDHTTPc_WEBSOCK_CLOSE_CODE_DATA_TYPE_ERRHTTPc_WEBSOCK_CLOSE_CODE_POLICY_VIOLATIONHTTPc_WEBSOCK_CLOSE_CODE_MSG_TOO_BIGHTTPc_WEBSOCK_CLOSE_CODE_INVALID_EXTHTTPc_WEBSOCK_CLOSE_CODE_UNEXPECTED_CONDITION
Close Reason:
(a) Except for its length, the reason string has no restriction and is user-definable. This should be used for debugging purposes.
(b) This field can be empty.
HTTP Client Hook Functions#
The HTTP Client module provides a set of hook functions to notify your application and to customize the stack behavior for your application's needs. Those are only available when the HTTP Client internal task is active (HTTPc_CFG_MODE_ASYNC_TASK_EN). Here's a list of description for the different hooks type:
Hook Type | Description | Structure name | SetParam function | Must be set before calling |
|---|---|---|---|---|
Notify event about connection status |
|
|
| |
Notify event that happen during a HTTP request and allows the application to customize it. |
|
|
| |
Notify event that happen after a WebSocket Upgrade is successful and gives access to the application to the messages when received. |
|
|
| |
Notify event that happen during a WebSocket Message transmission allows the application to customize it. |
|
|
|
HTTP Client Connection Hooks#
The HTTP Client module provides a set of hook to notify the connection status to the application. Like for every hook functions, those are only available when the HTTP Client internal task is active (HTTPc_CFG_MODE_ASYNC_TASK_EN). Those hook functions can be set with the API function HTTPc_ConnSetParam() and are mandatory when the API function HTTPc_ConnOpen() is called in non-blocking mode.
Table - Connection Hooks#
Hook Function | Description |
|---|---|
Connection Hooks | |
Notify that a connection has finish the Connect process. | |
Notify that a connection has been close. |
HTTP Client On Connection Connect#
Called after a connection connect tryout with the remote HTTP server.
Like for every hook functions, it's only available when the HTTP Client internal task is active ( HTTPc_CFG_MODE_ASYNC_TASK_EN). This hook function can be set up with the API function HTTPc_ConnSetParam() with parameter type HTTPc_PARAM_TYPE_CONN_CONNECT_CALLBACK. This hook is mandatory when the API function HTTPc_ConnOpen() is called in no-blocking mode.
Prototype#
void HTTPc_ConnConnectHook (HTTPc_CONN_OBJ *p_conn_obj,
CPU_BOOLEAN open_status);Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
open_status
Status of the connection:
DEF_OK, if the connection with the server was successful.DEF_FAIL, otherwise.
Return Values#
None.
Required Configuration#
The HTTPc Internal Task must be active. Refer to HTTP Client Compile-Time Configurations for more infmicrium-ormation.
Notes / Warnings#
None.
Example Template#
Listing - Connection Connect Hook Function Example Code#
static void HTTPc_ConnConnectHook (HTTPc_CONN_OBJ *p_conn,
CPU_BOOLEAN open_status)
{
if (open_status == DEF_OK) {
printf("Connection to server succeeded.\n\r");
` } else {`
printf("Connection to server failed.\n\r");
}
}HTTP Client On Connection Close#
Called after a connection close tryout.
Like for every hook functions, it's only available when the HTTP Client internal task is active (HTTPc_CFG_MODE_ASYNC_TASK_EN). This hook is mandatory when the internal task is enabled and can be set up with the API function HTTPc_ConnSetParam() with the parameter type HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK.
Prototype#
void HTTPc_ConnCloseHook(HTTPc_CONN_OBJ *p_conn_obj,
CPU_BOOLEAN close_status,
RTOS_ERR err);Arguments#
p_conn_obj
Pointer to the current HTTPc Connection Object.
close_status
Status of the connection close:
DEF_OK, if the connection with the server was successful closed.DEF_FAIL, otherwise.
err
Internal error code when the connection was closed.
Return Values#
None.
Required Configuration#
The HTTPc Internal Task must be active. Refer to HTTP Client Compile-Time Configurations for more information.
Notes / Warnings#
None.
Example Template#
Listing - Connection Close Hook Function Example Code#
static void HTTPc_ConnCloseHook (HTTPc_CONN_OBJ *p_conn,
CPU_BOOLEAN close_status,
RTOS_ERR err)
{
printf("Connection closed with error code %i.\n\r", err.Code);
}HTTP Client Request Hooks#
The HTTP Client module provides a set of hook functions to customize the stack behavior during an HTTP Request. Hook functions are called during each HTTP transaction processing and allows to personalize the HTTP requests to send and to recover the data included in HTTP responses received. Those are only available when the HTTP Client internal task is active (HTTPc_CFG_MODE_ASYNC_TASK_EN) and can be set up with the API function HTTPc_ReqSetParam().
Table - Request Hooks#
Hook Function | Description |
|---|---|
Transaction Hooks | |
Notify that an HTTP Transaction (Request + Response) is done. | |
Notify that an error occurred during an specific HTTP Transaction. | |
Request Hooks | |
Set a Query String field (Key-Value Pair) to add to the Request. | |
Set a Header field to add to the Request. | |
Set the data to put in the Request when using the Chunked Transfer Encoding. | |
Response Hooks | |
Recover a header field received in the Response. | |
Recover each piece of data received in the Response. | |
Form Field Hooks | |
Copy the data of the value into the transmission buffer. | |
Copy the file data into the transmission buffer. |
HTTP Client On Transaction Complete#
Called after an HTTP transaction was completed.
Like for every hook functions, it's only available when the HTTP Client internal task is active (HTTPc_CFG_MODE_ASYNC_TASK_EN). This hook is not mandatory when the API function HTTPc_ReqSend() is called in blocking mode. It can be set up with the API function HTTPc_ReqSetParam() and the parameter type HTTPc_PARAM_TYPE_TRANS_COMPLETE_CALLBACK.
Prototype#
void HTTPc_TransCompleteHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTPc_RESP_OBJ *p_resp_obj,
CPU_BOOLEAN status);Arguments#
p_conn_obj
Pointer to the current HTTPc Connection Object.
p_req_obj
Pointer to the current HTTPc Request Object.
p_resp_obj
Pointer to the HTTPc Response Object fill with the data received in the HTTP response.
status
Status of the Transaction:
DEF_OK, Transaction was completed successfully.DEF_FAIL, otherwise.
Return Values#
None.
Required Configuration#
The HTTP Client Internal Task must be active. See section Run-time Configuration of the Compile-Time Configuration page.
Notes / Warnings#
None.
Example Template#
Listing - Transaction Complete Hook Function Example Code#
static void HTTPc_TransCompleteHook (HTTPc_CONN_OBJ *p_conn,
HTTPc_REQ_OBJ *p_req,
HTTPc_RESP_OBJ *p_resp,
CPU_BOOLEAN status)
{
if (status == DEF_OK) {
printf("%s\n\r", p_resp-\>ReasonPhrasePtr);
} else {
printf("Transaction failed\n\r");
}
}HTTP Client On Transaction Error#
Called after an error occurred during an HTTP transaction process.
Like for every hook functions, it's only available when the HTTP Client internal task is active ( HTTPc_CFG_MODE_ASYNC_TASK_EN ). This hook is not mandatory when the API function HTTPc_ReqSend() is called in blocking mode. This hook can be set up with the API function HTTPc_ReqSetParam() and the parameter type HTTPc_PARAM_TYPE_TRANS_ERR_CALLBACK.
Prototype#
void HTTPc_TransErrHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
RTOS_ERR err);Arguments#
p_conn_obj
Pointer to the current HTTPc Connection Object.
p_req_obj
Pointer to the current HTTPc Request Object.
err
Error code associated with the occurred error.
Return Values#
None.
Required Configuration#
The HTTP Client Internal Task must be active. See the section Compile-Time Configuration page.
Notes / Warnings#
None.
Example Template#
Listing - Transaction Error Callback Function Example Code#
static void HTTPc_TransErrHook (HTTPc_CONN_OBJ *p_conn,
HTTPc_REQ_OBJ *p_req,
RTOS_ERR err)
{
printf("Transaction error: %i\n\r", err);
}HTTP Client On Request Query String#
Called to include a Key-Value Pair to the Query String of the ongoing Request.
The parameter HTTPc_PARAM_TYPE_REQ_QUERY_STR_HOOK must be set up using the function HTTPc_ReqSetParam() for the hook function to be called.
Prototype#
CPU_BOOLEAN HTTPc_ReqQueryStrHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTPc_KEY_VAL **p_key_val);Arguments#
p_conn_obj
Pointer to the current HTTPc Connection Object.
p_req_obj
Pointer to the current HTTPc Request Object.
p_key_val
Variable that will received the pointer to the Key-Value Pair to include in the Query String.
Return Values#
DEF_YES, if all the Key-Value Pairs have been passed by the application.DEF_NO, if Key-Value Pairs remain to be passed by the application (Hook function will be called again).
Required Configuration#
The
HTTPc_CFG_QUERY_STR_ENconfiguration macro MUST be enabled.
Notes / Warnings#
The Key-Value Pair object MUST stay valid until the HTTP transaction is completed.
Example Template#
Listing - Connection Connect Callback Function Example Code#
#define HTTPc_QUERY_STR_KEY_LEN_MAX 10
#define HTTPc_QUERY_STR_VAL_LEN_MAX 20
HTTPc_KEY_VAL HTTPc_KeyVal;
CPU_CHAR HTTPc_KeyStr[HTTPc_QUERY_STR_KEY_LEN_MAX];
CPU_CHAR HTTPc_ValStr[HTTPc_QUERY_STR_VAL_LEN_MAX];
static CPU_BOOLEAN HTTPc_ReqQueryStrHook (HTTPc_CONN_OBJ *p_conn,
HTTPc_REQ_OBJ *p_req,
HTTPc_KEY_VAL **p_key_val)
{
HTTPc_KEY_VAL *p_kvp;
p_kvp = &HTTPc_KeyVal;
p_kvp-\>KeyPtr = &HTTPc_KeyStr[0];
p_kvp-\>ValPtr = &HTTPc_ValStr[0];
Str_Copy_N(p_kvp-\>KeyPtr, "Name", HTTPc_QUERY_STR_KEY_LEN_MAX);
Str_Copy_N(p_kvp-\>ValPtr, "John", HTTPc_QUERY_STR_VAL_LEN_MAX);
p_kvp-\>KeyLen = Str_Len_N(p_kvp-\>KeyPtr, HTTPc_QUERY_STR_KEY_LEN_MAX);
p_kvp-\>ValLen = Str_Len_N(p_kvp-\>ValPtr, HTTPc_QUERY_STR_VAL_LEN_MAX);
*p_key_val = p_kvp;
return (DEF_YES);
}HTTP Client On Request Header#
Called by the HTTP Client core to allow the application to include a Header Field to the ongoing HTTP Request.
The parameter HTTPc_PARAM_TYPE_REQ_HDR_HOOK must be set up using the function HTTPc_ReqSetParam() for the hook function to be called.
Prototype#
CPU_BOOLEAN HTTPc_ReqHdrHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTP_HDR **p_hdr);Arguments#
p_conn_obj
Pointer to the current HTTPc Connection Object.
p_req_obj
Pointer to the current HTTPc Request Object.
p_hdr
Variable that will received the pointer to the header field to include in the HTTP request.
Return Values#
DEF_YES, if all the header fields have been passed by the application.DEF_NO, if header fields remain to be passed by the application (Hook function will be called again).
Required Configuration#
The HTTPc_CFG_HDR_TX_EN configuration macro MUST be enabled.
Notes / Warnings#
The header field object MUST stay valid until the HTTP transaction is completed.
Example Template#
Listing - Connection Connect Callback Function Example Code#
#define HTTPc_HDR_VAL_LEN_MAX 10
HTTPc_HDR HTTPc_ReqHdr;
CPU_CHAR HTTPc_ReqHdrValStr[HTTPc_HDR_VAL_LEN_MAX];
static CPU_BOOLEAN HTTPc_ReqHdrHook (HTTPc_CONN_OBJ *p_conn,
HTTPc_REQ_OBJ *p_req,
HTTPc_HDR **p_hdr)
{
HTTPc_HDR *p_hdr_tmp;
p_hdr_tmp = &HTTPc_ReqHdr;
p_hdr_tmp-\>ValPtr = &HTTPc_ReqHdrValStr[0];
p_hdr_tmp-\>HdrField = HTTP_HDR_FIELD_COOKIE;
Str_Copy_N(p_hdr_tmp-\>ValPtr, "ID=234668", HTTPc_HDR_VAL_LEN_MAX);
p_hdr_tmp-\>ValLen = Str_Len_N(p_hdr_tmp-\>ValPtr, HTTPc_HDR_VAL_LEN_MAX);
*p_hdr = p_hdr_tmp;
return (DEF_YES);
}HTTP Client On Request Body#
Called by the HTTP Client core to retrieve from the application the body data to put in the ongoing HTTP Request.
The parameter HTTPc_PARAM_TYPE_REQ_BODY_HOOK must be set up using the function HTTPc_ReqSetParam() for the hook function to be called. This hook function is used for both the Standard Transfer (content length of body is specified) and for the Chunked Transfer Encoding .
This hook function gives the choice to set the pointer to the application data (with p_data argument) that the HTTP Client stack will take care of transferring; or to directly copy the data in the HTTP transmit buffer (with p_buf argument).
Prototype#
CPU_BOOLEAN HTTPc_ReqBodyHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
` void **p_data,`
CPU_CHAR *p_buf,
CPU_INT16U *p_buf_len
CPU_INT16U *p_data_len);Arguments#
p_conn_obj
Pointer to the current HTTPc Connection Object.
p_req_obj
Pointer to the current HTTPc Request Object.
p_data
Variable that will received the pointer to the data chunk to include in the HTTP request.
p_buf
Pointer to the HTTP transmit buffer.
buf_len
Length remaining in the HTTP transmit buffer.
p_data_len
Length of the data chunk.
Return Values#
DEF_YES, if all the data to transmit have been passed by the application.DEF_NO, if data to transmit remains to be passed by the application (Hook function will be called again).
Required Configuration#
None.
Notes / Warnings#
The data to transmit MUST stay valid until the HTTP transaction is completed.
Example Template#
Listing - Connection Connect Callback Function Example Code#
CPU_CHAR AppHTTPc_ReqBodyBuf[1024];
static CPU_BOOLEAN HTTPc_ReqBodyHook (HTTPc_CONN_OBJ *p_conn,
HTTPc_REQ_OBJ *p_req,
void **p_data,
CPU_CHAR *p_buf,
CPU_INT16U buf_len,
CPU_INT16U *p_data_len)
{
CPU_SIZE_T data_len;
data_len = App_ReadDataStream(&AppHTTPc_ReqBodyBuf); /* Theoretical application's function to read a stream of data and ... */
/* ... copy it in the buffer and return the length of data copied. */
*p_data = &AppHTTPc_ReqBodyBuf;
*p_data_len = data_len;
if (data_len == 0) {
return (DEF_YES);
} else {
return (DEF_NO);
}
}HTTP Client On Response Header#
Called by the HTTP Client core for each header field received in the HTTP response and recognize by the HTTP Client stack.
The application can decide to copy the header received or to ignore the header in the hook function. The parameter HTTPc_PARAM_TYPE_RESP_HDR_HOOK must be set up using the function HTTPc_ReqSetParam() for the hook function to be called.
Prototype#
void HTTPc_RespHdrHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTP_HDR_FIELD hdr_field,
CPU_CHAR *p_hdr_val,
CPU_INT16U val_len);Arguments#
p_conn_obj
Pointer to the current HTTPc Connection Object.
p_req_obj
Pointer to the current HTTPc Request Object.
hdr_field
HTTP header type of the header field received in the HTTP response.
p_hdr_val
Pointer to the value string received in the Response header field.
val_len
Length of the value string.
Return Values#
None.
Required Configuration#
The
HTTPc_CFG_HDR_RX_ENconfiguration macro MUST be enabled.
Notes / Warnings#
None.
Example Template#
Listing - Connection Connect Callback Function Example Code#
HTTPc_HDR AppHTTPc_RespHdr;
CPU_CHAR AppHTTPc_RespHdrValBuf[100];
static void HTTPc_RespHdrHook (HTTPc_CONN_OBJ *p_conn,
HTTPc_REQ_OBJ *p_req,
HTTP_HDR_FIELD hdr_field,
CPU_CHAR *p_hdr_val,
CPU_INT16U val_len)
{
HTTPc_HDR *p_hdr;
p_hdr = &AppHTTPc_RespHdr;
p_hdr-\>ValPtr = &AppHTTPc_RespHdrValBuf;
switch (hdr_field) {
case HTTP_HDR_FIELD_COOKIE:
p_hdr-\>HdrField = hdr_field;
Str_Copy_N(p_hdr-\>ValPtr, p_hdr_val, val_len);
p_hdr-\>ValLen = val_len;
break;
default:`
break;
}
}HTTP Client On Response Body#
Called by the HTTP Client core when body's data of the HTTP response is received.
The parameter HTTPc_PARAM_TYPE_RESP_BODY_HOOK must be set up using the function HTTPc_ReqSetParam() for the hook function to be called.
Prototype#
CPU_INT32U HTTPc_RespBodyHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTP_CONTENT_TYPE content_type,
void *p_data,
CPU_INT32U data_len,
CPU_BOOLEAN last_chunk);Arguments#
p_conn_obj
Pointer to the current HTTPc Connection Object.
p_req_obj
Pointer to the current HTTPc Request Object.
content_type
HTTP Content Type of the HTTP Response body's data.
p_data
Pointer to a data piece of the HTTP Response body.
p_data_len
Length of the data piece received.
last_chunk
DEF_YES, if this is the last piece of data.DEF_NO, if more data is up coming.
Return Values#
The number of bytes read during the callback.
Required Configuration#
None.
Notes / Warnings#
None.
Example Template#
Listing - Connection Connect Callback Function Example Code#
static void HTTPc_RespBodyHook (HTTPc_CONN_OBJ *p_conn,
HTTPc_REQ_OBJ *p_req,
HTTP_CONTENT_TYPE content_type,
void *p_data,
CPU_INT32U data_len,
CPU_BOOLEAN last_chunk)
{
FS_FILE_HANDLE file_handle;
FS_FLAGS fs_flags;
CPU_SIZE_T size_wr;
CPU_SIZE_T size_wr_tot;
FS_ENTRY_INFO entry_info;
RTOS_ERR err;
file_handle = (FS_FILE_HANDLE)p_req-\>UserDataPtr;
FSFile_Query(file_handle,
&entry_info,
&err);
if (err.Code = RTOS_ERR_ENTRY_CLOSED) {
fs_flags = 0;
DEF_BIT_SET(fs_flags, FS_FILE_ACCESS_MODE_WR);
DEF_BIT_SET(fs_flags, FS_FILE_ACCESS_MODE_CREATE);
DEF_BIT_SET(fs_flags, FS_FILE_ACCESS_MODE_TRUNCATE);
file_handle = FSFile_Open(FS_WRK_DIR_NULL,
"index.html",
fs_flags,
&err);
if (err.Code != RTOS_ERR_NONE) {
return;
}
p_req-\>UserDataPtr = (void *)file_handle;
}
switch (content_type) {
case HTTP_CONTENT_TYPE_HTML:
if (p_data != DEF_NULL) {
size_wr = 0;
size_wr_tot = 0;
while (size_wr \< data_len) {
size_wr = FSFile_Wr(file_handle,
p_data,
data_len,
&err);
if (err.Code != RTOS_ERR_NONE) {
return;
}
size_wr_tot += size_wr;
}
}
break;
case HTTP_CONTENT_TYPE_OCTET_STREAM:
case HTTP_CONTENT_TYPE_PDF:
case HTTP_CONTENT_TYPE_ZIP:
case HTTP_CONTENT_TYPE_GIF:
case HTTP_CONTENT_TYPE_JPEG:
case HTTP_CONTENT_TYPE_PNG:
case HTTP_CONTENT_TYPE_JS:
case HTTP_CONTENT_TYPE_PLAIN:
case HTTP_CONTENT_TYPE_CSS:
case HTTP_CONTENT_TYPE_JSON:
default:
break;
}
if (last_chunk == DEF_YES) {
FSFile_Close(file_handle,
&err);
}
}HTTP Client On Form Key-Value Extended#
Called by the HTTP Client core when the form table is formatted to be sent.
Each HTTPc_KEY_VAL_EXT objects contained in a table form must have set up a hook function pointer with the parameter OnValTx. The HTTPc transmit buffer pointer and the length available inside are passed as argument to allow the hook function to copy the data value directly inside the HTTPc buffer.
Prototype#
CPU_BOOLEAN HTTPc_FormKeyValExtHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTPc_KEY_VAL_EXT *p_key_val_obj,
CPU_CHAR *p_buf,
CPU_INT16U buf_len,
CPU_INT16U *p_len_wr);Arguments#
p_conn_obj
Pointer to the current HTTPc Connection Object.
p_req_obj
Pointer to the current HTTPc Request Object.
p_key_val_obj
Pointer to the Key-Value Extended object.
p_buf
Pointer to transmit buffer.
buf_len
Length available inside the transmit buffer.
p_len_wr
Data length actually written inside the buffer by the hook function.
Return Values#
DEF_YES, if all the data have been written to the buffer.DEF_NO, otherwise
Required Configuration#
None.
Notes / Warnings#
None.
Example Template#
Listing - Connection Connect Callback Function Example Code#
CPU_CHAR HTTPc_AppBuf[512];
static CPU_BOOLEAN HTTPc_FormKeyValExtHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTPc_KEY_VAL_EXT *p_key_val_obj,
CPU_CHAR *p_buf,
CPU_INT16U buf_len,
CPU_INT16U *p_len_wr);
{
HTTPc_KEY_VAL_EXT *p_field;
CPU_CHAR *p_data;
CPU_INT16U min_len;
static CPU_INT16U data_ix;
p_data = &HTTPc_AppBuf[data_ix];
min_len = DEF_MIN(buf_len, (p_key_val_obj-\>ValLen - data_ix));
if (min_len \<= 0) {
data_ix = 0;
*p_len_wr = min_len;
return (DEF_YES);
}
Str_Copy_N(p_buf, p_data, min_len);
*p_len_wr = min_len;
data_ix += min_len;
return (DEF_NO);
}This code uses a variable declared as static for example purpose. It cannot work if multiple connections call the same hook function. In that case, the UserDataPtr parameter inside the |
|---|
HTTP Client On Form Multipart File#
Called by the HTTP Client core when the form table is formatted to be sent.
Each HTTPc_MULTIPART_FILE objects contained in a table form must have set up a hook function pointer with the parameter OnFileTx. The HTTPc transmit buffer pointer and the length available inside are passed as argument to allow the hook function to copy the data file directly inside the HTTPc buffer.
Prototype#
CPU_BOOLEAN HTTPc_FormMultipartFileHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTPc_MULTIPART_FILE *p_file_obj,
CPU_CHAR *p_buf,
CPU_INT16U buf_len,
CPU_INT16U *p_len_wr);Arguments#
p_conn_obj
Pointer to the current HTTPc Connection Object.
p_req_obj
Pointer to the current HTTPc Request Object.
p_file_obj
Pointer to the Multipart File object.
p_buf
Pointer to transmit buffer.
buf_len
Length available inside the transmit buffer.
p_len_wr
Data length actually written inside the buffer by the hook function.
Return Values#
DEF_YES, if all the data have been written to the buffer.DEF_NO, otherwise
Required Configuration#
None.
Notes / Warnings#
None.
Example Template#
Listing - Connection Connect Callback Function Example Code#
static CPU_BOOLEAN HTTPc_FormMultipartFileHook (HTTPc_CONN_OBJ *p_conn_obj,
HTTPc_REQ_OBJ *p_req_obj,
HTTPc_MULTIPART_FILE *p_file_obj,
CPU_CHAR *p_buf,
CPU_INT16U buf_len,
CPU_INT16U *p_len_wr);
{
FS_FILE_HANDLE file_handle;
FS_ENTRY_INFO entry_info;
FS_FLAGS fs_flags;
CPU_SIZE_T file_rem;
CPU_SIZE_T size;
CPU_SIZE_T size_rd;
CPU_BOOLEAN finish;
RTOS_ERR err;
finish = DEF_YES;
file_handle = (FS_FILE_HANDLE)p_req_obj-\>UserDataPtr;
FSFile_Query(file_handle,
&entry_info,
&err);
if (err.Code == RTOS_ERR_ENTRY_CLOSED) {
fs_flags = 0;
DEF_BIT_SET(fs_flags, FS_FILE_ACCESS_MODE_RD);
DEF_BIT_SET(fs_flags, FS_FILE_ACCESS_MODE_CREATE);
file_handle = FSFile_Open(FS_WRK_DIR_NULL,
"index.html",
fs_flags,
&err);
if (err.Code != RTOS_ERR_NONE) {
return (finish);
}
p_req-\>UserDataPtr = (void *)file_handle;
}
file_rem = p_file-\>Size - p_file-\>Pos;
if (file_rem \<= 0) {
*p_len_wr = 0;
finish = DEF_YES;
FSFile_Close(file_handle,
&err);
goto exit;
}
size = DEF_MIN(file_rem,
buf_len);
size_rd = FSFile_Rd(file_handle,
p_buf,
size,
&err);
if (err.Code != RTOS_ERR_NONE) {
return (finish);
}
*p_len_wr = size_rd;
finish = DEF_NO;
exit:
return (finish);
}This code uses the Micrium OS File System for example purposes.
HTTP Client Hook Functions WebSocket#
The HTTP Client provides a set of hook functions for WebSocket to customize the stack behavior for your application needs. Those are only available when the HTTP Client internal task is active (HTTPc_CFG_MODE_ASYNC_TASK_EN) and can be set up with the API function HTTPc_WebSockMsgSetParam()
Table - WebSocket Hooks#
Hook Function | Description |
|---|---|
Control Hooks | |
Called when a WebSocket Upgrade is successful. | |
Called when an error occurred. | |
Called when a connection that has been successfully upgraded close. | |
Message RX Hooks | |
Called at the beginning of the WebSocket data message reception. | |
Called each time a chunk of the data message is received is available. | |
Called when the data message is completely received. | |
Called when a Pong message is received. |
HTTP Client On Open#
Called when a WebSocket upgrade is successful.
It notify that the application can start to receive and transmit WebSocket messages.
Prototype#
void HTTPc_WebSockOnOpen (HTTPc_CONN_OBJ *p_conn)Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
Return Values#
None.
Required Configuration#
The
HTTPc_CFG_WEBSOCKET_ENconfiguration macro MUST be enabled.
Notes / Warnings#
This hook is set in a
HTTPc_WEBSOCK_OBJusingHTTPc_WebSockSetParam()with the parameterHTTPc_PARAM_TYPE_WEBSOCK_ON_OPEN.Must be set to the
HTTPc_WEBSOCK_OBJbefore upgrading the connection withHTTPc_WebSockUpgrade().
HTTP Client On Close#
Called when a WebSocket Connection has closed.
Note that it doesn't guarantee that the closing handshake is completed, but only notify that the connection will not send or receive WebSocket Message anymore.
Prototype#
void HTTPc_WebSockOnClose (HTTPc_CONN_OBJ *p_conn,
HTTPc_WEBSOCK_CLOSE_CODE close_code,
HTTPc_WEBSOCK_CLOSE_REASON *p_reason);Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
close_code
Code defined by the RFC to explain the reason of the connection closing.
p_reason
Pointer that contains the data following the close code and the length.
Return Values#
None.
Required Configuration#
The
HTTPc_CFG_WEBSOCKET_ENconfiguration macro MUST be enabled.
Notes / Warnings#
This hook is set in a
HTTPc_WEBSOCK_OBJusingHTTPc_WebSockSetParam()with the parameterHTTPc_PARAM_TYPE_WEBSOCK_ON_CLOSE.Must be set to the
HTTPc_WEBSOCK_OBJbefore upgrading the connection withHTTPc_WebSockUpgrade().
HTTP Client On Error#
Called when an error occurs in a WebSocket connection.
Prototype#
void HTTPc_WebSockOnError (HTTPc_CONN_OBJ *p_conn,
RTOS_ERR err);Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
err
Error Code causing the connection to close.
Return Values#
None.
Required Configuration#
The
HTTPc_CFG_WEBSOCKET_ENconfiguration macro MUST be enabled.
Notes / Warnings#
This hook is set in a
HTTPc_WEBSOCK_OBJusingHTTPc_WebSockSetParam()with the parameterHTTPc_PARAM_TYPE_WEBSOCK_ON_ERR.Must be set to the
HTTPc_WEBSOCK_OBJbefore upgrading the connection withHTTPc_WebSockUpgrade().
HTTP Client On Pong#
Called every time a Pong message is received.
Prototype#
void HTTPc_WebSockOnPong (HTTPc_CONN_OBJ *p_conn,
CPU_CHAR *p_data,
CPU_INT16U data_len);Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
p_data
Pointer to the data of the Pong message
data_len
Data length of the Pong message.
Return Values#
None.
Required Configuration#
The
HTTPc_CFG_WEBSOCKET_ENconfiguration macro MUST be enabled.
Notes / Warnings#
This hook is set in a
HTTPc_WEBSOCK_OBJusingHTTPc_WebSockSetParam()with the parameterHTTPc_PARAM_TYPE_WEBSOCK_ON_PONG.Must be set to the
HTTPc_WEBSOCK_OBJbefore upgrading the connection withHTTPc_WebSockUpgrade().
HTTP Client On Message Reception Initialization#
Called at every beginning of a WebSocket Data Message.
It first describes the type of data message and the total length of the message to receive. Then, it is possible to set an optional pointer to specify where the data must be copied automatically.
Prototype#
void HTTPc_WebSockOnMsgRxInit (HTTPc_CONN_OBJ *p_conn,
HTTPc_WEBSOCK_MSG_TYPE msg_type,
CPU_INT32U msg_len,
` void **p_data);Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
msg_type
Type of WebSocket message to receive.
msg_len
The total length if the message to receive.
p_data
Pointer to a pointer that can be set to specify where the data must be copied. Specific to the Auto Mode.
Return Values#
None.
Required Configuration#
The
HTTPc_CFG_WEBSOCKET_ENconfiguration macro MUST be enabled.
Notes / Warnings#
When a message is fragmented, thus the total message length is unknown, the value will be
HTTPc_WEBSOCK_TX_MSG_LEN_NOT_DEFINED.This hook is set in a
HTTPc_WEBSOCK_OBJusingHTTPc_WebSockSetParam()with the parameterHTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_INIT.Must be set to the
HTTPc_WEBSOCK_OBJbefore upgrading the connection withHTTPc_WebSockUpgrade().
HTTP Client On Message RX Data#
Called every time a chunk of the data message is available to be read.
Prototype#
CPU_INT32U HTTPc_WebSockOnMsgRxData (HTTPc_CONN_OBJ *p_conn,
HTTPc_WEBSOCK_MSG_TYPE msg_type,
` void *p_data,`
CPU_INT16U data_len);Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
msg_type
Type of WebSocket message to receive.
p_data
Pointer to the message data chunk.
data_len
Length of the data chunk available.
Return Values#
The total number of bytes read from the data chunk.
Required Configuration#
The
HTTPc_CFG_WEBSOCKET_ENconfiguration macro MUST be enabled.
Notes / Warnings#
When the number of bytes read is less than the available data, the remaining bytes will be available for the next time this hook is called with new received data concatenated, if applicable.
This hook is set in a
HTTPc_WEBSOCK_OBJusingHTTPc_WebSockSetParam()with the parameterHTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_DATA.Must be set to the
HTTPc_WEBSOCK_OBJbefore upgrading the connection withHTTPc_WebSockUpgrade().
HTTP Client On Message RX Complete#
Called when a message is received completely.
Prototype#
void HTTPc_WebSockOnMsgRxComplete (HTTPc_CONN_OBJ *p_conn);Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
Return Values#
None.
Required Configuration#
The
HTTPc_CFG_WEBSOCKET_ENconfiguration macro MUST be enabled.
Notes / Warnings#
This hook is set in a
HTTPc_WEBSOCK_OBJusingHTTPc_WebSockSetParam()with the parameterHTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_COMPLETE.Must be set to the
HTTPc_WEBSOCK_OBJbefore upgrading the connection withHTTPc_WebSockUpgrade().
HTTP Client WebSocket Message Hooks#
The HTTP Client provides a set of hook functions for WebSocket Message to customize the stack behavior for your application needs. Those are only available when the HTTP Client internal task is active (HTTPc_CFG_MODE_ASYNC_TASK_EN) and can be set up with the API function HTTPc_WebSockSetParam().
Table - WebSocket Message Hooks#
Hook Function | Description |
|---|---|
Message TX Hooks | |
Called when the message is ready to be sent. | |
Called to set the internal connection buffer of a data chunk of a message to send. | |
Called when the message is completely transmitted |
HTTP Client On Message TX Initialization#
Called when the message is ready to be transmit.
Prototype#
CPU_INT32U HTTPc_WebSockOnMsgTxInit (HTTPc_CONN_OBJ *p_conn,
HTTPc_WEBSOCK_MSG_OBJ *p_msg);Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
p_msg
Pointer to the WebSocket Message to transmit
Return Values#
The length of the message to transmit.
Required Configuration#
The
HTTPc_CFG_WEBSOCKET_ENconfiguration macro MUST be enabled.
Notes / Warnings#
When the dynamic mode is used, thus the total message length is unknown, the value returned will be
HTTPc_WEBSOCK_TX_MSG_LEN_NOT_DEFINED.This hook is set in a
HTTPc_WEBSOCK_MSG_OBJusingHTTPc_WebSockMsgSetParam()with the parameterHTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_MSG_TX_INIT.Must be set to the
HTTPc_WEBSOCK_MSG_OBJbefore upgrading the connection withHTTPc_WebSockSend().
HTTP Client On Message TX Data#
Called to set a chunk of the WebSocket message payload to the connection buffer.
Prototype#
CPU_INT32U HTTPc_WebSockOnMsgTxData (HTTPc_CONN_OBJ *p_conn,
HTTPc_WEBSOCK_MSG_OBJ *p_msg,
CPU_CHAR *p_buf,
CPU_INT32U buf_len);Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
p_msg
Pointer to the WebSocket message object.
p_buf
Pointer to the start of the transmit buffer.
buf_len
The available size of the transmit buffer.
Return Values#
Number of bytes copied in the buffer and ready to be transmitted.
Required Configuration#
The
HTTPc_CFG_WEBSOCKET_ENconfiguration macro MUST be enabled.
Notes / Warnings#
In dynamic mode, thus the message length has been previously set to
HTTPc_WEBSOCK_TX_MSG_LEN_NOT_DEFINED, this hook will be called until the value 0 is returned.This hook is set in a
HTTPc_WEBSOCK_MSG_OBJusingHTTPc_WebSockMsgSetParam()with the parameterHTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_MSG_TX_INIT.Must be set to the
HTTPc_WEBSOCK_MSG_OBJbefore upgrading the connection withHTTPc_WebSockSend().
HTTP Client On Message TX Complete#
Called when the message is completely transmitted. Can be also called for every pending message when a connection is close.
Prototype#
void HTTPc_WebSockOnMsgTxComplete (HTTPc_CONN_OBJ *p_conn,
HTTPc_WEBSOCK_MSG_OBJ *p_msg
CPU_BOOLEAN status);Arguments#
p_conn
Pointer to the current HTTPc Connection Object.
p_msg
Pointer to the WebSocket Message transmitted.
status
Bool that indicate if the message has been transmitted successfully.
Return Values#
None.
Required Configuration#
The
HTTPc_CFG_WEBSOCKET_ENconfiguration macro MUST be enabled.
Notes / Warnings#
This hook is set in a
HTTPc_WEBSOCK_MSG_OBJusingHTTPc_WebSockMsgSetParam()with the parameterHTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_MSG_TX_COMPLETE.Must be set to the
HTTPc_WEBSOCK_MSG_OBJbefore upgrading the connection withHTTPc_WebSockSend().