Control Structure
µC/HTTP-client offers many structures that the application can use to create objects to interact with the µC/HTTP-client stack.
All the HTTP Client Objects required by the application must be allocated by the application and passed to the µC/HTTP-client stack.
All objects or strings passed to the µC/HTTP-client stack MUST stay valid and unmodified for the duration of the HTTP Transaction for Request-oriented parameters and objects; or until the HTTP connection is closed for Connection-oriented parameters and objects.
HTTP Client Connection (HTTPc_CONN_OBJ
)
This structure is the main one used by µC/HTTP-client. It contains all parameters relative to an HTTP connection (server port number, server address, server host name, etc.) and also many internal parameters for the HTTP connection and HTTP transaction processing.
Each configurable parameter SHOULD be set up with the function HTTPc_ConnSetParam(). The list of available parameters for a connection can be viewed here.
The members of an HTTP Client object should never be directly tampered with at any time. To ensure this, the HTTPc_CONN_OBJ
structure's members have all been declared constant with the const keyword and the suffix _reserved has been added.
struct httpc_conn_obj { /* -------------- CONNECTION PARAMETERS --------------- */ const NET_SOCK_ID SockID_reserved; /* Connection's Socket ID. */ const HTTPc_FLAGS SockFlags_reserved; /* Connection's Socket flags. */ #ifdef NET_SECURE_MODULE_EN const NET_APP_SOCK_SECURE_CFG SockSecureCfg_reserved; /* Connection's Socket Secure Cfg. */ #endif const CPU_INT16U ConnectTimeout_ms_reserved; /* Connection Connect Timeout. */ const CPU_INT16U InactivityTimeout_s_reserved; /* Connection Inactivity Timeout. */ const NET_PORT_NBR ServerPort_reserved; const NET_SOCK_ADDR ServerSockAddr_reserved; /* Server socket address. */ const CPU_CHAR *HostNamePtr_reserved; /* Pointer to HTTP server Host name string. */ const CPU_INT16U HostNameLen_reserved; const HTTPc_CONN_STATE State_reserved; /* Connection State. */ const HTTPc_FLAGS Flags_reserved; /* Set of flags related to HTTP connection. */ const HTTPc_CONN_CLOSE_STATUS CloseStatus_reserved; /* Status of connection closed. */ const HTTPc_ERR ErrCode_reserved; /* Error code of connection. */ #ifdef HTTPc_TASK_MODULE_EN const HTTPc_CONNECT_CALLBACK OnConnect_reserved; /* Connection Connect callback function. */ const HTTPc_CONN_CLOSE_CALLBACK OnClose_reserved; /* Connection Close callback function. */ const HTTPc_CONN_ERR_CALLBACK OnErr_reserved; /* Connection Error callback function. */ #endif #ifdef HTTPc_SIGNAL_TASK_MODULE_EN const KAL_SEM_HANDLE ConnectSignal_reserved; /* HTTP Socket Connect Done Signal. */ const KAL_SEM_HANDLE TransDoneSignal_reserved; /* HTTP Transaction Done Signal. */ const KAL_SEM_HANDLE CloseSignal_reserved; /* HTTP Socket Close Done Signal. */ #endif /* ---------------- REQUEST PARAMETERS ---------------- */ const HTTPc_REQ *ReqListHeadPtr_reserved; /* Head of the Request list. */ const HTTPc_REQ *ReqListEndPtr_reserved; /* End of the Request list. */ const HTTPc_FLAGS ReqFlags_reserved; /* Set of flags related to the HTTP request. */ #if (HTTPc_CFG_QUERY_STR_EN == DEF_ENABLED) const CPU_INT16U ReqQueryStrTxIx_reserved; /* Tbl index of the Query Strings Transmitted. */ const HTTPc_KEY_VAL *ReqQueryStrTempPtr_reserved; /* Temporary Query String to Tx. */ #endif #if (HTTPc_CFG_HDR_TX_EN == DEF_ENABLED) const CPU_INT08U ReqHdrTxIx_reserved; /* Current index in Req hdr table to Tx hdrs. */ const HTTP_HDR *ReqHdrTempPtr_reserved; /* Temporary Header field to Tx. */ #endif #if (HTTPc_CFG_FORM_EN == DEF_ENABLED) const CPU_INT16U ReqFormDataTxIx_reserved; /* Current index in form table to Tx form fields. */ #endif const CPU_INT16U ReqDataOffset_reserved; /* Offset in Request Data Pointer to Tx the data. */ /* ---------------- RESPONSE PARAMETERS --------------- */ const HTTPc_FLAGS RespFlags_reserved; /* Set of flags related to the HTTP response. */ /* ----------- CONNECTION BUFFER PARAMETERS ----------- */ const void *TxDataPtr_reserved; /* Pointer to data to transmit. */ const CPU_CHAR *BufPtr_reserved; /* Pointer to conn buffer. */ const CPU_INT16U BufLen_reserved; /* Conn buffer length. */ const CPU_CHAR *RxBufPtr_reserved; /* Pointer to Buffer where to Rx data. */ const CPU_INT16U RxDataLenRem_reserved; /* Remaining data to process in the rx buffer. */ const CPU_INT32U RxDataLen_reserved; /* Data length received. */ const CPU_CHAR *TxBufPtr_reserved; /* Pointer to Buffer where to Tx data. */ const CPU_INT16U TxDataLen_reserved; /* Length of data to Tx. */ /* ------------ CONNECTION LIST PARAMETERS ------------ */ const HTTPc_CONN *NextPtr_reserved; /* Pointer to next connection. */ #if (HTTPc_CFG_USER_DATA_EN == DEF_ENABLED) /* --------------- USER DATA PARAMETER ---------------- */ void *UserDataPtr; #endif };
HTTP Client Request (HTTPc_REQ_OBJ
)
This structure regroups parameters and flags related to the configuration of an HTTP request.
Each configurable parameter SHOULD be set up with the function HTTPc_ReqSetParam(). The list of available parameters for a connection can be viewed here.
The members of an HTTP Request object should never be directly tempered with at any time. To ensure this, the HTTPc_REQ_OBJ
structure's members have all been declared constant with the const keyword and the suffix _reserved has been added.
struct httpc_req_obj { const HTTPc_FLAGS Flags_reserved; const HTTPc_FLAGS HdrFlags_reserved; const HTTP_METHOD Method_reserved; const CPU_CHAR *ResourcePathPtr_reserved; const CPU_INT16U ResourcePathLen_reserved; const HTTP_CONTENT_TYPE ContentType_reserved; const CPU_INT32U ContentLen_reserved; const void *DataPtr_reserved; #if (HTTPc_CFG_QUERY_STR_EN == DEF_ENABLED) const HTTPc_KEY_VAL *QueryStrTbl_reserved; const CPU_INT16U QueryStrNbr_reserved; const HTTPc_REQ_QUERY_STR_HOOK OnQueryStrTx_reserved; #endif #if (HTTPc_CFG_HDR_TX_EN == DEF_ENABLED) const HTTP_HDR *HdrTbl_reserved; const CPU_INT16U HdrNbr_reserved; const HTTPc_REQ_HDR_HOOK OnHdrTx_reserved; #endif #if (HTTPc_CFG_FORM_EN == DEF_ENABLED) const HTTPc_FORM_TBL_FIELD *FormFieldTbl_reserved; const CPU_INT16U FormFieldNbr_reserved; #endif #if (HTTPc_CFG_CHUNK_TX_EN == DEF_ENABLED) const HTTPc_REQ_BODY_HOOK OnBodyChunkTx_reserved; #endif #if (HTTPc_CFG_HDR_RX_EN == DEF_ENABLED) const HTTPc_RESP_HDR_HOOK OnHdrRx_reserved; /* Resp Hdr Hook fnct to choose which hdr to keep. */ #endif const HTTPc_RESP_BODY_HOOK OnBodyRx_reserved; /* Resp Body Hook fnct to pass Rx data to application. */ #ifdef HTTPc_TASK_MODULE_EN const HTTPc_COMPLETE_CALLBACK OnTransComplete_reserved; /* Response received callback function. */ const HTTPc_TRANS_ERR_CALLBACK OnErr_reserved; /* Transaction Error callback function. */ #endif const HTTPc_CONN *ConnPtr_reserved; /* Pointer to Connection Object. */ const HTTPc_RESP *RespPtr_reserved; /* Pointer to Conn Response Object. */ const HTTPc_REQ *NextPtr_reserved; #if (HTTPc_CFG_USER_DATA_EN == DEF_ENABLED) void *UserDataPtr; #endif };
HTTP Client Response (HTTPc_RESP_OBJ
)
This structure will be filled by the µC/HTTP-client core with the data received in the HTTP response; except for the body part that is retrieved by the application with the hook function On Response Body.
struct httpc_resp_obj { HTTP_PROTOCOL_VER ProtocolVer; /* HTTP version received in response message. */ HTTP_STATUS_CODE StatusCode; /* Status code received in response. */ const CPU_CHAR *ReasonPhrasePtr; /* Pointer to received reason phrase. */ HTTP_CONTENT_TYPE ContentType; /* Content type received in response. */ CPU_INT32U ContentLen; /* Content length received in response if any. */ }
HTTP Client Key-Value Pair (HTTPc_KEY_VAL
)
Key-Value Pair Objects can be used with the HTTP Query String feature and the HTTP Form feature.
The structure's object allows for storing the pointer to an application's Key string and the pointer to its Value string's equivalent key. The string's length must also be saved in the object.
struct httpc_key_val { CPU_CHAR *KeyPtr; /* Pointer to Key String. */ CPU_INT16U KeyLen; /* Length of Key String. */ CPU_CHAR *ValPtr; /* Pointer to Value String. */ CPU_INT16U ValLen; /* Length of Value String. */ };
HTTP Client Extended Key-Value Pair (HTTPc_KEY_VAL_EXT
)
Extended Key-Value Pair Objects can be used with the HTTP Form feature. More specifically, with a multipart type form.
Extended Key-Value Pair Objects are very similar to the Key-Value Pair Objects except that the value pointer is replaced by a hook function that will allow the application to directly copy the value into the µC/HTTP-client buffer.
struct httpc_key_val_ext { CPU_CHAR *KeyPtr; /* Pointer to Key String. */ CPU_INT16U KeyLen; /* Length of Key String. */ HTTPc_KEY_VAL_EXT_HOOK OnValTx; /* Pointer to Hook Function to set Value. */ CPU_INT32U ValLen; /* Length of the Value String. */ };
HTTP Client Multipart File (HTTPc_MULTIPART_FILE
)
Multipart File Objects can be used with the HTTP Form feature. More specifically, with a multipart type form.
The structure's object allows it to store a pointer to the strings file name, the HTTP Content Type of the file and the hook function pointer that will be used to read the file into the transmit buffer.
struct http_multipart_file { CPU_CHAR *NamePtr; /* Pointer to Name of form field. */ CPU_INT16U NameLen; /* Length of the form field's name. */ CPU_CHAR *FileNamePtr; /* Pointer to File Name String. */ CPU_INT16U FileNameLen; /* Length of the File Name String. */ CPU_INT32U FileLen; /* File Length. */ HTTP_CONTENT_TYPE ContentType; /* HTTP Content Type of the file. */ HTTPc_MULTIPART_FILE_HOOK OnFileTx; /* Pointer to Hook Function to Transmit file's data. */ };
HTTP Client Header (HTTPc_HDR
)
This structure is used by the application to add Header Fields to an HTTP request.
struct httpc_hdr { HTTP_HDR_FIELD HdrField; /* HTTP Header Field Type. */ CPU_CHAR *ValPtr; /* Pointer to Header Field Value. */ CPU_INT16U ValLen; /* Length of the value. */ };