Application Modules#

This section introduces you to the various network application modules that are included as part of Micrium OS.

Complementary information is also available in the Network section of the Technologies Overview documentation page. The following sections will refer to it when appropriate.

• HTTP Client Module

• HTTP Server Module

• MQTT Client Module

• SNTP Client Module

• SMTP Client Module

• FTP Client Module

• IPerf Module

• Telnet Server Module

• TFTP Client Module

• TFTP Server Module

HTTP Client Module#

The Micrium OS HTTP Client can be used to access HTTP servers and perform actions on resources maintained by a server.

In an embedded environment, an HTTP client will rarely be used to display web pages like a web browser does. It will primarily be used to get and update specific data, download and upload files or to interface with web services.

• HTTP Client Overview

• HTTP Client Example Applications

• HTTP Client Configuration

  • HTTP Client Compile-Time Configurations

  • HTTP Client Run-Time Application Specific Configurations

    • HTTP Client Connection Configurations

    • HTTP Client Quantity Configurations

• HTTP Client Programming Guide

  • HTTP Client Control Structure

  • HTTP Client Connection Object Setup

  • HTTP Client Request Object Setup

  • HTTP Client Open Secure Connection with SSL-TSL

  • HTTP Client Add Additional Header fields to an HTTP Request

  • HTTP Client Request's Body Standard Transfer

  • HTTP Client Chunked Transfer Encoding

  • HTTP Client Query String

  • HTTP Client Form Submission

  • HTTP Client Persistent Connection

  • HTTP Client Retrieve HTTP Response Data

  • HTTP Client WebSocket

    • HTTP Client Upgrading an HTTP Connection

    • HTTP Client Message reception

      • HTTP Client Auto Mode Example

      • HTTP Client Normal Mode Example

    • HTTP Client Sending Message

    • HTTP Client Closing a Connection

HTTP Client Protocol Recognized Fields

HTTP Client Overview#

• Specifications

• Features

• Design

  • Memory Usage

  • Internal Task

  • Auto Select Remote IP address

• Limitations

Specifications#

• Complies with the following RFC:

  • RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1

  • RFC 6455 - The WebSocket Protocol

• Implements the following methods:

  • GET

  • POST

  • PUT

  • DELETE

  • HEAD

Features#

• Scalable to contain only required features and minimize memory footprint

• Supports persistent connection

• Supports form submission

• Supports chunked transfer encoding for both reception and transmission

• Supports application and multipart forms

• Supports reception of HTTP headers in requests and addition of HTTP headers in responses.

• Supports HTTP HTTP Query String processing

• Supports HTTP WebSocket message processing

Design#

The HTTP Client module has been designed to suit many different types of HTTP client applications. With the right configuration it can be used with a very low footprint to send a simple HTTP request and wait for the HTTP server's response. Another benefit of its design is that it can also be used to make simultaneous HTTP requests by opening multiple connections which allows for consistent usage of the same API calls.

Memory Usage#

Each HTTP client application can have very different memory needs. For example, some applications will only require one connection whereas others will require more; some applications will prefer to allocate objects on their own stack while others will want to use a memory pool on the heap. Therefore, to conform with all of these different requirements, HTTP Client does not have its own memory module. All the objects required by the HTTP Client MUST be passed by the application. Three HTTP Client Objects must be supplied by the Application: a Connection object , a Request Object and a Response Object . Also, a buffer per connection must be supplied for the transmission/reception operations. Additional objects may be required when some available features are enabled.

Internal Task#

To support multiple simultaneous connections, HTTP Client has an internal task. This task also allows the queuing of multiple requests on a given connection. When the HTTP Client Task is present, API calls to HTTP Client's stack can be set to the blocking or non-blocking mode.

For simpler applications and to reduce memory footprint, the internal HTTP Client task can be disabled. In that case, HTTP Client operations will be executed directly in the application task and will always be blocking.

Auto Select Remote IP address#

When the DNS Client that is part of the core network is properly configured, HTTP Client can accept a host name string to connect to the remote server. It will perform the IP address resolution by communicating with a DNS server. If the DNS server sends back IPv4 and IPv6 addresses, the first attempt will be to use the IPv6 address to connect to the remote HTTP server. If this connection fails the IPv4 address will be used instead.

Limitations#

• Only supports HTTP v1.1.

• HTTP range requests are not supported.

HTTP Client Example Applications#

This section describes the examples that are related to the HTTP Client module of Micrium OS.

• HTTP Client Initialization Example

  • Description

  • Configuration

    • Mandatory

    • Optional

  • Location

  • API

  • Notes

• HTTP Client GET Request Examples

  • Description

  • Configuration

    • Optional

  • Location

  • API

  • Notes

• HTTP Client POST Request Examples

  • Description

  • Configuration

    • Optional

  • Location

  • API

  • Notes

• HTTP Client PUT Request Examples

  • Description

  • Configuration

    • Optional

  • Location

  • API

  • Notes

• HTTP Client Persistent Connection Examples

  • Description

  • Configuration

    1. Optional

  • Location

  • API

  • Notes

• HTTP Client Multi-connection Examples

  • Description

  • Configuration

    • Optional

  • Location

  • API

  • Notes

HTTP Client Initialization Example#

Description#

This is a generic example that shows how to initialize the HTTP client module. It accomplishes the following tasks:

• Initialize the HTTP client module

• Create a RAM disk for file exchange:

  • Store a file (index.html) to be sent to a server

Configuration#

Mandatory#

The following #define must be added in ex_description.h to allow other examples to initialize the HTTP Client module correctly:

Optional#

The following #define can be added to ex_description.h, as described in Example Applications section, to change default configuration value used by the example:

Location#

/examples/net/http/client/ex_http_client.c

/examples/net/http/client/ex_http_client.h

API#

Notes#

None.

HTTP Client GET Request Examples#

Description#

This is a generic example that shows how to send GET request. It accomplishes the following tasks:

• Set connection option

• Open an HTTP connection

• Send GET request

• Close HTTP Connection

Configuration#

Optional#

The following #define can be added to ex_description.h, as described in Example Applications section, to change default configuration value used by the example:

Location#

/examples/net/http/client/ex_http_client_files.c

/examples/net/http/client/ex_http_client_files.h

/examples/net/http/client/ex_http_client_hooks.c

/examples/net/http/client/ex_http_client_hooks.h

/examples/net/http/client/ex_http_client.c

/examples/net/http/client/ex_http_client.h

API#

Notes#

None.

HTTP Client POST Request Examples#

Description#

This is a generic example that shows how to send POST request. It accomplishes the following tasks:

• Set connection option

• Open an HTTP connection

• Send POST request

• Close HTTP Connection

Configuration#

Optional#

The following #define can be added to ex_description.h, as described in Example Applications section, to change default configuration value used by the example:

Location#

/examples/net/http/client/ex_http_client_files.c

/examples/net/http/client/ex_http_client_files.h

/examples/net/http/client/ex_http_client_hooks.c

/examples/net/http/client/ex_http_client_hooks.h

/examples/net/http/client/ex_http_client.c

/examples/net/http/client/ex_http_client.h

API#

Notes#

None.

HTTP Client PUT Request Examples#

Description#

This is a generic example that shows how to send PUT request. It accomplishes the following tasks:

• Set connection option

• Open an HTTP connection

• Send PUT request

• Close HTTP Connection

Configuration#

Optional#

The following #define can be added to ex_description.h, as described in Example Applications section, to change default configuration value used by the example:

Location#

/examples/net/http/client/ex_http_client_files.c

/examples/net/http/client/ex_http_client_files.h

/examples/net/http/client/ex_http_client_hooks.c

/examples/net/http/client/ex_http_client_hooks.h

/examples/net/http/client/ex_http_client.c

/examples/net/http/client/ex_http_client.h

API#

Notes#

None.

HTTP Client Persistent Connection Examples#

Description#

This is a generic example that shows how to send multiple GET request on the same connection. It accomplishes the following tasks:

• Set connection option

• Open an HTTP connection

• Send GET request #1

• Send GET request #2

• Close HTTP Connection

Configuration#

Optional#

The following #define can be added to ex_description.h, as described in Example Applications section, to change default configuration value used by the example:

Location#

/examples/net/http/client/ex_http_client_files.c

/examples/net/http/client/ex_http_client_files.h

/examples/net/http/client/ex_http_client_hooks.c

/examples/net/http/client/ex_http_client_hooks.h

/examples/net/http/client/ex_http_client.c

/examples/net/http/client/ex_http_client.h

API#

Notes#

None.

HTTP Client Multi-connection Examples#

Description#

This is a generic example that shows how to open multiple connections and how to send requests in parallel. It accomplishes the following tasks:

• Set connection #1 option

• Set connection #2 option

• Open an HTTP connection #1

• Open an HTTP connection #2

• Send GET request #1

• Send GET request #2

Configuration#

Optional#

The following #define can be added to ex_description.h, as described in Example Applications section, to change default configuration value used by the example:

Location#

/examples/net/http/client/ex_http_client_files.c

/examples/net/http/client/ex_http_client_files.h

/examples/net/http/client/ex_http_client_hooks.c

/examples/net/http/client/ex_http_client_hooks.h

/examples/net/http/client/ex_http_client.c

/examples/net/http/client/ex_http_client.h

API#

Notes#

None.

HTTP Client Configuration#

In order to address your application's needs, the HTTP Client module must be properly configured. There are two groups of configuration parameters:

• Compile time configurations

• Run-time application specific configurations

HTTP Client Compile-Time Configurations#

Micrium OS HTTP Client is configurable at compile time via several #defines located in http_client_cfg.h file. HTTP Client module uses #defines when possible, because they allow code and data sizes to be scaled at compile time based on enabled features. This allows the Read-Only Memory (ROM) and Random-Access Memory (RAM) footprints of the HTTP Client module to be adjusted based on application requirements.

It is recommended that the configuration process begins with the default configuration values which in the next sections will be shown in bold.

Task Configuration#

HTTP Client module has an internal task that can be enabled or disabled. Using this internal task allows for simultaneous connection processing and using the API in a non-blocking mode.

Table - HTTPc Task Configuration#

Persistent Connection Configuration#

Table - HTTPc Persistent Connection Configuration#

Chunked Transfer Encoding Configuration#

Table - HTTPc Chunked Transfer Encoding Configuration#

Query String Configuration#

Table - HTTPc Query String Configuration#

Header Field Configuration#

Table - HTTPc Header Field Configuration#

Form Submission Configuration#

Table - HTTPc Form Submission Configuration#

User Data Configuration#

Table - HTTPc User Data Configuration#

WebSocket Configuration#

Table - HTTPc WebSocket Configuration#

HTTP Client Run-Time Application Specific Configurations#

This section defines the configurations related to HTTP Client but that are specified at run-time, during the initialization process.

• Initialization

• Optional configurations

• Post-Init Configurations

Initialization#

Initializing the HTTP Client module is done by calling the function HTTPc_Init(). This function takes no configuration argument. Unless you override an optional configuration before calling the function HTTPc_Init(), the default configurations will be used.

Optional configurations#

This section describes the configurations that are optional. If you do not set them in your application, the default configurations will apply.

The default values can be retrieved via the structure HTTPc_InitCfgDflt.

Table - HTTP Client Optional Configurations#

Post-Init Configurations#

This section describes the configurations that can be set at any time during execution after you called the function HTTPc_Init().

These configurations are optional. If you do not set them in your application, the default configurations will apply.

Table - HTTP Client Post-init Configurations#

HTTP Client Connection Configurations#

Table - HTTPc_CONN_CFG configuration structure in the HTTP Client Connection Configurations page describes each configuration field available in this configuration structure.

Table - HTTPc_CONN_CFG configuration structure#

HTTP Client Quantity Configurations#

Table - HTTPc_QTY_CFG configuration structure in the HTTP Client Quantity Configurations page describes each configuration field available in this configuration structure.

Table - HTTPc_QTY_CFG configuration structure#

HTTP Client Programming Guide#

This Section regroups topics to help developing a custom HTTP client application with the MIcrium OS HTTP Client module. Examples are include in many sub-sections.

• HTTP Client Control Structure

• HTTP Client Connection Object Setup

• HTTP Client Request Object Setup

• HTTP Client Open Secure Connection with SSL-TSL

• HTTP Client Add Additional Header fields to an HTTP Request

• HTTP Client Request's Body Standard Transfer

• HTTP Client Chunked Transfer Encoding

• HTTP Client Query String

• HTTP Client Form Submission

• HTTP Client Persistent Connection

• HTTP Client Retrieve HTTP Response Data

• HTTP Client WebSocket

HTTP Client Control Structure#

The HTTP Client module offers many structures that the application can use to create objects to interact with the API.

All the HTTP Client Objects required by the application must be allocated by the application and passed to the HTTP Client API.

HTTP Client Connection (HTTPc_CONN_OBJ)#

This structure is the main one used by the HTTP Client module. 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 hostname 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 transmitted strings.     */
  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;          /* Index in Req hdr table to Tx headers.     */
  const  HTTP_HDR                  *ReqHdrTempPtr_reserved;       /* Temporary Header field to Tx.             */
#endif
#if (HTTPc_CFG_FORM_EN == DEF_ENABLED)
  const  CPU_INT16U                 ReqFormDataTxIx_reserved;     /* Index in form table to Tx form fields.    */
#endif
  const  CPU_INT16U                 ReqDataOffset_reserved;       /* Offset in Request Data Pointer to Tx 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 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 app.   */
#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 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 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 - HTTP_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.           */
};

HTTP Client Connection Object Setup#

Connection's Parameters#

HTTP Client provides the function HTTPc_ConnSetParam() to configure parameters related to the HTTP Client Connection object . The function takes as argument the type of parameter and the pointer to the parameter. The below parameter's types are available:

Table - HTTPc Connection's Parameters#

Example#

Listing - HTTP Client Connection#

CPU_BOOLEAN  HTTPcApp_ConnPrepare (HTTPc_CONN_OBJ  *p_conn)
{
  CPU_BOOLEAN  persistent;
  RTOS_ERR     err;

                            /* ---------------- INIT NEW CONNECTION --------------- */
    HTTPc_ConnClr(p_conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                        /* ----------------- SET SERVER PORT ------------------ */
    port = 8080;
    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_SERVER_PORT,
                      &port,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                            /* --------------- SET PERSISTENT MODE ---------------- */
    persistent = DEF_YES;
    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_PERSISTENT,
                      &persistent,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                            /* --------------- SET CONN'S CALLBACKS --------------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_CONN_CONNECT_CALLBACK,
                      &AppHTTPc_ConnConnectCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                      &AppHTTPc_ConnCloseCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

  return (DEF_OK);
}

HTTP Client Request Object Setup#

Request's Parameters#

HTTP Client provides the function HTTPc_ReqSetParam() to configure parameters related to the HTTP Request. The function takes as argument the type of parameter and the pointer to the parameter. The below parameter's types are available:

Table - HTTPc Request's Parameters#

Example#

Listing - Request Setup Example Code#

CPU_BOOLEAN  HTTPcApp_ReqPrepare (HTTPc_CONN_OBJ  *p_req)
{
  RTOS_ERR  err;

                                    /* ------------- INIT NEW REQUEST ------------ */
    HTTPc_ReqClr(p_req, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* -------- SET STRING QUERY PARAMETERS ------ */
    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_REQ_QUERY_STR_HOOK,
                     &HTTPcApp_ReqQueryStrHook,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                                /* ------ SET REQUEST ADDITIONAL HEADERS ----- */
    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_REQ_HDR_HOOK,
                     &HTTPcApp_ReqHdrHook,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* -------- SET REQ/RESP HOOK FUNCTIONS ------ */
    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_RESP_HDR_HOOK,
                     &HTTPcApp_RespHdrHook,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_RESP_BODY_HOOK,
                     &HTTPcApp_RespBodyHook,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                                /* ----- SET REQ/RESP CALLBACK FUNCTIONS ----- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_TRANS_COMPLETE_CALLBACK,
                     &HTTPcApp_TransDoneCallback,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_TRANS_ERR_CALLBACK,
                     &HTTPcApp_TransErrCallback,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

  return (DEF_OK);
}

HTTP Client Open Secure Connection with SSL-TSL#

Requirements#

To open a secure HTTP connection with the HTTP Client module, the below requirements are needed:

• A network security module (such as Mocana - NanoSSL) is required.

• The Micrium OS Network core stack needs to be configured accordingly (see section Transport Layer Security Configuration ).

• The client side needs to install certificate authorities to authenticate the identity of each public key certificate sent by servers.

Refer to section Secure Sockets (TLS or SSL) for an example on how to use the Network module to open a secure socket for a client application.

HTTP Client parameters#

HTTP Client offers two parameters to configure the secure connection:

• HTTPc_PARAM_TYPE_SECURE_COMMON_NAME

• HTTPc_PARAM_TYPE_SECURE_TRUST_CALLBACK

The first parameter is optional and gives the option to specify the Common Name linked to the Secure Certificate to identify it with the certificate authorities. If this parameter is not set the server host name will be used.

The second parameter is mandatory to open a secure connection and therefore when this parameter is specified, the HTTP Client stack will assume that the connection to open must be secured. The parameter specified the hook function used by the secure module to ask the upper application to verify and validate the public key certificate send by the server.

Both parameters must be configured with the function HTTPc_ConnSetParam().

Example#

Listing - Secure Connection Example Code#

HTTPc_CONN_OBJ  conn;

/*
*********************************************************************************************************
*                                       HTTPcEx_ConnPrepare()
*
* Description : Example function to prepare the HTTPc Connection.
*
* Argument(s) : p_conn  Pointer to HTTPc Connection object to set up.
*
* Return(s)   : DEF_YES, if Connection preparation successful.
*               DEF_NO,  otherwise.
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcEx_ConnPrepare (HTTPc_CONN_OBJ  *p_conn)
{
  RTOS_ERR  err;

                                                                /* ------------ INIT NEW CONNECTION ---------- */
    HTTPc_ConnClr(p_conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ----------- SET CONN'S CALLBACKS ---------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_CONN_CONNECT_CALLBACK,
                      &HTTPcEx_ConnConnectCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                      &HTTPcEx_ConnCloseCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* ----- SET CONNECTION SECURE PARAMETERS ---- */
  HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_SECURE_TRUST_CALLBACK
                      &HTTPcEx_ConnSecureCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    return (DEF_OK);
}

/*
*********************************************************************************************************
*                                       HTTPcEx_ConnCloseCallback()
*
* Description : Example Callback Function to validate public key from server.
*
* Argument(s) : p_cert_dn   Pointer to certificate distinguished name.
*
*               reason      Reason why certificate is not trusted:
*                               NET_SOCK_SECURE_UNTRUSTED_BY_CA
*                               NET_SOCK_SECURE_EXPIRE_DATE
*                               NET_SOCK_SECURE_INVALID_DATE
*                               NET_SOCK_SECURE_SELF_SIGNED
*
* Return(s)   : DEF_YES, if certificate is valid.
*               DEF_NO,  otherwise.
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcEx_ConnCloseCallback (void                              *p_cert_dn,
                                        NET_SOCK_SECURE_UNTRUSTED_REASON   reason)
{
    return (DEF_YES);
}

HTTP Client Add Additional Header fields to an HTTP Request#

HTTP Client supports the addition of header fields to an HTTP request:

• The preprocessor macro HTTPc_CFG_HDR_TX_EN must be set to DEF_ENABLED.

• HTTPc_HDR objects must be used to set up headed fields to add.

• Two methods are offered by the HTTP Client stack to add header fields:

  • Passing a header fields table to to the HTTP Client stack.

  • Using a hook function that will ask the application for each header field to add to the request.

Some header fields are taken care of by the HTTP Client module and must therefore not be added by the application :

• Host

• Content-Type

• Content-Length

• Transfer-Encoding

• Connection

Using a Header Fields Table#

With the first option, before sending the HTTP request, the application can prepare a table of HTTPc_HDR objects that the HTTP Client will include in the request. The API function HTTPc_ReqSetParam() must be used with the parameter type HTTPc_PARAM_TYPE_REQ_HDR_TBL to pass out the table to the HTTP Client stack.

Listing - Adding Header Fields with a Table Example Code#

#define  HTTPc_CFG_HDR_NBR_MAX       10
#define  HTTPc_CFG_HDR_VAL_LEN_MAX  100

HTTPc_HDR      HTTPc_ReqHdrTbl[HTTPc_CFG_HDR_NBR_MAX];
CPU_CHAR       HTTPc_ReqHdrValTbl[HTTPc_CFG_HDR_NBR_MAX][HTTPc_CFG_HDR_VAL_LEN_MAX];

/*
*********************************************************************************************************
*                                           HTTPc_ReqPrepareHdr()
*
* Description : Prepare the HTTP header table.
*
* Argument(s) : p_tbl    Variable that will received the pointer to header table.
*
* Return(s)   : Number of Header fields in the table.
*********************************************************************************************************
*/
static  CPU_INT08U  HTTPc_ReqPrepareHdr (HTTPc_KEY_VAL  **p_tbl)
{
  HTTPc_HDR  *p_hdr;

    p_hdr           = &HTTPc_ReqHdrTbl[0];
    p_hdr->ValPtr   = &HTTPc_ReqHdrValTbl[0][0];
    p_hdr->HdrField =  HTTP_HDR_FIELD_ACCEPT;

    Str_Copy_N(p_hdr->ValPtr, "text/*", HTTPc_CFG_HDR_VAL_LEN_MAX);

    p_hdr->ValLen = Str_Len_N(p_hdr->ValPtr, HTTPc_CFG_HDR_VAL_LEN_MAX);

   *p_ext_hdr_tbl = &HTTPc_ReqHdrTbl[0];

    return (1);
}

/*
*********************************************************************************************************
*                                           HTTPc_ReqPrepare()
*
* Description : Prepare the HTTP request to send.
*
* Argument(s) : p_req    Pointer to the HTTP Request object to configure.
*
* Return(s)   : DEF_OK,   if the request was configured successfully.
*               DEF_FAIL, otherwise.
*********************************************************************************************************
*/
static  CPU_BOOLEAN  HTTPc_ReqPrepare (HTTPc_REQ_OBJ  *p_req)
{
    HTTPc_PARAM_TBL   tbl_obj;
    HTTPc_HDR        *p_hdr_tbl;
    CPU_INT08U        hdr_nbr;
    HTTPc_ERR         err;

                                                                /* ---------- SET HEADER FIELDS DATA --------- */
    hdr_nbr = HTTPc_ReqPrepareHdr(&p_hdr_tbl);
    if (hdr_nbr <= 0) {
        return (DEF_FAIL);
    }

                                                                /* -------- SET HEADER FIELDS PARAMETER ------ */
    tbl_obj.EntryNbr = hdr_nbr;
    tbl_obj.TblPtr   = (void *)p_hdr_tbl;
    HTTPc_ReqSetParam(p_req, HTTPc_PARAM_TYPE_REQ_HDR_TBL, &tbl_obj, &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }

    ...  /* TODO other operations on request if necessary. */

    return (DEF_OK);

Using a Hook Function#

The Second option is to set up a hook function. The hook function will be called by the HTTP Client core to add a Header Field to the request. The hook function will be called until it return DEF_YES to notified the HTTP Client stack that all the fields have been added. The API function HTTPc_ReqSetParam() must be used with the parameter type HTTPc_PARAM_TYPE_REQ_HDR_HOOK to pass out hook function pointer to the HTTP Client stack.

Listing - Adding Header Fields with a Hook Example Code#

#define  HTTPc_CFG_HDR_NBR_MAX       10
#define  HTTPc_CFG_HDR_VAL_LEN_MAX  100

CPU_INT08U     HTTPc_ReqHdrIx;
HTTPc_HDR      HTTPc_ReqHdrTbl[HTTPc_CFG_HDR_NBR_MAX];
CPU_CHAR       HTTPc_ReqHdrValTbl[HTTPc_CFG_HDR_NBR_MAX][HTTPc_CFG_HDR_VAL_LEN_MAX];

/*
*********************************************************************************************************
*                                           HTTPc_ReqPrepare()
*
* Description : Prepare the HTTP request to send.
*
* Argument(s) : p_req    Pointer to the HTTP Request object to configure.
*
* Return(s)   : DEF_OK,   if the request was configured successfully.
*               DEF_FAIL, otherwise.
*********************************************************************************************************
*/
static  CPU_BOOLEAN  HTTPc_ReqPrepare (HTTPc_REQ_OBJ  *p_req)
{
    HTTPc_ERR       err;

                                                                /* -------- SET STRING QUERY PARAMETER ------- */
    HTTPc_ReqSetParam(p_req, HTTPc_PARAM_TYPE_REQ_HDR_HOOK, &HTTPc_ReqHdrHook, &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }

    p_req->UserDataPtr = (void *)&HTTPc_ReqHdrIx;

    ...  /* TODO other operations on request if necessary. */

    return (DEF_OK);
}

/*
*********************************************************************************************************
*                                           HTTPc_ReqHdrHook()
*
* Description : Hook function to retrieve the header fields to include in the HTTP request.
*
* Argument(s) : p_conn   Pointer to the HTTP Connection object.
*
*               p_req    Pointer to the HTTP Request object.
*
*               p_hdr    Variable that will received the pointer to the Header field object.
*
* Return(s)   : DEF_YES, if all the header fields to include have been passed.
*               DEF_NO,  otherwise.
*********************************************************************************************************
*/
static  CPU_BOOLEAN  HTTPc_ReqHdrHook (HTTPc_CONN_OBJ   *p_conn,
                                       HTTPc_REQ_OBJ    *p_req,
                                       HTTPc_HDR       **p_hdr)
{
    HTTPc_HDR       *p_hdr_item;
    CPU_INT08U       index;

    index = *(CPU_INT08U)p_req->UserDataPtr;

    switch(index) {
        case 0:
             p_hdr_item           = &HTTPc_ReqHdrTbl[0];
             p_hdr_item->ValPtr   = &HTTPc_ReqHdrValTbl[0][0];
             p_hdr_item->HdrField =  HTTP_HDR_FIELD_ACCEPT;
            (void)Str_Copy_N(p_hdr_item->ValPtr, "text/*", HTTPc_CFG_HDR_VAL_LEN_MAX);
             p_hdr_item->ValLen = Str_Len_N(p_hdr_item->ValPtr, HTTPc_CFG_HDR_VAL_LEN_MAX);
            *p_hdr = p_hdr_item;
             index++;
            *(CPU_INT08U)p_req->UserDataPtr = index;
             return (DEF_NO);

        case 1:
             p_hdr_item           = &HTTPc_ReqHdrTbl[1];
             p_hdr_item->ValPtr   = &HTTPc_ReqHdrValTbl[1][0];
             p_hdr_item->HdrField =  HTTP_HDR_FIELD_DATE;
            (void)Str_Copy_N(p_hdr_item->ValPtr, "Thursday, 21-Aug-14 02:15:31 GMT", HTTPc_CFG_HDR_VAL_LEN_MAX);
             p_hdr_item->ValLen = Str_Len_N(p_hdr_item->ValPtr, HTTPc_CFG_HDR_VAL_LEN_MAX);
            *p_hd = p_hdr_item;
             index = 0;
            *(CPU_INT08U)p_req->UserDataPtr = index;
             return (DEF_YES);

        default:
            *p_hdr = DEF_NULL;
             index = 0;
            *(CPU_INT08U)p_req->UserDataPtr = index;
             return (DEF_YES);
    }
}

HTTP Client Request's Body Standard Transfer#

The POST and PUT methods can be used to transfer data to the HTTP server. The data is included in the body part of the HTTP request.

Additional HTTP header fields must be included when a body is present. The content type of the data must be specified with the Content-Type header field, and for a standard transfer, the length of the data must be specified with the Content-Length header field. Those headers will be added automatically by the HTTP Client stack after the required parameters are configured.

The function HTTPc_ReqSetParam() must be used to configure the additional parameters necessary when data must be transmitted the standard way. Three parameters must be set up :

• HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_TYPE

• HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_LEN

• HTTPc_PARAM_TYPE_REQ_BODY_HOOK

The first parameter sets the content-type of the data, the second the length of the data, and the third sets the hook function that will be used by the HTTP Client module to retrieve the data.

Example#

The example below implements a function to send a PUT request :

• An HTTP Connection is set up

• An HTTP request is configured with the three body parameters: content-type, content-length, and hook function.

• The Connection is open.

• The request is sent.

Listing - Standard Body Transfer Function Example Code#

CPU_CHAR  index_html[1024];

/*
*********************************************************************************************************
*                                      HTTPcEx_ReqSendPUT_Standard()
*
* Description : Example function to send a HTTP PUT request with the standard transfer (not chunked).
*
* Argument(s) : none.
*
* Return(s)   : DEF_YES, is request sent successfully.
*               DEF_NO,  otherwise.
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcEx_ReqSendPUT_Standard (void)
{
    HTTPc_CONN_OBJ     conn;
    HTTPc_REQ_OBJ      req;
    HTTPc_RESP_OBJ     resp;
    CPU_CHAR           buf[512];
    HTTPc_FLAGS        flags;
    HTTP_CONTENT_TYPE  content_type;
    CPU_SIZE_T         content_len;
    CPU_SIZE_T         str_len;
    CPU_BOOLEAN        result;
    RTOS_ERR           err;

                                                                /* ------------ INIT NEW CONNECTION ---------- */
    HTTPc_ConnClr(&conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ---------- SET CONNECTION PARAM ----------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ConnSetParam(&conn,
                        HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                       &HTTPcEx_ConnCloseCallback,
                       &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* -------------- INIT NEW REQUEST------------ */
    HTTPc_ReqClr(&req, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ------- SET REQUEST BODY PARAMETERS ------- */
    content_type = HTTP_CONTENT_TYPE_HTML;
    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_TYPE,
                      &content_type,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    content_len = STATIC_INDEX_HTML_LEN;
    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_LEN,
                      &content_len,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_REQ_BODY_HOOK,
                      &HTTPcEx_ReqBodyHook,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* -------- SET TRANSACTION CALLBACKS -------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_TRANS_ERR_CALLBACK,
                      &HTTPcEx_TransErrCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* ------------- OPEN CONNECTION ------------- */
    str_len = Str_Len("www.example.com");
    flags   = HTTPc_FLAG_NONE;
    result  = HTTPc_ConnOpen(&conn,
                             &buf,
                              APP_HTTPc_CFG_BUF_SIZE,
                             "www.example.com",
                              str_len,
                              flags,
                             &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    if (result != DEF_OK) {
        return (DEF_FAIL);
    }

                                                                /* ------------ SEND HTTP REQUEST ------------ */
    str_len = Str_Len("/index.html");
    flags   = HTTPc_FLAG_NONE;
    result  = HTTPc_ReqSend(&conn,
                            &req,
                            &resp,
                             HTTP_METHOD_PUT,
                            "/index.html",
                             str_len,
                             flags,
                            &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    return (DEF_OK);
}

The example below is a first implementation of the hook function to retrieve the request body data from the application. In this example, the data is retrieved from an existing application buffer (index_html) and the hook function only set up the data pointer and the length of the data.

Listing - Request Body Hook Function Example Code #1#

/*
*********************************************************************************************************
*                                      HTTPcEx_ReqBodyHook()
*
* Description : Example Hook function to transfer data in request with the standard transfer.
*
*               This function let you the choice to set the pointer to the application data (with p_data)
*               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(s) : p_conn      Pointer to the current HTTPc Connection object.
*
*               p_req       Pointer to the current HTTPc Request object.
*
*               p_data      Pointer to the application data.
*
*               p_buf       Pointer to the HTTP buffer.
*
*               buf_len     Buffer's length.
*
*               p_data_len  Variable that will return the data length passed by the application.
*
* Return(s)   : DEF_YES, if all data as been passed.
*               DEF_NO,  if data still remaining to be passed by the application.
*********************************************************************************************************
*/

static  CPU_BOOLEAN  HTTPcEx_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_INT16U  size;
    CPU_INT16U  str_len;

   *p_data = &index_html[0];

    str_len = Str_Len(&index_html[0]);
    Str_Copy_N(p_buf, &index_html[0], str_len);

   *p_data_len = str_len;

    return (DEF_YES);
}

The example below is a second implementation of the hook function to retrieve the request body data from the application. In this example, the data is retrieved from a file that is accessed using Micrium OS File System and directly copied into the HTTP transmit buffer.

Listing - Request Body Hook Function Example Code #2#

static  CPU_BOOLEAN  HTTPcEx_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_BOOLEAN     finish;
    CPU_SIZE_T      file_rem;
    CPU_SIZE_T      size;
    CPU_SIZE_T      size_rd;
    FS_FILE_HANDLE  file_handle;
    FS_ENTRY_INFO   file_info;
    FS_FILE_SIZE    file_pos;
    RTOS_ERR        err;

   *p_data = DEF_NULL;

    file_handle = FSFile_Open(FSWrkDir_NullHandle,
                             "ram0/index.html",
                              FS_FILE_ACCESS_MODE_RD,
                             &err);
    if (err.Code != RTOS_ERR_NONE) {
        // TODO: Handle error.

       *p_data_len = 0u;
        finish     = DEF_YES;
        return (finish);
    }

    FSFile_Query(file_handle,
                &file_info,
                &err);
    if (err.Code != RTOS_ERR_NONE) {
        // TODO: Handle error.

       *p_data_len = 0;
        finish     = DEF_YES;
        goto exit_close;
    }

    file_pos = FSFile_PosGet(file_handle,
                            &err);
    if (err.Code != RTOS_ERR_NONE) {
        // TODO: Handle error.

       *p_data_len = 0;
        finish     = DEF_YES;
        goto exit_close;
    }

    file_rem = file_info.Size - file_pos;
    if (file_rem <= 0) {
       *p_data_len = 0;
        finish     = DEF_YES;
        goto exit_close;
    }

    size = DEF_MIN(file_rem, buf_len);

    size_rd = FSFile_Rd(file_handle,
                        p_buf,
                        size,
                       &err);
    if (err.Code != RTOS_ERR_NONE) {
        // TODO: Handle error.

       *p_data_len = 0u;
        finish     = DEF_YES;
        goto exit_close;
    }

   *p_data_len = size_rd;
    finish     = DEF_NO;

exit_close:
    FSFile_Close(file_handle, &err);
    if (err.Code != RTOS_ERR_NONE) {
        // TODO: Handle error.
    }

    return (finish);
}

HTTP Client Chunked Transfer Encoding#

The POST and PUT methods can be used to transfer data to the HTTP server. The data is included in the body part of the HTTP request.

When the size of the data to transmit is unknown before starting the HTTP request, the Chunked Transfer Encoding can be used. It will split the data into chunks of known size and will send an empty chunk to advertise the end of the data.

Additional HTTP header fields must be included when a body is present. The content type of the data must be specified with the Content-Type header field and for the Chunked Transfer encoding the Transfer-Encoding header field must be specified. Those headers will be added automatically by the HTTP Client module after the required parameters are configured. For more details, refer to section Chunked Transfer Encoding.

The function HTTPc_ReqSetParam() must be used to configure the additional parameters necessary when data is transmitted in chunks. Three parameters must be set up :

• HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_TYPE

• HTTPc_PARAM_TYPE_REQ_BODY_CHUNK

• HTTPc_PARAM_TYPE_REQ_BODY_HOOK

The first parameter is to set the content-type of the data, the second is a Boolean to enable the Chunked Transfer Encoding and the third is to set the hook function that will be used by the HTTP Client module to retrieve the data.

Example#

The example below implements a function to send a PUT request :

• An HTTP Connection is configured.

• An HTTP request is configured with the three body parameters: content-type, chunk enabled and hook function.

• The Connection is open.

• The request is sent.

Listing - Chunked Transfer Encoding Example Code#

/*
*********************************************************************************************************
*                                      HTTPcEx_ReqSendPUT_Chunked()
*
* Description : Example function to send a HTTP PUT request with the Chunked Transfer Encoding.
*
* Argument(s) : none.
*
* Return(s)   : DEF_YES, is request sent successfully.
*               DEF_NO,  otherwise.
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcEx_ReqSendPUT_Chunked (void)
{
    CPU_BOOLEAN        result;
    CPU_BOOLEAN        chunk_en;
    CPU_CHAR           buf[512];
    CPU_SIZE_T         str_len;
    HTTPc_CONN_OBJ     conn;
    HTTPc_REQ_OBJ      req;
    HTTPc_RESP_OBJ     resp;
    HTTP_CONTENT_TYPE  content_type;
    RTOS_ERR           err;

                                                                   /* ---------- INIT NEW CONNECTION --------- */
    HTTPc_ConnClr(&conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                   /* -------- SET CONNECTION PARAM ---------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ConnSetParam(&conn,
                        HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                       &HTTPcEx_ConnCloseCallback,
                       &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                   /* ----- SET REQUEST BODY PARAMETERS ------ */
    content_type = HTTP_CONTENT_TYPE_JSON;
    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_TYPE,
                      &content_type,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    chunk_en = DEF_YES;
    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_REQ_BODY_CHUNK,
                      &chunk_en,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_REQ_BODY_HOOK,
                      &HTTPcEx_ReqBodyHook,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_TRANS_ERR_CALLBACK,
                      &HTTPcEx_TransErrCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                   /* ----------- OPEN CONNECTION ------------ */
    str_len = Str_Len("www.example.com");
    result  = HTTPc_ConnOpen(&conn,
                             &buf,
                              APP_HTTPc_CFG_BUF_SIZE,
                             "www.example.com",
                              str_len,
                              HTTPc_FLAG_NONE,
                             &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    if (result != DEF_OK) {
        return (DEF_FAIL);
    }

                                                                   /* ---------- SEND HTTP REQUEST ----------- */
    str_len = Str_Len("/");
    result  = HTTPc_ReqSend(&conn,
                            &req,
                            &resp,
                             HTTP_METHOD_PUT,
                            "/",
                             str_len,
                             HTTPc_FLAG_NONE,
                            &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    return (DEF_OK);
}

For examples on the On Request Body hook function, refer to section Request's Body Standard Transfer since the hook function is used regardless of the transfer mode.

HTTP Client Query String#

A Query String is a set of Key-Value pairs or single values added at the end of the request's URL after a question mark character "?". Each field of the Query is separated by the "&" character. For more details, see section Query String .

The HTTP Client module supports the addition of a Query String to an HTTP request:

1. The preprocessor macro HTTPc_CFG_QUERY_STR_EN must be set to DEF_ENABLED.

2. HTTPc_KEY_VAL type's objects must be used to setup a Query String field. When the field is a single string and not a pair of key-value, the pointer to the value can be left blank and only the pointer to the key will be used.

3. Two methods are offered by the HTTP Client module to add Query String:

• Passing a Key-Value Pairs' Table to the HTTP Client stack.

• Using a hook function that will ask the application for each Key-Value Pair.

Using a Key-Value Pairs' Table#

For the first option, before sending the HTTP request, the application can prepare a table of HTTPc_KEY_VAL objects that the HTTP Client will include in the Query String. The API function HTTPc_ReqSetParam() must be used with the parameter type HTTPc_PARAM_TYPE_REQ_QUERY_STR_TBL to pass out the table to the HTTP Client stack.

Listing - Adding a Query String with Table Example Code#

#define  HTTPc_CFG_QUERY_STR_NBR_MAX       10
#define  HTTPc_CFG_QUERY_STR_KEY_LEN_MAX   50
#define  HTTPc_CFG_QUERY_STR_VAL_LEN_MAX  100

HTTPc_KEY_VAL  HTTPc_ReqQueryStrTbl[HTTPc_CFG_QUERY_STR_NBR_MAX];
CPU_CHAR       HTTPc_ReqQueryStrKeyTbl[HTTPc_CFG_QUERY_STR_NBR_MAX][HTTPc_CFG_QUERY_STR_KEY_LEN_MAX];
CPU_CHAR       HTTPc_ReqQueryStrValTbl[HTTPc_CFG_QUERY_STR_NBR_MAX][HTTPc_CFG_QUERY_STR_VAL_LEN_MAX];

/*
*********************************************************************************************************
*                                         HTTPc_ReqPrepareQueryStr()
*
* Description : Prepare the Query String Table.
*
* Argument(s) : p_tbl    Variable that will received the pointer to the Query String table.
*
* Return(s)   : Number of fields in the Query String table.
*********************************************************************************************************
*/
static  CPU_INT08U  HTTPc_ReqPrepareQueryStr (HTTPc_KEY_VAL  **p_tbl)
{
    HTTPc_KEY_VAL  *p_key_val;

                                                                /* ------------- SET FIRST QUERY ------------- */
    p_key_val         = &HTTPc_ReqQueryStrTbl[0];
    p_key_val->KeyPtr = &HTTPc_ReqQueryStrKeyTbl[0][0];
    p_key_val->ValPtr = &HTTPc_ReqQueryStrValTbl[0][0];

   (void)Str_Copy_N(p_key_val->KeyPtr, "name", HTTPc_CFG_QUERY_STR_KEY_LEN_MAX);
   (void)Str_Copy_N(p_key_val->ValPtr, "Jonh", HTTPc_CFG_QUERY_STR_VAL_LEN_MAX);

    p_key_val->KeyLen = Str_Len_N(p_key_val->KeyPtr, HTTPc_CFG_QUERY_STR_KEY_LEN_MAX);
    p_key_val->ValLen = Str_Len_N(p_key_val->ValPtr, HTTPc_CFG_QUERY_STR_VAL_LEN_MAX);

                                                                /* ------------ SET SECOND QUERY ------------- */
    p_key_val         = &HTTPc_ReqQueryStrTbl[1];
    p_key_val->KeyPtr = &HTTPc_ReqQueryStrKeyTbl[1][0];
    p_key_val->ValPtr =  DEF_NULL;

   (void)Str_Copy_N(p_key_val->KeyPtr, "active", HTTPc_CFG_QUERY_STR_KEY_LEN_MAX);

    p_key_val->KeyLen = Str_Len_N(p_key_val->KeyPtr, HTTPc_CFG_QUERY_STR_KEY_LEN_MAX);

   *p_tbl = &HTTPc_ReqQueryStrTbl[0];

    return (2);
}

/*
*********************************************************************************************************
*                                           HTTPc_ReqPrepare()
*
* Description : Prepare the HTTP request to send.
*
* Argument(s) : p_req    Pointer to the HTTP Request object to configure.
*
* Return(s)   : DEF_OK,   if the request was configured successfully.
*               DEF_FAIL, otherwise.
*********************************************************************************************************
*/
static  CPU_BOOLEAN  HTTPc_ReqPrepare (HTTPc_REQ_OBJ  *p_req)
{
    HTTPc_PARAM_TBL   tbl_obj;
    HTTPc_KEY_VAL    *p_query_str_tbl;
    CPU_INT08U        query_nbr;
    RTOS_ERR          err;

                                                                /* -------- SET STRING QUERY DATA ------------ */
    query_nbr = HTTPc_ReqPrepareQueryStr(&p_query_str_tbl);
    if (query_nbr <= 0) {
        return (DEF_FAIL);
    }

                                                                /* ------ SET STRING QUERY PARAMETERS -------- */
    tbl_obj.EntryNbr = query_nbr;
    tbl_obj.TblPtr   = (void *)p_query_str_tbl;
    HTTPc_ReqSetParam(p_req, HTTPc_PARAM_TYPE_REQ_QUERY_STR_TBL, &tbl_obj, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    ...  /* TODO other operations on request if necessary. */

    return (DEF_OK);
}

Using a Hook Function#

The Second option is to set up a hook function. The hook function will be called by the HTTP Client module to add a field to the Query String. The hook function will be called until it returns DEF_YES to notified the HTTP Client module that all the fields have been added. The API function HTTPc_ReqSetParam() must be used with the parameter type HTTPc_PARAM_TYPE_REQ_QUERY_STR_HOOK to pass out hook function pointer to the HTTP Client module.

Listing - Adding Query String with a Hook Example Code#

#define  HTTPc_CFG_QUERY_STR_NBR_MAX       10
#define  HTTPc_CFG_QUERY_STR_KEY_LEN_MAX   50
#define  HTTPc_CFG_QUERY_STR_VAL_LEN_MAX  100

CPU_INT08U     HTTPc_ReqQueryStrIx;
HTTPc_KEY_VAL  HTTPc_ReqQueryStrTbl[HTTPc_CFG_QUERY_STR_NBR_MAX];
CPU_CHAR       HTTPc_ReqQueryStrKeyTbl[HTTPc_CFG_QUERY_STR_NBR_MAX][HTTPc_CFG_QUERY_STR_KEY_LEN_MAX];
CPU_CHAR       HTTPc_ReqQueryStrValTbl[HTTPc_CFG_QUERY_STR_NBR_MAX][HTTPc_CFG_QUERY_STR_VAL_LEN_MAX];

/*
*********************************************************************************************************
*                                           HTTPc_ReqPrepare()
*
* Description : Prepare the HTTP request to send.
*
* Argument(s) : p_req    Pointer to the HTTP Request object to configure.
*
* Return(s)   : DEF_OK,   if the request was configured successfully.
*               DEF_FAIL, otherwise.
*********************************************************************************************************
*/
static  CPU_BOOLEAN  HTTPc_ReqPrepare (HTTPc_REQ_OBJ  *p_req)
{
    RTOS_ERR  err;

                                                                /* -------- SET STRING QUERY PARAMETER ------- */
    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_REQ_QUERY_STR_HOOK,
                     &HTTPc_ReqQueryStrHook,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    p_req->UserDataPtr = (void *)&HTTPc_ReqQueryStrIx;

    ...  /* TODO other operations on request if necessary. */

    return (DEF_OK);
}

/*
*********************************************************************************************************
*                                         HTTPc_ReqQueryStrHook()
*
* Description : Hook function to retrieve the data of the Query String.
*
* Argument(s) : p_conn     Pointer to the HTTP Connection object.
*
*               p_req      Pointer to the HTTP Request object.
*
*               p_key_val  Variable that will receive the pointer to the Key-Val object.
*
* Return(s)   : DEF_YES, if all the fields of the Query String have been passed.
*               DEF_NO,  otherwise.
*********************************************************************************************************
*/
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;
    CPU_INT08U      index;

    index = *(CPU_INT08U)p_req->UserDataPtr;

    switch(index) {
        case 0:
             p_kvp         = &HTTPc_ReqQueryStrTbl[0];
             p_kvp->KeyPtr = &HTTPc_ReqQueryStrKeyTbl[0][0];
             p_kvp->ValPtr = &HTTPc_ReqQueryStrValTbl[0][0];
            (void)Str_Copy_N(p_kvp->KeyPtr, "name", HTTPc_CFG_QUERY_STR_KEY_LEN_MAX);
            (void)Str_Copy_N(p_kvp->ValPtr, "Jonh", HTTPc_CFG_QUERY_STR_VAL_LEN_MAX);
             p_kvp->KeyLen = Str_Len_N(p_kvp->KeyPtr, HTTPc_CFG_QUERY_STR_KEY_LEN_MAX);
             p_kvp->ValLen = Str_Len_N(p_kvp->ValPtr, HTTPc_CFG_QUERY_STR_VAL_LEN_MAX);
            *p_key_val = p_kvp;
             index++;
            *(CPU_INT08U)p_req->UserDataPtr = index;
             return (DEF_NO);

        case 1:
             p_kvp         = &HTTPc_ReqQueryStrTbl[1];
             p_kvp->KeyPtr = &HTTPc_ReqQueryStrKeyTbl[1][0];
             p_kvp->ValPtr =  DEF_NULL;
            (void)Str_Copy_N(p_kvp->KeyPtr, "active", HTTPc_CFG_QUERY_STR_KEY_LEN_MAX);
             p_kvp->KeyLen = Str_Len_N(p_kvp->KeyPtr, HTTPc_CFG_QUERY_STR_KEY_LEN_MAX);
            *p_key_val = p_kvp;
             index = 0;
            *(CPU_INT08U)p_req->UserDataPtr = index;
             return (DEF_YES);

        default:
            *p_key_val = DEF_NULL;
             index = 0;
            *(CPU_INT08U)p_req->UserDataPtr = index;
             return (DEF_YES);
    }
}

HTTP Client Form Submission#

HTTP Client offers several structures and API functions to simplify the formatting and transmission of Forms for the development of an HTTP Client application.

For more details on HTTP Forms, see section Form .

Form Field Types#

HTTP Client offers three types of form field. Each type is associated with a structure that the application can used to create objects:

• Key-Value Pair : Simple pair of key and value strings. Can be used with the Application type form and the Multipart type form.

• Extended Key-Value Pair : Key-Value pair where the string value is not specified but a hook function is to allow the HTTP Client stack to retrieve the value when the form is formatted. Can be used with the Multipart type form only.

• Multipart File : Use to upload file to an HTTP server inside a Multipart type form. Can be used with the Multipart type form only.

Form API#

The application should incorporate all the form fields into a table using the API functions offered below :

• HTTPc_FormAddKeyVal() to add a simple Key-Value pair object to a form table.

• HTTPc_FormAddKeyValExt() to add a Extended Key-Value pair object to a form table.

• HTTPc_FormAddFile() to add a Multipart File object to a form table.

Once the form fields' table is created, two possibilities are offered.

The first option is valid only if the table contains simple Key-Value pairs and consists of formatting the form on the application side with one of the API functions below:

• HTTPc_FormAppFmt() to format the table into an Application-type form.

• HTTPc_FormMultipartFmt() to format the table into a Multipart-type form.

Afterwards the application can transmit the formatted form like any other body types.

The second option is to pass the form fields table to the HTTP Client module so that the formatting can be done internally by the HTTP Client core. This option allows you to have a different form field type in the table. The HTTP Client module will take care of calling the hook functions to recover data from the application for extended Key-Value pair object and Multipart File objects.

The form fields table can be passed to the HTTP Client module by calling the HTTPc_ReqSetParam() function will the parameter type HTTPc_PARAM_TYPE_REQ_FORM_TBL and the macro configuration HTTPc_CFG_FORM_EN must be set to DEF_ENABLED.

Examples#

Example #1: Application Type Form with the form formatting on the application side#

Listing - Form Submission Example Code #1#

#define  HTTP_SERVER_HOSTNAME             "www.example.com"
#define  HTTPc_EX_CFG_CONN_BUF_SIZE         512
#define  HTTPc_EX_CFG_FORM_FIELD_NBR_MAX     10
#define  HTTPc_EX_CFG_FORM_BUF_SIZE        4096
#define  HTTPc_EX_CFG_KEY_LEN_MAX            50
#define  HTTPc_EX_CFG_VAL_LEN_MAX           100

HTTPc_CONN_OBJ        HTTPcEx_Conn;
CPU_CHAR              HTTPcEx_ConnBuf[HTTPc_CFG_CONN_BUF_SIZE];
HTTPc_REQ_OBJ         HTTPcEx_Req;
HTTPc_RESP_OBJ        HTTPcEx_Resp;
HTTPc_FORM_TBL_FIELD  HTTPcEx_ReqFormTbl[HTTPc_EX_CFG_FORM_FIELD_NBR_MAX];
CPU_CHAR              HTTPcEx_FormBufTbl[HTTPc_EX_CFG_FORM_BUF_SIZE];
HTTPc_KEY_VAL         HTTPcEx_KeyVal_Tbl[HTTPc_EX_CFG_FORM_FIELD_NBR_MAX];
CPU_CHAR              HTTPcEx_KeyVal_KeyTbl[HTTPc_EX_CFG_FORM_FIELD_NBR_MAX][HTTPc_EX_CFG_KEY_LEN_MAX];
CPU_CHAR              HTTPcEx_KeyVal_ValTbl[HTTPc_EX_CFG_FORM_FIELD_NBR_MAX][HTTPc_EX_CFG_VAL_LEN_MAX];

/*
*********************************************************************************************************
*                                      HTTPcEx_ReqSendFormApp()
*
* Description : Example function to send an HTTP POST request containing an Application type form.
*
* Argument(s) : None.
*
* Return(s)   : DEF_OK,   if the HTTP transaction was successful.
*               DEF_FAIL, otherwise.
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcEx_ReqSendFormApp (void)
{
    HTTPc_CONN_OBJ        *p_conn;
    HTTPc_REQ_OBJ         *p_req;
    HTTPc_RESP_OBJ        *p_resp;
    CPU_CHAR              *p_buf;
    CPU_CHAR              *p_data;
    HTTPc_FORM_TBL_FIELD  *p_form_tbl;
    CPU_INT08U             form_nbr;
    CPU_INT16U             content_len;
    RTOS_ERR               err;

    p_conn = &HTTPcEx_ConnTbl[0];
    p_req  = &HTTPcEx_ReqTbl[0];
    p_resp = &HTTPcEx_RespTbl[0];
    p_buf  = &HTTPcEx_BufTbl[0][0];

                                                                /* ------------- SET FORM TO SEND ------------ */
    form_nbr = HTTPcEx_ReqPrepareFormApp(&p_form_tbl);
    if (form_nbr <= 0) {
        return (DEF_FAIL);
    }

    p_data      = &HTTPcEx_FormBufTbl[0];
    content_len = HTTPc_FormMultipartFmt(p_data,
                                         APP_HTTPc_CFG_FORM_BUF_SIZE,
                                         p_form_tbl,
                                         form_nbr,
                                        &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ------------ INIT NEW CONNECTION ---------- */
    HTTPc_ConnClr(p_conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                                /* ----------- SET CONN'S CALLBACKS ---------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                      &HTTPcEx_ConnCloseCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* ------------- INIT NEW REQUEST ------------ */
    HTTPc_ReqClr(p_req, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ------- SET REQUEST BODY PARAMETERS ------- */
    content_type = HTTP_CONTENT_TYPE_MULTIPART_FORM;
    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_TYPE,
                     &content_type,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_LEN,
                     &content_len,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_REQ_BODY_HOOK,
                     &HTTPcEx_ReqBodyHook,
                     &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ----------- SET REQ'S CALLBACKS ----------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_TRANS_ERR_CALLBACK,
                     &HTTPcEx_TransErrCallback,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                               /* ------------- OPEN CONNECTION ------------- */
    str_len = Str_Len(HTTP_SERVER_HOSTNAME);
    result  = HTTPc_ConnOpen(p_conn,
                             p_buf,
                             HTTPc_EX_CFG_BUF_SIZE,
                             HTTP_SERVER_HOSTNAME,
                             str_len,
                             HTTPc_FLAG_NONE,
                            &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    if (result == DEF_OK) {
        printf("Connection to server succeeded.\n\r");
    } else {
        printf("Connection to server failed.\n\r");
    }

                                                                /* ------------ SEND HTTP REQUEST ------------ */
    str_len = Str_Len("/form");
    result  = HTTPc_ReqSend(p_conn,
                            p_req,
                            p_resp,
                            HTTP_METHOD_POST,
                            "/form",
                            str_len,
                            HTTPc_FLAG_NONE,
                           &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    if (result == DEF_OK) {
        printf("%s\n\r", p_resp->ReasonPhrasePtr);
    }

    return (DEF_OK);
}

/*
*********************************************************************************************************
*                                       HTTPcEx_ReqPrepareFormApp()
*
* Description : Example function to prepare the form table for an application type form
*
* Argument(s) : p_form_tbl  Variable that will received the pointer to the form table.
*
* Return(s)   : Number of fields in the table.
*********************************************************************************************************
*/

static  CPU_INT08U  HTTPcEx_ReqPrepareFormApp (HTTPc_FORM_TBL_FIELD  **p_form_tbl)
{
    HTTPc_FORM_TBL_FIELD  *p_tbl;
    HTTPc_KEY_VAL         *p_kvp;
    RTOS_ERR               err;

    p_tbl = &HTTPcEx_ReqFormTbl[0];
                                                                /* ---------- ADD FIRST FORM FIELD ----------- */
    p_kvp          = &HTTPcEx_KeyVal_Tbl[0];
    p_kvp->KeyPtr  = &HTTPcEx_KeyVal_KeyTbl[0][0];
    p_kvp->ValPtr  = &HTTPcEx_KeyVal_ValTbl[0][0];
    p_kvp->KeyLen  = Str_Len("Name");
    p_kvp->ValLen  = Str_Len("John Smith");
   (void)Str_Copy_N(p_kvp->KeyPtr, "Name",       p_kvp->KeyLen);
   (void)Str_Copy_N(p_kvp->ValPtr, "Jonh Smith", p_kvp->ValLen);
    HTTPc_FormAddKeyVal(p_tbl, p_kvp, &err);

                                                                /* ---------- ADD SECOND FORM FIELD ---------- */
    p_tbl++;
    p_kvp++;
    p_kvp->KeyPtr    = &HTTPcEx_KeyVal_KeyTbl[1][0];
    p_kvp->ValPtr    = &HTTPcEx_KeyVal_ValTbl[1][0];
    p_kvp->KeyLen = Str_Len("Book");
    p_kvp->ValLen = Str_Len("Implementing IPv6 Second Edition");
   (void)Str_Copy_N(p_kvp->KeyPtr, "Book",                             p_kvp->KeyLen);
   (void)Str_Copy_N(p_kvp->ValPtr, "Implementing IPv6 Second Edition", p_kvp->ValLen);
    HTTPc_FormAddKeyVal(p_tbl, p_kvp, &err);

   *p_form_tbl = &HTTPcEx_ReqFormTbl[0];

    return (2);
}

HTTP Client Persistent Connection#

Persistent Connection allows you to send multiple HTTP requests one after another on the same opened connection before closing it. For more details, refer to section Persistent Connection .

Example#

In this example, two HTTP requests are queued on an HTTP Connection before the client closes the connection.

The function HTTPc_ReqSend() is called with the flag HTTPc_FLAG_REQ_NO_BLOCK, so the function is not blocking and will return before the transaction completes. Therefore the On Transaction Complete hook must be set to retrieve the HTTP response.

Listing - Persistent Connection Example Code#

#define  HTTP_SERVER_HOSTNAME                            "www.example.com"

#define  HTTPc_EX_CFG_CONN_NBR_MAX                        5u
#define  HTTPc_EX_CFG_REQ_NBR_MAX                         5u
#define  HTTPc_EX_CFG_BUF_SIZE                          512u

HTTPc_CONN_OBJ  HTTPcEx_ConnTbl[HTTPc_EX_CFG_CONN_NBR_MAX];
HTTPc_REQ_OBJ   HTTPcEx_ReqTbl[HTTPc_EX_CFG_REQ_NBR_MAX];
HTTPc_RESP_OBJ  HTTPcEx_RespTbl[HTTPc_EX_CFG_REQ_NBR_MAX];
CPU_CHAR        HTTPcEx_BufTbl[HTTPc_EX_CFG_CONN_NBR_MAX][HTTPc_EX_CFG_BUF_SIZE ];

CPU_BOOLEAN     close_conn = DEF_NO;
CPU_BOOLEAN     req1_done = DEF_NO;
CPU_BOOLEAN     req2_done = DEF_NO;

/*
*********************************************************************************************************
*                                         HTTPcEx_ReqSendGET()
*
* Description : Example function to Send Requests on persistent connection.
*
* Argument(s) : None.
*
* Return(s)   : DEF_YES, if request successfully sent.
*               DEF_NO,  otherwise.
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcEx_ReqSendGET (void)
{
    HTTPc_CONN_OBJ  *p_conn;
    HTTPc_REQ_OBJ   *p_req1;
    HTTPc_REQ_OBJ   *p_req2;
    HTTPc_RESP_OBJ  *p_resp1;
    HTTPc_RESP_OBJ  *p_resp2;
    CPU_CHAR        *p_buf;
    CPU_BOOLEAN      persistent;
    CPU_BOOLEAN      result;
    RTOS_ERR         err;

    p_conn  = &HTTPcEx_ConnTbl[0];
    p_buf   = &HTTPcEx_BufTbl[0][0];
    p_req1  = &HTTPcEx_ReqTbl[0];
    p_req2  = &HTTPcEx_ReqTbl[1];
    p_resp1 = &HTTPcEx_RespTbl[0];
    p_resp2 = &HTTPcEx_RespTbl[1];

                                                                /* ------------ INIT NEW CONNECTION ---------- */
    HTTPc_ConnClr(p_conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ----------- SET PERSISTENT MODE ----------- */
    persistent = DEF_YES;
    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_PERSISTENT,
                      &persistent,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ---------- SET CONN'S CALLBACKS ----------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                      &HTTPcEx_ConnCloseCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* ------------ INIT NEW REQUESTS ------------ */
    HTTPc_ReqClr(p_req1, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqClr(p_req2, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ---- SET REQ/RESP CALLBACK FUNCTIONS ------ */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ReqSetParam(p_req1,
                      HTTPc_PARAM_TYPE_TRANS_COMPLETE_CALLBACK,
                     &HTTPcEx_TransDoneCallback,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(p_req2,
                      HTTPc_PARAM_TYPE_TRANS_COMPLETE_CALLBACK,
                     &HTTPcEx_TransDoneCallback,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(p_req1,
                      HTTPc_PARAM_TYPE_TRANS_ERR_CALLBACK,
                     &HTTPcEx_TransErrCallback,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(p_req2,
                      HTTPc_PARAM_TYPE_TRANS_ERR_CALLBACK,
                     &HTTPcEx_TransErrCallback,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* ------------ OPEN CONNECTION -------------- */
    str_len = Str_Len(HTTP_SERVER_HOSTNAME);
    result  = HTTPc_ConnOpen(p_conn,
                             p_buf,
                             HTTPc_EX_CFG_BUF_SIZE,
                             HTTP_SERVER_HOSTNAME,
                             str_len,
                             HTTPc_FLAG_NONE,
                            &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    if (result == DEF_OK) {
        printf("Connection to server succeeded.\n\r");
    } else {
        printf("Connection to server failed.\n\r");
    }

                                                                /* ----------- SEND HTTP REQUESTS ------------ */
    str_len = Str_Len("//");
    result  = HTTPc_ReqSend(p_conn,
                            p_req1,
                            p_resp1,
                            HTTP_METHOD_GET,
                            "//",
                            str_len,
                            HTTPc_FLAG_REQ_NO_BLOCK,
                           &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    (void)HTTPc_ReqSend(p_conn,
                        p_req2,
                        p_resp2,
                        HTTP_METHOD_GET,
                       "//",
                        str_len,
                        HTTPc_FLAG_REQ_NO_BLOCK,
                       &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    while (close_conn == DEF_NO)
    {
        /* Do OS delay. */
    };

                                                                /* --------- CLOSE HTTP CONNECTION ----------- */
    close_conn = DEF_NO;
    HTTPc_ConnClose(p_conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    return (DEF_OK);
}

/*
*********************************************************************************************************
*                                         HTTPcEx_TransDoneCallback()
*
* Description : Example callback function to be notified when an HTTP transaction is completed.
*
* Argument(s) : p_conn_obj   Pointer to current HTTPc Connection object.
*
*               p_req_obj    Pointer to current HTTPc Request object.
*
*               p_resp_obj   Pointer to current HTTPc Response object.
*
*               status       Status of the HTTP transaction:
*                                DEF_OK,   transaction succeeded.
*                                DEF_FAIL, transaction failed.
*
* Return(s)   : None.
*********************************************************************************************************
*/

void  HTTPcEx_TransDoneCallback (HTTPc_CONN_OBJ  *p_conn_obj,
                                 HTTPc_REQ_OBJ   *p_req_obj,
                                 HTTPc_RESP_OBJ  *p_resp_obj,
                                 CPU_BOOLEAN      status)
{
    HTTPc_REQ_OBJ      *p_req1;
    HTTPc_REQ_OBJ      *p_req2;

    p_req1  = &HTTPcEx_ReqTbl[0];
    p_req2  = &HTTPcEx_ReqTbl[1];

    if (p_req_obj == p_req1) {
        if (status == DEF_OK) {
            printf("Transaction #1: %s\n\r", p_resp_obj->ReasonPhrasePtr);
        } else {
            printf("Transaction #1 failed\n\r");
        }
        req1_done = DEF_YES;
     } else if (p_req_obj == p_req2) {
        if (status == DEF_OK) {
            printf("Transaction #2: %s\n\r", p_resp_obj->ReasonPhrasePtr);
        } else {
            printf("Transaction #2 failed\n\r");
        }
        req2_done = DEF_YES;
    } else {
        printf("Unexpected error.\n\r");
    }

    close_conn = req1_done & req2_done;
}

HTTP Client Retrieve HTTP Response Data#

The HTTPc Response object will be filled by the HTTP Client stack with the fields below received in the HTTP response:

• The Server HTTP version

• Status Code

• Reason phrase

• Content type (if body present)

• Content Length (if body present)

If the function HTTPc_ReqSend() was called in the blocking mode and the function returned with no errors, then the HTTPc Response object can be read by the application after the function call. Otherwise, the application must wait until the On Transaction Complete function is called by the HTTP Client stack to read the HTTPc Response object.

Two hook functions allow the application to retrieve more data from the HTTP response :

• On Response Header

• On Response Body

The first hook allows the application to retrieve header fields contained in the HTTP response. If the hook function is set via the function HTTPc_ReqSetParam() with the parameter type HTTPc_PARAM_TYPE_RESP_HDR_HOOK, the hook will be called by the HTTP Client module for each header field parsed and recognized by the stack. The application as therefore the liberty to copy the data received on its side inside the hook function.

The second hook allows the application to retrieve the data contained in the HTTP response body. If the hook function is set via the function HTTPc_ReqSetParam() with the parameter type HTTPc_PARAM_TYPE_RESP_BODY_HOOK, the hook will be called by the HTTP Client module for each piece of data received until all is received.

Examples#

Blocking Mode#

In the first example below, the function HTTPc_ReqSend() is called in blocking mode. Therefore, the HTTPc Response object can be read just after the function call.

Listing - Retrieve HTTP Response Data Example Code #1#

#define  HTTP_SERVER_HOSTNAME   "www.example.com"
#define  HTTPc_EX_CFG_BUF_SIZE   1024

/*
*********************************************************************************************************
*                                         HTTPcEx_ReqSendGET()
*
* Description : Example function to send a GET request and retrieve HTTP response.
*
* Argument(s) : None.
*
* Return(s)   : DEF_OK,   if HTTP transaction was successful.
*               DEF_FAIL, otherwise.
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcEx_ReqSendGET (void)
{
    HTTPc_CONN_OBJ   conn;
    HTTPc_REQ_OBJ    req;
    HTTPc_RESP_OBJ   resp;
    CPU_CHAR         buf[HTTPc_EX_CFG_BUF_SIZE];
    HTTPc_FLAGS      flags;
    CPU_SIZE_T       str_len;
    CPU_BOOLEAN      result;
    RTOS_ERR         err;

                                                                /* ------------ INIT NEW CONNECTION ---------- */
    HTTPc_ConnClr(&conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ----------- SET CONN'S CALLBACKS ---------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ConnSetParam(&conn,
                        HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                       &HTTPcEx_ConnCloseCallback,
                       &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* ------------- INIT NEW REQUEST ------------ */
    HTTPc_ReqClr(&req, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* --------- SET TRANS HOOK FUNCTIONS -------- */
    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_RESP_HDR_HOOK,
                      &HTTPcEx_RespHdrHook,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_RESP_BODY_HOOK,
                      &HTTPcEx_RespBodyHook,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ------ SET TRANS CALLBACK FUNCTIONS ------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ReqSetParam(&req,
                       HTTPc_PARAM_TYPE_TRANS_ERR_CALLBACK,
                      &HTTPcEx_TransErrCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* ------------- OPEN CONNECTION ------------- */
    str_len = Str_Len(HTTP_SERVER_HOSTNAME);
    result  = HTTPc_ConnOpen(&conn,
                             &buf,
                              HTTPc_EX_CFG_BUF_SIZE,
                              HTTP_SERVER_HOSTNAME,
                              str_len,
                              HTTPc_FLAG_NONE,
                             &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    if (result == DEF_OK) {
        printf("Connection to server succeeded.\n\r");
    } else {
        printf("Connection to server failed.\n\r");
    }

                                                                /* ------------ SEND HTTP REQUEST ------------ */
    str_len = Str_Len("/");
    result  = HTTPc_ReqSend(&conn,
                            &req,
                            &resp,
                             HTTP_METHOD_GET,
                            "/",
                             str_len,
                             HTTPc_FLAG_NONE,
                           &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    if (result == DEF_OK) {
        printf("%s\n\r", resp.ReasonPhrasePtr);
    }

    return (DEF_OK);
}

No-Blocking Mode#

In this second example, the function HTTPc_ReqSend() is called in non-blocking mode. Therefore, the HTTPc Response object can be read once the On Transaction Complete function is called.

Listing - Retrieve HTTP Response Data Example Code #2#

#define  HTTP_SERVER_HOSTNAME   "www.example.com"
#define  HTTPc_EX_CFG_BUF_SIZE   1024

HTTPc_CONN_OBJ  HTTPcEx_Conn;
HTTPc_REQ_OBJ   HTTPcEx_Req;
HTTPc_RESP_OBJ  HTTPcEx_Resp;
CPU_CHAR        HTTPcEx_ConnBuf[HTTPc_EX_CFG_BUF_SIZE];

/*
*********************************************************************************************************
*                                         HTTPcEx_ReqSendGET()
*
* Description : Example function to send a GET request and retrieve HTTP response.
*
* Argument(s) : None.
*
* Return(s)   : DEF_OK,   if HTTP transaction was successful.
*               DEF_FAIL, otherwise.
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcEx_ReqSendGET (void)
{
    HTTPc_CONN_OBJ   *p_conn;
    HTTPc_REQ_OBJ    *p_req;
    HTTPc_RESP_OBJ   *p_resp;
    CPU_CHAR         *p_buf;
    CPU_SIZE_T        str_len;
    CPU_BOOLEAN       result;
    HTTPc_ERR         err;

    p_conn = &HTTPcEx_Conn;
    p_req  = &HTTPcEx_Req;
    p_resp = &HTTPcEx_Resp;
    p_buf  = &HTTPcEx_ConnBuf[0];

                                                                /* ------------ INIT NEW CONNECTION ---------- */
    HTTPc_ConnClr(p_conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ----------- SET CONN'S CALLBACKS ---------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ConnSetParam(p_conn,
                       HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                      &HTTPcEx_ConnCloseCallback,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* ------------- INIT NEW REQUEST ------------ */
    HTTPc_ReqClr(p_req, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* --------- SET TRANS HOOK FUNCTIONS -------- */
    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_RESP_HDR_HOOK,
                     &HTTPcEx_RespHdrHook,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_RESP_BODY_HOOK,
                     &HTTPcEx_RespBodyHook,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

                                                                /* ------ SET TRANS CALLBACK FUNCTIONS ------- */
#if (HTTPc_CFG_MODE_ASYNC_TASK_EN == DEF_ENABLED)
    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_TRANS_COMPLETE_CALLBACK,
                     &HTTPcEx_TransDoneCallback,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    HTTPc_ReqSetParam(p_req,
                      HTTPc_PARAM_TYPE_TRANS_ERR_CALLBACK,
                     &HTTPcEx_TransErrCallback,
                     &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
#endif

                                                                /* ------------- OPEN CONNECTION ------------- */
    str_len = Str_Len(HTTP_SERVER_HOSTNAME);
    result  = HTTPc_ConnOpen(p_conn,
                             p_buf,
                             HTTPc_EX_CFG_BUF_SIZE,
                             HTTP_SERVER_HOSTNAME,
                             str_len,
                             HTTPc_FLAG_NONE,
                            &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    if (result == DEF_OK) {
        printf("Connection to server succeeded.\n\r");
    } else {
        printf("Connection to server failed.\n\r");
    }

                                                                /* ------------ SEND HTTP REQUEST ------------ */
    str_len = Str_Len("/");
    result  = HTTPc_ReqSend(p_conn,
                            p_req,
                            p_resp,
                            HTTP_METHOD_GET,
                           "/",
                            str_len,
                            HTTPc_FLAG_REQ_NO_BLOCK,
                           &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }

    return (DEF_OK);
}

/*
*********************************************************************************************************
*                                      HTTPcEx_TransDoneCallback()
*
* Description : Example callback function to be notified when an HTTP transaction was completed.
*
*               Once this callback is called, the HTTPc Response object is ready to be read by the application
*               if no error occurred.
*
* Argument(s) : p_conn     Pointer to current HTTPc Connection object.
*
*               p_req      Pointer to current HTTPc Request object.
*
*               p_resp     Pointer to current HTTPc Response object.
*
*               status     DEF_OK, if transaction was complete successfully.
*                          DEF_NO, otherwise.
*
* Return(s)   : None.
*********************************************************************************************************
*/

static  void  HTTPcEx_TransDoneCallback(HTTPc_CONN_OBJ    *p_conn,
                                        HTTPc_REQ_OBJ     *p_req,
                                        HTTPc_RESP_OBJ    *p_resp,
                                        CPU_BOOLEAN        status)
{
    if (status == DEF_OK) {
        printf("Transaction response status: %s\n\r", p_resp->ReasonPhrasePtr);
    } else {
        printf("Transaction failed\n\r");
    }
}

Response Header and Body Hook Functions#

The example code below is an implementation of the On Response Header hook function and the On Response Body hook function.

Listing - Response Hook Functions Example Code#

#define  HTTPc_EX_CFG_HDR_VAL_BUF_LEN  100

CPU_CHAR  HTTPcEx_HdrValBuf[HTTPc_EX_CFG_HDR_VAL_BUF_LEN];

/*
*********************************************************************************************************
*                                         HTTPcEx_RespHdrHook()
*
* Description : Example hook function to retrieve Header Fields received in the HTTP response.
*
* Argument(s) : p_conn      Pointer to current HTTPc Connection object.
*
*               p_req       Pointer to current HTTPc Request object.
*
*               hdr_field   Header field type received.
*
*               p_hdr_val   Pointer to Header field value string received.
*
*               val_len     Length of value string.
*
* Return(s)   : None.
*********************************************************************************************************
*/

static  void  HTTPcEx_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)
{
    CPU_CHAR    *p_buf;
    CPU_INT16U   len;

    p_buf = &HTTPcEx_HdrValBuf[0];

    switch (hdr_field) {
        case HTTP_HDR_FIELD_DATE:
        case HTTP_HDR_FIELD_SERVER:
             len = DEF_MIN((HTTPc_EX_CFG_HDR_VAL_BUF_LEN - 1), val_len);
             Mem_Copy(p_buf, p_hdr_val, len);
             p_buf += len;
            *p_buf  = '\0';
             break;

        default:
             break;
    }
}

/*
*********************************************************************************************************
*                                         HTTPcEx_RespBodyHook()
*
* Description : Example hook function to retrieve body data.
*
*               In this example, a html file is received and is copied into a file.
*
* Argument(s) : p_conn        Pointer to current HTTPc Connection object.
*
*               p_req         Pointer to current HTTPc Request object.
*
*               content_type  Content type of the body received in the HTTP response.
*
*               p_data        Pointer to the data piece received.
*
*               data_len      Length of data piece received.
*
*               last_chunk    DEF_YES, if this represent the last piece of the data body to receive.
*                             DEF_NO,  if data still remains to be received.
*
* Return(s)   : None.
*********************************************************************************************************
*/

static  void  HTTPcEx_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;
    CPU_SIZE_T      size_wr;
    CPU_SIZE_T      size_wr_tot;
    CPU_BOOLEAN     is_open;
    RTOS_ERR        err;

    file_handle = FSFile_Open(FSWrkDir_NullHandle,
                             "ram0/index.html",
                             (FS_FILE_ACCESS_MODE_WR | FS_FILE_ACCESS_MODE_CREATE | FS_FILE_ACCESS_MODE_APPEND),
                             &err);
    if (err.Code != RTOS_ERR_NONE) {
        return;
    }

    switch (content_type) {
        case HTTP_CONTENT_TYPE_HTML:
             if (p_data != DEF_NULL) {
                 size_wr     = 0u;
                 size_wr_tot = 0u;
                 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;
    }

    FSFile_Close(file_handle, &err);
}

HTTP Client WebSocket#

WebSocket allows to create a full duplex communication channel over a single TCP/HTTP connection and enables streams of structured messages. It use simple and efficient headers to describe those messages which offer a better solution when it come to send small data at higher rate. For more details, refer to section WebSocket .

This section regroups topics to help developing a custom WebSocket application with the HTTP Client module. Examples are include in many sub-sections.

• HTTP Client Upgrading an HTTP Connection

• HTTP Client Message reception

• HTTP Client Sending Message

• HTTP Client Closing a Connection

HTTP Client Upgrading an HTTP Connection#

Because it uses many HTTP functionalities for opening handshake, the WebSocket protocol has been integrated has part of Micrium OS HTTP Client module. Furthermore, all the HTTP Client request features, such as query string, are available during the opening handshake request. Here are the usual steps to upgrade a HTTP connection to WebSocket:

1. First, create a HTTPc Connection to the desired server using HTTPc_ConnOpen(). If successful, it will return a valid HTTPc_CONN_OBJ object that can be used for the next request.

2. Before sending an Upgrade Request to the server, an HTTPc_WEBSOCK_OBJ object may be configured by using HTTPc_WebSockSetParam() function. Note that WebSocket Message Reception is done through hook functions that are configured in HTTPc_WEBSOCK_OBJ object passed during the WebSocket Upgrade.

3. Because the WebSocket opening handshake is essentially a specific HTTP Request with specific headers, HTTPc_WebSockUpgrade() function is available to simplify the connection upgrade. It will automatically set the mandatory headers and validates the response from the server. Because it also uses a HTTPc_REQ_OBJ object, you can use all the features available during a normal HTTP Request.

4. Finally, when the opening handshake is successful, the connection that has been established in step 1 has now upgraded to WebSocket and is no more related to HTTP. At this point, HTTPc_WebSockSend() can be used for WebSocket Message Transmission and the WebSocket Message Reception will be processed through the RX hook configured in HTTPc_WEBSOCK_OBJ.

Related Hooks#

Example#

The following example simply shows how to upgrade an HTTP connection to Websocket. As you can see below, it will first open an HTTP connection to the remote server and then upgrade it. Note that there's no Message Reception mechanism configured in this example.

Listing - Upgrading an HTTP Connection#

#include <rtos/net/include/http_client.h>

/*
*********************************************************************************************************
*                                            LOCAL DEFINES
*********************************************************************************************************
*/
#define  HTTPc_EXAMPLE_URI              "server.example.com"
#define  HTTPc_EXAMPLE_RESSOURCE        "/echo"
#define  HTTPc_EXAMPLE_CONN_BUF_LEN     1024

/*
*********************************************************************************************************
*                                       LOCAL GLOBAL VARIABLES
*********************************************************************************************************
*/

static  HTTPc_CONN_OBJ         HTTPcExample_Conn;
static  CPU_CHAR               HTTPcExample_ConnBuf[HTTPc_EXAMPLE_CONN_BUF_LEN];
static  HTTPc_REQ_OBJ          HTTPcExample_Req;
static  HTTPc_RESP_OBJ         HTTPcExample_Resp;
static  HTTPc_WEBSOCK_OBJ      HTTPcExample_WebSock;

/*
*********************************************************************************************************
*                                      LOCAL FUNCTION PROTOTYPES
*********************************************************************************************************
*/

static void  HTTPcExample_ConnOnClose    (HTTPc_CONN_OBJ              *p_conn,
                                          HTTPc_CONN_CLOSE_STATUS      close_status,
                                          HTTPc_ERR                    err);

static void  HTTPcExample_WebSockOnOpen  (HTTPc_CONN_OBJ              *p_conn);

static void  HTTPcExample_WebSockOnClose (HTTPc_CONN_OBJ              *p_conn,
                                          HTTPc_WEBSOCK_CLOSE_CODE     close_code,
                                          HTTPc_WEBSOCK_CLOSE_REASON  *p_reason) ;

/*
*********************************************************************************************************
*                                               EXAMPLE
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcExample_OpenWebSocket (void)
{
    CPU_BOOLEAN  result;
    RTOS_ERR     err;
                                                            /* ----------- INIT NEW CONNECTION & REQUEST ----- */
                                                            /* Always Clear the object.                        */
    HTTPc_ConnClr(&HTTPcExample_Conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    HTTPc_ReqClr(&HTTPcExample_Req, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    HTTPc_WebSockClr(&HTTPcExample_WebSock, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                            /* ------------- SET ON CONNECTION CLOSE --------- */
                                                            /* This callback is always required.               */
    HTTPc_ConnSetParam(        &HTTPcExample_Conn,
                                HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                       (void *) HTTPcExample_ConnOnClose,
                               &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                            /* ----------------- OPEN CONNECTION ------------- */
    result = HTTPc_ConnOpen(&HTTPcExample_Conn,
                             HTTPcExample_ConnBuf,
                             HTTPc_EXAMPLE_CONN_BUF_LEN,
                             HTTPc_EXAMPLE_URI,
                             sizeof(HTTPc_EXAMPLE_URI),
                             HTTPc_FLAG_NONE,
                            &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                            /* --------------- SET WEBSOCK ON OPEN ----------- */
    HTTPc_WebSockSetParam(        &HTTPcExample_WebSock,
                                   HTTPc_PARAM_TYPE_WEBSOCK_ON_OPEN,
                          (void *) HTTPcExample_WebSockOnOpen,
                                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                            /* --------------- SET WEBSOCK ON CLOSE ---------- */
    HTTPc_WebSockSetParam(        &HTTPcExample_WebSock,
                                   HTTPc_PARAM_TYPE_WEBSOCK_ON_CLOSE,
                          (void *) HTTPcExample_WebSockOnClose,
                                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                            /* ------- UPGRADE HTTP CONNECTION TO WEBSOCKET -- */
    result = HTTPc_WebSockUpgrade(&HTTPcExample_Conn,
                                  &HTTPcExample_Req,
                                  &HTTPcExample_Resp,
                                  &HTTPcExample_WebSock,
                                   HTTPc_EXAMPLE_RESSOURCE,
                                   sizeof(HTTPc_EXAMPLE_RESSOURCE),
                                   HTTPc_FLAG_NONE,
                                  &err);
    if (result != DEF_OK) {
        return (DEF_FAIL);
    }

    return (DEF_OK);
}

/*
*********************************************************************************************************
*                                      CONNECTION ON CLOSE CALLBACK
*********************************************************************************************************
*/

static void  HTTPcExample_ConnOnClose (HTTPc_CONN_OBJ           *p_conn,
                                       HTTPc_CONN_CLOSE_STATUS   close_status,
                                       RTOS_ERR                  err)
{
                                                            /* Called  when a connection closes.               */
}

/*
*********************************************************************************************************
*                                        WEBSOCK ON OPEN CALLBACK
*********************************************************************************************************
*/

static void  HTTPcExample_WebSockOnOpen (HTTPc_CONN_OBJ           *p_conn)
{
                                                            /* Called  when a WebSocket Upgrade is successful. */
}

/*
*********************************************************************************************************
*                                        WEBSOCK ON CLOSE CALLBACK
*********************************************************************************************************
*/

static void  HTTPcExample_WebSockOnClose (HTTPc_CONN_OBJ              *p_conn,
                                          HTTPc_WEBSOCK_CLOSE_CODE     close_code,
                                          HTTPc_WEBSOCK_CLOSE_REASON  *p_reason)
{
                                                            /* Called when a WebSocket Connection has closed.  */
}

HTTP Client Message reception#

In the WebSocket Protocol, data is exchanged using sequences of frame to form WebSocket Messages. The user doesn't need to know how the WebSocket data framing works since the HTTP Client WebSocket module manages it internally. The HTTP Client WebSocket API simplifies the application development by using the concept of message which can be summarized by its Type, Payload Length and Contents.

WebSocket Messages can have 5 different types divided in 2 groups.

Control Message

• Close

• Ping

• Pong

Data Message

• Text

• Binary

Control Message#

Control messages are intended to be used for protocol-level signaling. Note that their payload length cannot exceed 125 bytes and they cannot be fragmented (only one frame per message).

Since control messages are protocol related, they are managed directly by the WebSocket Module which provides hook to notify the application.

Data Messages#

Data messages are intended to transport information. Their length can vary from 0 to 2^64 and can be fragmented. They can be divided in two type.

Note that the HTTP Client WebSocket module doesn't validate UTF-8 and must be done by the user application if necessary.

The reception of any Data Messages are done through hooks that are configured in the HTTPc_WEBSOCK_OBJ and that must be set before the connection upgrade request ( HTTPc_WebSockUpgrade() ).

Note that only one Data Message is processed at a time.

Data Message Reception Mode#

The hooks described in the previous section can be use in many different ways. However, those can be group in two different mode.

Normal mode#

Normal Mode uses all of the three Data Message Reception hooks. It allow the user to be notify every time a message payload chunk is available with the On Message RX Data hook. Thus, the application can parse a message during its reception without having to copying it all in a buffer.

This mode is useful when the memory footprints is critical and the message length can be long or undefined.

Normal Mode Example

Auto mode#

Auto Mode only use two hooks. During On Message Reception Initialization , it is possible to set a pointer to the buffer where the message payload must be set. If the application do so, the message will be automatically copied to the specified buffer. Once the message is completely received, On Message RX Complete hook will be called and data will be available is the buffer previously set.

This mode is useful for simpler application which the message length received from other endpoint are small and size-limited

Auto Mode Example

HTTP Client Auto Mode Example#

This example shows how to open a WebSocket with Data message Reception hooks configured in Auto Mode.

Listing - HTTP Client Auto Mode#

/*
*********************************************************************************************************
*                                            LOCAL DEFINES
*********************************************************************************************************
*/

#define  HTTPc_EXAMPLE_URI              "server.example.com"
#define  HTTPc_EXAMPLE_RESSOURCE        "/echo"
#define  HTTPc_EXAMPLE_CONN_BUF_LEN     1024
#define  HTTPc_EXAMPLE_MSG_MAX_LEN      512

/*
*********************************************************************************************************
*                                       LOCAL GLOBAL VARIABLES
*********************************************************************************************************
*/

static  HTTPc_CONN_OBJ         HTTPcExample_Conn;
static  CPU_CHAR               HTTPcExample_ConnBuf[HTTPc_EXAMPLE_CONN_BUF_LEN];
static  HTTPc_REQ_OBJ          HTTPcExample_Req;
static  HTTPc_RESP_OBJ         HTTPcExample_Resp;
static  HTTPc_WEBSOCK_OBJ      HTTPcExample_WebSock;
static  CPU_CHAR               HTTPcExample_RxBuf[HTTPc_EXAMPLE_MSG_MAX_LEN];

/*
*********************************************************************************************************
*                                      LOCAL FUNCTION PROTOTYPES
*********************************************************************************************************
*/

static void        HTTPcExample_ConnOnClose            (HTTPc_CONN_OBJ            *p_conn,
                                                        HTTPc_CONN_CLOSE_STATUS    close_status,
                                                        HTTPc_ERR                  err);

static void        HTTPcExample_WebSockOnMsgRxInit     (HTTPc_CONN_OBJ            *p_conn,
                                                        HTTPc_WEBSOCK_MSG_TYPE     msg_type,
                                                        CPU_INT32U                 msg_len,
                                                        void                     **p_data);

static void        HTTPcExample_WebSockOnMsgRxComplete (HTTPc_CONN_OBJ            *p_conn);

/*
*********************************************************************************************************
*                                               EXAMPLE
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcExample_OpenWebSocket (void)
{
    CPU_BOOLEAN  result;
    RTOS_ERR     err;
                                                       /* ----------- INIT NEW CONNECTION & REQUEST ---------- */
                                                       /* Always Clear the object.                             */
    HTTPc_ConnClr(&HTTPcExample_Conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    HTTPc_ReqClr(&HTTPcExample_Req, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    HTTPc_WebSockClr(&HTTPcExample_WebSock, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* ------------- SET ON CONNECTION CLOSE -------------- */
                                                       /* This callback is always required.                    */
    HTTPc_ConnSetParam(        &HTTPcExample_Conn,
                                HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                       (void *) HTTPcExample_ConnOnClose,
                               &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* ----------------- OPEN CONNECTION ------------------ */
    result = HTTPc_ConnOpen(&HTTPcExample_Conn,
                             HTTPcExample_ConnBuf,
                             HTTPc_EXAMPLE_CONN_BUF_LEN,
                             HTTPc_EXAMPLE_URI,
                             sizeof(HTTPc_EXAMPLE_URI),
                             HTTPc_FLAG_NONE,
                            &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* ----------- SET WEBSOCK HOOKS/CALLBACKS ------------ */
                                                       /* Set OnMsgRxInit hooks.                               */
    HTTPc_WebSockSetParam(        &HTTPcExample_WebSock,
                                   HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_INIT,
                          (void *) HTTPcExample_WebSockOnMsgRxInit,
                                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* Set OnMsgRxComplete hooks.                           */
    HTTPc_WebSockSetParam(        &HTTPcExample_WebSock,
                                   HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_COMPLETE,
                          (void *) HTTPcExample_WebSockOnMsgRxComplete,
                                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* ------- UPGRADE HTTP CONNECTION TO WEBSOCKET ------- */
    result = HTTPc_WebSockUpgrade(&HTTPcExample_Conn,
                                  &HTTPcExample_Req,
                                  &HTTPcExample_Resp,
                                  &HTTPcExample_WebSock,
                                   HTTPc_EXAMPLE_RESSOURCE,
                                   sizeof(HTTPc_EXAMPLE_RESSOURCE),
                                   HTTPc_FLAG_NONE,
                                  &err);
    if (result != DEF_OK) {
        return (DEF_FAIL);
    }
    return (DEF_OK);
}

/*
*********************************************************************************************************
*                                      CONNECTION ON CLOSE CALLBACK
*********************************************************************************************************
*/

static void  HTTPcExample_ConnOnClose (HTTPc_CONN_OBJ           *p_conn,
                                       HTTPc_CONN_CLOSE_STATUS   close_status,
                                       HTTPc_ERR                 err)
{
                                                       /* Called  when a connection close.                     */
}

/*
*********************************************************************************************************
*                                    WEBSOCK ON MSG RX INIT HOOK
*********************************************************************************************************
*/

static void  HTTPcExample_WebSockOnMsgRxInit (HTTPc_CONN_OBJ            *p_conn,
                                              HTTPc_WEBSOCK_MSG_TYPE     msg_type,
                                              CPU_INT32U                 msg_len,
                                              void                     **p_data)
{
                                                       /* Validate that we have enough space in the buffer...  */
                                                       /* ...to get all the message.                           */
    if (msg_len <= HTTPc_EXAMPLE_MSG_MAX_LEN) {
        *p_data = HTTPcExample_RxBuf;                  /* Set the pointer where the message data must be set.  */
    }
}

/*
*********************************************************************************************************
*                                   WEBSOCK ON MSG RX COMPLETE HOOK
*********************************************************************************************************
*/

static void  HTTPcExample_WebSockOnMsgRxComplete (HTTPc_CONN_OBJ *p_conn)
{
                                                       /* Once the message is completely received...           */
                                                       /* ...Do Something.                                     */
}

HTTP Client Normal Mode Example#

This example show how to open a WebSocket with Data message Reception hooks configured in Normal Mode.

Listing - HTTP Client Normal Mode#

#include <rtos/net/include/http_client.h>

/*
*********************************************************************************************************
*                                            LOCAL DEFINES
*********************************************************************************************************
*/

#define  HTTPc_EXAMPLE_URI              "server.example.com"
#define  HTTPc_EXAMPLE_RESSOURCE        "/echo"
#define  HTTPc_EXAMPLE_CONN_BUF_LEN     1024
#define  HTTPc_EXAMPLE_MSG_MAX_LEN      512

/*
*********************************************************************************************************
*                                       LOCAL GLOBAL VARIABLES
*********************************************************************************************************
*/

static  HTTPc_CONN_OBJ         HTTPcExample_Conn;
static  CPU_CHAR               HTTPcExample_ConnBuf[HTTPc_EXAMPLE_CONN_BUF_LEN];
static  HTTPc_REQ_OBJ          HTTPcExample_Req;
static  HTTPc_RESP_OBJ         HTTPcExample_Resp;
static  HTTPc_WEBSOCK_OBJ      HTTPcExample_WebSock;

static  CPU_CHAR               HTTPcExample_RxBuf[HTTPc_EXAMPLE_MSG_MAX_LEN];
static  CPU_INT32U             HTTPcExample_RxMsgLenToGet ;

/*
*********************************************************************************************************
*                                      LOCAL FUNCTION PROTOTYPES
*********************************************************************************************************
*/

static void        HTTPcExample_ConnOnClose            (HTTPc_CONN_OBJ            *p_conn,
                                                        HTTPc_CONN_CLOSE_STATUS    close_status,
                                                        HTTPc_ERR                  err);

static void        HTTPcExample_WebSockOnMsgRxInit     (HTTPc_CONN_OBJ            *p_conn,
                                                        HTTPc_WEBSOCK_MSG_TYPE     msg_type,
                                                        CPU_INT32U                 msg_len,
                                                        void                     **p_data);

static CPU_INT32U  HTTPcExample_WebSockOnMsgRxData     (HTTPc_CONN_OBJ            *p_conn,
                                                        HTTPc_WEBSOCK_MSG_TYPE     msg_type,
                                                        void                      *p_data,
                                                        CPU_INT16U                 data_len);

static void        HTTPcExample_WebSockOnMsgRxComplete (HTTPc_CONN_OBJ            *p_conn);

/*
*********************************************************************************************************
*                                               EXAMPLE
*********************************************************************************************************
*/

CPU_BOOLEAN  HTTPcExample_OpenWebSocket (void)
{
    CPU_BOOLEAN  result;
    RTOS_ERR     err;
                                                       /* ----------- INIT NEW CONNECTION & REQUEST ---------- */
                                                       /* Always Clear the object.                             */
    HTTPc_ConnClr(&HTTPcExample_Conn, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    HTTPc_ReqClr(&HTTPcExample_Req, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
    HTTPc_WebSockClr(&HTTPcExample_WebSock, &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* ------------- SET ON CONNECTION CLOSE -------------- */
                                                       /* This callback is always required.                    */
    HTTPc_ConnSetParam(        &HTTPcExample_Conn,
                                HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                       (void *) HTTPcExample_ConnOnClose,
                               &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* ----------------- OPEN CONNECTION ------------------ */
    result = HTTPc_ConnOpen(&HTTPcExample_Conn,
                             HTTPcExample_ConnBuf,
                             HTTPc_EXAMPLE_CONN_BUF_LEN,
                             HTTPc_EXAMPLE_URI,
                             sizeof(HTTPc_EXAMPLE_URI),
                             HTTPc_FLAG_NONE,
                            &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* ----------- SET WEBSOCK HOOKS/CALLBACKS ------------ */
                                                       /* Set OnMsgRxInit hooks.                               */
    HTTPc_WebSockSetParam(        &HTTPcExample_WebSock,
                                   HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_INIT,
                          (void *) HTTPcExample_WebSockOnMsgRxInit,
                                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* Set OnMsgRxData hooks.                               */
    HTTPc_WebSockSetParam(        &HTTPcExample_WebSock,
                                   HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_DATA,
                          (void *) HTTPcExample_WebSockOnMsgRxData,
                                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* Set OnMsgRxComplete hooks.                           */
    HTTPc_WebSockSetParam(        &HTTPcExample_WebSock,
                                   HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_COMPLETE,
                          (void *) HTTPcExample_WebSockOnMsgRxComplete,
                                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                       /* ------- UPGRADE HTTP CONNECTION TO WEBSOCKET ------- */
    result = HTTPc_WebSockUpgrade(&HTTPcExample_Conn,
                                  &HTTPcExample_Req,
                                  &HTTPcExample_Resp,
                                  &HTTPcExample_WebSock,
                                   HTTPc_EXAMPLE_RESSOURCE,
                                   sizeof(HTTPc_EXAMPLE_RESSOURCE),
                                   HTTPc_FLAG_NONE,
                                  &err);
    if (result != DEF_OK) {
        return (DEF_FAIL);
    }
    return (DEF_OK);
}

/*
*********************************************************************************************************
*                                      CONNECTION ON CLOSE CALLBACK
*********************************************************************************************************
*/

static void  HTTPcExample_ConnOnClose (HTTPc_CONN_OBJ           *p_conn,
                                       HTTPc_CONN_CLOSE_STATUS   close_status,
                                       HTTPc_ERR                 err)
{
                                                       /* Called  when a connection close.                     */
}

/*
*********************************************************************************************************
*                                    WEBSOCK ON MSG RX INIT HOOK
*********************************************************************************************************
*/

static void  HTTPcExample_WebSockOnMsgRxInit (HTTPc_CONN_OBJ            *p_conn,
                                              HTTPc_WEBSOCK_MSG_TYPE     msg_type,
                                              CPU_INT32U                 msg_len,
                                              void                     **p_data)
{
                                                       /* Validate that we have enough space in the buffer...  */
                                                       /* ...to get all the message.                           */
    if (msg_len <= HTTPc_EXAMPLE_MSG_MAX_LEN) {
        HTTPcExample_RxMsgLenToGet = msg_len;
    } else {
        HTTPcExample_RxMsgLenToGet = 0u;
    }
}

/*
*********************************************************************************************************
*                                    WEBSOCK ON MSG RX DATA HOOK
*********************************************************************************************************
*/

static CPU_INT32U  HTTPcExample_WebSockOnMsgRxData (HTTPc_CONN_OBJ            *p_conn,
                                                    HTTPc_WEBSOCK_MSG_TYPE     msg_type,
                                                    void                      *p_data,
                                                    CPU_INT16U                 data_len)
{
    CPU_INT16U  data_len_used;

    data_len_used = 0u;

    if (HTTPcExample_RxMsgLenToGet != 0u) {
        if (HTTPcExample_RxMsgLenToGet == data_len) {
                                                       /* In this example, wait to have all the message...     */
                                                       /* ...before copying it in the reception buffer.        */
            Mem_Copy(HTTPcExample_RxBuf, p_data, data_len);
            HTTPcExample_RxMsgLenToGet = 0u;
            data_len_used              = data_len;
        }
    }

    return (data_len_used);                            /* Return that number of bytes used.                    */
}

/*
*********************************************************************************************************
*                                   WEBSOCK ON MSG _RX COMLETE HOOK
*********************************************************************************************************
*/

static void  HTTPcExample_WebSockOnMsgRxComplete (HTTPc_CONN_OBJ  *p_conn)
{
                                                       /* Once the message is completely received...           */
                                                       /* ...Do Something.                                     */

}