Form Submission
- Former user (Deleted)
- WES Admin
- Former user (Deleted)
Owned by Former user (Deleted)
µC/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, please refer to section Form in the HTTP Reference Guide.
Form Field Types
µC/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 µC/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 a Application type form.
- HTTPc_FormMultipartFmt() to format the table into a Mutlipart 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 µC/HTTP-client stack so that the formatting can be done internally by the µC/HTTP-client core. This option allows to have a different form field types into the table. The µC/HTTP-client stack will take care to call 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 µC/HTTP-client stack 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;
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 != HTTPc_ERR_NONE) {
return (DEF_FAIL);
}
/* ---------------- INIT NEW CONNECTION --------------- */
HTTPc_ConnClr(p_conn, &err);
if (err != HTTPc_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 != HTTPc_ERR_NONE) {
return (DEF_FAIL);
}
#endif
/* ----------------- INIT NEW REQUEST ----------------- */
HTTPc_ReqClr(p_req, &err);
if (err != HTTPc_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 != HTTPc_ERR_NONE) {
return (DEF_FAIL);
}
HTTPc_ReqSetParam(p_req,
HTTPc_PARAM_TYPE_REQ_BODY_CONTENT_LEN,
&content_len,
&err);
if (err != HTTPc_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 != HTTPc_ERR_NONE) {
return (DEF_FAIL);
}
#endif
/* ----------------- OPEN CONNECTION ------------------ */
str_len = Str_Len(HTTP_SERVER_HOSTNAME);
flags = HTTPc_FLAG_NONE;
result = HTTPc_ConnOpen(p_conn,
p_buf,
HTTPc_EX_CFG_BUF_SIZE,
HTTP_SERVER_HOSTNAME,
str_len,
flags,
&err);
if (err != HTTPc_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");
flags = HTTPc_FLAG_NONE;
result = HTTPc_ReqSend(p_conn,
p_req,
p_resp,
HTTP_METHOD_POST,
"/form",
str_len,
flags,
&err);
if (err != HTTPc_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;
HTTPc_ERR httpc_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, &httpc_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, &httpc_err);
*p_form_tbl = &HTTPcEx_ReqFormTbl[0];
return (2);
}