qCgiRequest.c File Reference

Web Query & Cookie Handling API. More…

Defines

#define _Q_MULTIPART_CHUNK_SIZE (64 * 1024)

Functions

Q_ENTRY * qCgiRequestParseOption (bool filemode, const char *basepath, int clearold)

Set request parsing option for file uploading in case of multipart/form-data encoding.

Q_ENTRY * qCgiRequestParse (Q_ENTRY *request)

Parse web request(COOKIE/GET/POST) query into name and value fairs then store into the Q_ENTRY structure.

Q_ENTRY * qCgiRequestParseQueries (Q_ENTRY *request, const char *method)

Parse GET/POST queries into name and value fairs then store into the Q_ENTRY structure.

Q_ENTRY * qCgiRequestParseCookies (Q_ENTRY *request)

Parse cookies into name and value fairs then store into the Q_ENTRY structure.

char * qCgiRequestGetQueryString (const char *query_type)

Get unparsed query string.

Detailed Description

Web Query & Cookie Handling API.

qDecoder supports parsing

COOKIE
GET method
POST method (application/x-www-form-urlencoded: default FORM encoding)
POST method (multipart/form-data: especially used for file uploading)

Anyway you don’t care about this. You don’t need to know which method (COOKIE/GET/POST) is used for sending data.

   [HTML sample]
   <form action="your_program.cgi">
     <input type="text" name="color">
     <input type="submit">
   </form>
   [Your Source]
   Q_ENTRY *req = qCgiRequestParse(NULL);
   const char *color = qEntryGetStr(req, "color");
   printf("color = %sn", color);
   qEntryFree(req);

The storing sequence is (1)COOKIE (2)GET (3)POST. Thus if same query names (which are sent by different method) exist, COOKIE query will be returned.

If you would like to get POST queries only. See below sample codes.

   Q_ENTRY *req = qCgiRequestParseQueries(NULL, "POST");
   const char *color = qEntryGetStr(req, "color");
   printf("color = %sn", color);

If you would like to get POST and COOKIE queries only. See below sample codes.

   Q_ENTRY *req = NULL;
   req = qCgiRequestParseCookies(req);
   req = qCgiRequestParseQueries(req, "POST");
   const char *color = qEntryGetStr(req, "color");
   printf("color = %sn", color);
   qEntryFree(req);

In case of multipart/form-data encoding(used for file uploading), qDecoder supports 2 modes for handling file uploading. I just made a name for that.

default mode : Uploading file will be processed only in memory. (see examples/upload.c)
file mode : Uploading file will be stored into unique temporary file on the fly. There is sub mode named progress mode. This is same as file mode. But user can see the progress bar while uploading. When file mode is turned on and if you add some specific HTML codes in your uploading page, progressive window will be shown automatically. (see examples/uploadprogress.c)

You can switch to file mode by calling qCgiRequestParseOption().

   Q_ENTRY *req = qCgiRequestParseOption(true, "/tmp", 86400);
   req = qCgiRequestParse(req);
   (...your codes here...)
   qEntryFree(req);

Basically, when file is uploaded qDecoder store it’s meta information like below.

(VARIABLE_NAME) – In the default mode, this is binary data. In the file mode this value is same as “(VARIABLE_NAME).savepath”.
(VARIABLE_NAME).filename – File name itself, path information will be removed.
(VARIABLE_NAME).length – File size, the number of bytes.
(VARIABLE_NAME).contenttype – Mime type like ‘text/plain’.
(VARIABLE_NAME).savepath – Only appended only in file mode. The file path where the uploaded file is saved.

   [default mode example]
   binary = (...binary data...)
   binary.filename = hello.xls
   binary.length = 3292
   binary.contenttype = application/vnd.ms-excel
   [file mode example]
   binary = tmp/Q_7b91698bc6d6ac7eaac93e71ce729b7c/1-hello.xls
   binary.filename = hello.xls
   binary.length = 3292
   binary.contenttype = application/vnd.ms-excel
   binary.savepath = tmp/Q_7b91698bc6d6ac7eaac93e71ce729b7c/1-hello.xls

If you want to activate progress mode. Please follow below steps

1) copy “examples/qDecoder-upload/” folder under your Web Document Root.

2) modify your HTML codes like below.

   [HTML sample]
   <script language="JavaScript"
           src="/_(SOME_PATH)_/qDecoder-upload/qDecoder-upload.js"></script>
   <form method="post" action="your_program.cgi"
         enctype="multipart/form-data" onSubmit="return Q_UPLOAD(this);">
     <input type="hidden" name="Q_UPLOAD_ID" value="">
     Input text: <input type="text" name="text">
     <br>Select file: <input type="file" name="binary1">
     <br>Another file: <input type="file" name="binary2">
     <br><input type="submit">
   </form>
   [Code sample]
   int main(...) {
     // if you use "progress mode", this codes should be located at
     // the first line in main().
     Q_ENTRY *req = qCgiRequestParseOption(true, "/tmp", 86400);
     req = qCgiRequestParse(req);
     (...your codes here...)
     qEntryFree(req);
   }

Function Documentation

Q_ENTRY* qCgiRequestParseOption	(	bool	filemode,
		const char *	basepath,
		int	clearold
	)

Set request parsing option for file uploading in case of multipart/form-data encoding.

Parameters:

	request	if request is a NULL pointer, the function allocates, initializes, and returns a new object. otherwise use it.
	filemode	false(default) for parsing in memory, true for storing attached files to file
	basepath	the base path where the uploaded files are located. can be NULL if filemode is false.
	clearold	automatically remove temporary uploading file older than this secconds. to disable, set to 0.

Returns:: an initialized Q_ENTRY* handle, NULL if basepath can not be found.

Note:: This method should be called before qCgiRequestParse().

   Q_ENTRY *req = qCgiRequestParseOption(true, "/tmp", 86400);
   req = qCgiRequestParse(req);

Q_ENTRY* qCgiRequestParse ( Q_ENTRY * request )

Parse web request(COOKIE/GET/POST) query into name and value fairs then store into the Q_ENTRY structure.

Parameters:

request

if request is a NULL pointer, the function allocates, initializes, and returns a new object. but if you called qCgiParseRequestOption() to set options, pass it’s pointer.

Returns:: Q_ENTRY* handle if successful, NULL if there was insufficient memory to allocate a new object.

   Q_ENTRY *req = qCgiRequestParse(NULL);
   printf("%sn", qEntryGetStr(req, "name"));

Note:: The parsing sequence is (1)COOKIE, (2)GET (3)POST. Thus if same query names (which are sent by different method) exist, qGetValue() will return the value sent by GET method.

Q_ENTRY* qCgiRequestParseQueries	(	Q_ENTRY *	request,
		const char *	method
	)

Parse GET/POST queries into name and value fairs then store into the Q_ENTRY structure.

Parameters:

	request	if request is a NULL pointer, the function allocates, initializes, and returns a new object. otherwise reuse(append at) Q_ENTRY* handle.
	method	“GET” or “POST”. NULL can be used for parse both GET/POST queries.

Returns:: Q_ENTRY* handle if successful, NULL if there was insufficient memory to allocate a new object.

   Q_ENTRY *getpost = qCgiRequestParseQueries(NULL, NULL);
   printf("%sn", qEntryGetStr(getpost, "name"));
   // if you would like to parse only POST queries.
   Q_ENTRY *post = qCgiRequestParseQueries(NULL, "POST");
   printf("%sn", qEntryGetStr(post, "name"));

Q_ENTRY* qCgiRequestParseCookies ( Q_ENTRY * request )

Parse cookies into name and value fairs then store into the Q_ENTRY structure.

Parameters:

request

if request is a NULL pointer, the function allocates, initializes, and returns a new object. otherwise cookie value will be appended at Q_ENTRY* handle.

Returns:: Q_ENTRY* handle if successful, NULL if there was insufficient memory to allocate a new object.

   Q_ENTRY *cookies = qCgiRequestParseCookies(NULL);
   printf("%sn", qEntryGetStr(cookies, "name"));

char* qCgiRequestGetQueryString ( const char * query_type )

Get unparsed query string.

Parameters:

query_type

GET, POST, COOKIE (case-sensitive)

Returns:: query string which is memory allocated if successful, otherwise returns NULL;

   char *query = qCgiRequestGetQueryString("GET");
   if(query != NULL) {
     printf("%sn", query);
     free(query);
   }

[Home] [About] [Examples] [Changes] [Download] [SVN Repository] [Install] [Reference]


Defines
#define	_Q_MULTIPART_CHUNK_SIZE (64 * 1024)
Functions
Q_ENTRY *	qCgiRequestParseOption (bool filemode, const char *basepath, int clearold)
	Set request parsing option for file uploading in case of multipart/form-data encoding.
Q_ENTRY *	qCgiRequestParse (Q_ENTRY *request)
	Parse web request(COOKIE/GET/POST) query into name and value fairs then store into the Q_ENTRY structure.
Q_ENTRY *	qCgiRequestParseQueries (Q_ENTRY request, const char method)
	Parse GET/POST queries into name and value fairs then store into the Q_ENTRY structure.
Q_ENTRY *	qCgiRequestParseCookies (Q_ENTRY *request)
	Parse cookies into name and value fairs then store into the Q_ENTRY structure.
char *	qCgiRequestGetQueryString (const char *query_type)
	Get unparsed query string.