Query String

Owned by Former user (Deleted)
Last updated: Jan 12, 2021 by WES Admin
8 min read

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 fields of the Query are separated by the "&" character. For more details, see section Query String in the HTTP Reference Guide.

µC/HTTP-client supports the addition of a Query String to an HTTP request:

    • 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.
    • Two methods are offered by the µC/HTTP-client stack to add Query String:
      1. Passing a Key-Value Pairs' Table to the µC/HTTP-client stack.
      2. 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 µC/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 µC/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;
    HTTPc_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 != 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 µC/HTTP-client core to add a field to the Query String. The hook function will be called until it return DEF_YES to notified the µC/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_QUERY_STR_HOOK to pass out hook function pointer to the µC/HTTP-client stack.

Listing - Adding a 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) 
{
    HTTPc_ERR       err;

                                                                /* ------------ SET STRING QUERY PARAMETER ------------ */
    HTTPc_ReqSetParam(p_req, HTTPc_PARAM_TYPE_REQ_QUERY_STR_HOOK, &HTTPc_ReqQueryStrHook, &err);
    if (err != HTTPc_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 received 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);
    }
}