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 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:
- The preprocessor macro
HTTPc_CFG_QUERY_STR_EN
must be set toDEF_ENABLED
.
- The preprocessor macro
- 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:
- Passing a Key-Value Pairs' Table to the µC/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 µ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.
#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.
#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); } }