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.

Listing - HTTPc_CONN structure
 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.

Listing - HTTPc_REQ Structure
 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.

Listing - HTTPc_RESP Structure
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.

Listing - HTTPc_KEY_VAL Structure
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.

Listing - HTTPc_KEY_VAL_EXT Structure
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.

Listing - HTTPc_MULTIPART_FILE Structure
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.

Listing - HTTPc_HDR Structure
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.           */
};