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#

  1. 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#

  1. 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#

  1. 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_NONE

  • RTOS_ERR_ALREADY_INIT

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_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_NONE

  • RTOS_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_NO_MORE_RSRC

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NET_RETRY_MAX

  • RTOS_ERR_NET_SOCK_CLOSED

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_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_NONE

  • RTOS_ERR_NOT_INIT

Returned Value#

None.

Notes / Warnings#

  1. This function MUST be called before the HTTPc_CONN object 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_PORT

  • HTTPc_PARAM_TYPE_PERSISTENT

  • HTTPc_PARAM_TYPE_CONNECT_TIMEOUT

  • HTTPc_PARAM_TYPE_INACTIVITY_TIMEOUT

  • HTTPc_PARAM_TYPE_SECURE_COMMON_NAME

  • HTTPc_PARAM_TYPE_SECURE_TRUST_CALLBACK

  • HTTPc_PARAM_TYPE_CONN_CONNECT_CALLBACK

  • HTTPc_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_OWNERSHIP

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_NO_MORE_RSRC

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_FAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_NET_OP_IN_PROGRESS

  • RTOS_ERR_TX

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_NET_ADDR_UNRESOLVED

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_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_NONE

  • RTOS_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_TBL

  • HTTPc_PARAM_TYPE_REQ_QUERY_STR_HOOK

  • HTTPc_PARAM_TYPE_REQ_HDR_TBL

  • HTTPc_PARAM_TYPE_REQ_HDR_HOOK

  • HTTPc_PARAM_TYPE_REQ_FORM_TBL

  • HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_TYPE

  • HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_LEN

  • HTTPc_PARAM_TYPE_REQ_BODY_CHUNK

  • HTTPc_PARAM_TYPE_REQ_BODY_HOOK

  • HTTPc_PARAM_TYPE_RESP_HDR_HOOK

  • HTTPc_PARAM_TYPE_RESP_BODY_HOOK

  • HTTPc_PARAM_TYPE_TRANS_COMPLETE_CALLBACK

  • HTTPc_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_OWNERSHIP

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_NO_MORE_RSRC

  • RTOS_ERR_ABORT

  • RTOS_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_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_FAIL

Returned Value#

Length of the formatted form, if no errors. 0 , otherwise.

Notes / Warnings#

  1. 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_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_FAIL

Returned Value#

Length of the formatted form, if no errors. 0 , otherwise.

Notes / Warnings#

  1. 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#

  1. HTTPc_KVP_BIG type 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_OPEN

  • HTTPc_PARAM_TYPE_WEBSOCK_ON_CLOSE

  • HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_INIT

  • HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_DATA

  • HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_COMPLETE

  • HTTPc_PARAM_TYPE_WEBSOCK_ON_ERR

  • HTTPc_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_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_DATA

  • HTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_TX_INIT

  • HTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_TX_DATA

  • HTTPc_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_OWNERSHIP

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_NO_MORE_RSRC

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • DEF_OK, if the operation is successful.

  • DEF_FAIL, if the operation has failed.

Notes / Warnings#

  1. Connection Object:

    (a) Since the WebSocket Upgrade handshake is based on a HTTP request, the connection object p_conn_obj MUST have already established a connection to the desired host server.

  2. Request and Response Object.

    (a) Any HTTP request/response features available can be used during the WebSocket Upgrade Request.

  3. 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

  4. 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.

  5. 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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_OWNERSHIP

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_FAIL

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_NO_MORE_RSRC

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • DEF_OK, the operation is successful.

  • DEF_FAIL, the operation has failed.

Notes / Warnings#

  1. The connection object p_conn MUST has been previously upgraded to WebSocket to use this function. Refer to the HTTPc_WebSockUpgrade() function.

  2. The available Message Types are as follows :

    • HTTPc_WEBSOCK_MSG_TYPE_TXT_FRAME

    • HTTPc_WEBSOCK_MSG_TYPE_BIN_FRAME

    • HTTPc_WEBSOCK_MSG_TYPE_CLOSE

    • HTTPc_WEBSOCK_MSG_TYPE_PING

    • HTTPc_WEBSOCK_MSG_TYPE_PONG

  3. 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.

  4. 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.

  5. 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.

  6. 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_NONE

  • RTOS_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_NONE

  • RTOS_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_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_WOULD_OVF

Returned Value#

  • Payload length, if the operation is successful.

  • 0, if the operation has failed.

Notes / Warnings#

  1. 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."

  2. The following Close Codes are available :

  • HTTPc_WEBSOCK_CLOSE_CODE_NORMAL

  • HTTPc_WEBSOCK_CLOSE_CODE_GOING_AWAY

  • HTTPc_WEBSOCK_CLOSE_CODE_PROTOCOL_ERR

  • HTTPc_WEBSOCK_CLOSE_CODE_DATA_TYPE_NOT_ALLOWED

  • HTTPc_WEBSOCK_CLOSE_CODE_DATA_TYPE_ERR

  • HTTPc_WEBSOCK_CLOSE_CODE_POLICY_VIOLATION

  • HTTPc_WEBSOCK_CLOSE_CODE_MSG_TOO_BIG

  • HTTPc_WEBSOCK_CLOSE_CODE_INVALID_EXT

  • HTTPc_WEBSOCK_CLOSE_CODE_UNEXPECTED_CONDITION

  1. 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

Connection Hooks

Notify event about connection status

HTTPc_CONN_OBJ

HTTPc_ConnSetParam()

HTTPc_ConnOpen()

Request Hooks

Notify event that happen during a HTTP request and allows the application to customize it.

HTTPc_REQ_OBJ

HTTPc_ReqSetParam()

HTTPc_ReqSend()

Hook Functions WebSocket

Notify event that happen after a WebSocket Upgrade is successful and gives access to the application to the messages when received.

HTTPc_WEBSOCK_OBJ

HTTPc_WebSockSetParam()

HTTPc_WebSockUpgrade()

WebSocket Message Hooks

Notify event that happen during a WebSocket Message transmission allows the application to customize it.

HTTPc_WEBSOCK_MSG_OBJ

HTTPc_WebSockMsgSetParam()

HTTPc_WebSockSend()

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

On Connection Connect

Notify that a connection has finish the Connect process.

On Connection Close

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

On Transaction Complete

Notify that an HTTP Transaction (Request + Response) is done.

On Transaction Error

Notify that an error occurred during an specific HTTP Transaction.

Request Hooks

On Request Query String

Set a Query String field (Key-Value Pair) to add to the Request.

On Request Header

Set a Header field to add to the Request.

On Request Body

Set the data to put in the Request when using the Chunked Transfer Encoding.

Response Hooks

On Response Header

Recover a header field received in the Response.

On Response Body

Recover each piece of data received in the Response.

Form Field Hooks

On Form Key-Value Extended

Copy the data of the value into the transmission buffer.

On Form Multipart File

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_EN configuration 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_EN configuration 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 HTTPc_REQ_OBJ or HTTPc_CONN_OBJ can be used to store data for the application usage.

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

On Open

Called when a WebSocket Upgrade is successful.

On Close

Called when an error occurred.

On Error

Called when a connection that has been successfully upgraded close.

Message RX Hooks

On Message Reception Initialization

Called at the beginning of the WebSocket data message reception.

On Message RX Data

Called each time a chunk of the data message is received is available.

On Message RX Complete

Called when the data message is completely received.

On Pong

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#
  1. The HTTPc_CFG_WEBSOCKET_EN configuration macro MUST be enabled.

Notes / Warnings#
  • This hook is set in a HTTPc_WEBSOCK_OBJ using HTTPc_WebSockSetParam() with the parameter HTTPc_PARAM_TYPE_WEBSOCK_ON_OPEN.

  • Must be set to the HTTPc_WEBSOCK_OBJ before upgrading the connection with HTTPc_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_EN configuration macro MUST be enabled.

Notes / Warnings#
  • This hook is set in a HTTPc_WEBSOCK_OBJ using HTTPc_WebSockSetParam() with the parameter HTTPc_PARAM_TYPE_WEBSOCK_ON_CLOSE.

  • Must be set to the HTTPc_WEBSOCK_OBJ before upgrading the connection with HTTPc_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_EN configuration macro MUST be enabled.

Notes / Warnings#
  • This hook is set in a HTTPc_WEBSOCK_OBJ using HTTPc_WebSockSetParam() with the parameter HTTPc_PARAM_TYPE_WEBSOCK_ON_ERR.

  • Must be set to the HTTPc_WEBSOCK_OBJ before upgrading the connection with HTTPc_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_EN configuration macro MUST be enabled.

Notes / Warnings#
  • This hook is set in a HTTPc_WEBSOCK_OBJ using HTTPc_WebSockSetParam() with the parameter HTTPc_PARAM_TYPE_WEBSOCK_ON_PONG.

  • Must be set to the HTTPc_WEBSOCK_OBJ before upgrading the connection with HTTPc_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#
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_OBJ using HTTPc_WebSockSetParam() with the parameter HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_INIT.

  • Must be set to the HTTPc_WEBSOCK_OBJ before upgrading the connection with HTTPc_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#
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_OBJ using HTTPc_WebSockSetParam() with the parameter HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_DATA.

  • Must be set to the HTTPc_WEBSOCK_OBJ before upgrading the connection with HTTPc_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_EN configuration macro MUST be enabled.

Notes / Warnings#
  • This hook is set in a HTTPc_WEBSOCK_OBJ using HTTPc_WebSockSetParam() with the parameter HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_COMPLETE.

  • Must be set to the HTTPc_WEBSOCK_OBJ before upgrading the connection with HTTPc_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

On Message TX Initialization

Called when the message is ready to be sent.

On Message TX Data

Called to set the internal connection buffer of a data chunk of a message to send.

On Message TX Complete

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#
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_OBJ using HTTPc_WebSockMsgSetParam() with the parameter HTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_MSG_TX_INIT.

  • Must be set to the HTTPc_WEBSOCK_MSG_OBJ before upgrading the connection with HTTPc_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_EN configuration 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_OBJ using HTTPc_WebSockMsgSetParam() with the parameter HTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_MSG_TX_INIT.

  • Must be set to the HTTPc_WEBSOCK_MSG_OBJ before upgrading the connection with HTTPc_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_EN configuration macro MUST be enabled.

Notes / Warnings#
  • This hook is set in a HTTPc_WEBSOCK_MSG_OBJ using HTTPc_WebSockMsgSetParam() with the parameter HTTPc_PARAM_TYPE_WEBSOCK_MSG_ON_MSG_TX_COMPLETE.

  • Must be set to the HTTPc_WEBSOCK_MSG_OBJ before upgrading the connection with HTTPc_WebSockSend().