---

qDecoder.c File Reference

Web Query & Cookie Handling API. More…

Functions
bool	qDecoderInit (bool filemode, char *upload_base, int clear_olderthan)
	Initialize how qDecoder() handle file uploading(multipart/form-data).
int	qDecoder (void)
	Interprets encoded web query & cookie strings and stores them in the internal linked-list.
char *	qGetValue (char *format,…)
	Finds out the value.
int	qGetInt (char *format,…)
	Finds out the value then converts to integer.
char *	qGetValueDefault (char *defstr, char *format,…)
	Finds out the value, if there is no such variable returns default value.
char *	qGetValueNotEmpty (char *errmsg, char *format,…)
	Exit program using the qError() function if there is no such variable.
char *	qGetValueReplace (char *mode, char *name, char *tokstr, char *word)
	Find out the value with replacing tokens.
char *	qGetValueFirst (char *format,…)
	Find out the first value.
char *	qGetValueNext (void)
	Find out the next value.
char *	qAdd (char *name, char *format,…)
	Add given variable to internal linked list.
void	qRemove (char *format,…)
	Remove variable from internal linked list.
char	qGetType (char *format,…)
	Get the type of variable.
Q_ENTRY *	qGetFirstEntry (void)
	Get the first entry pointer of internal linked list.
int	qPrint (FILE *out)
	Print out internal data for debugging.
bool	qCookieSet (char *name, char *value, int exp_days, char *path, char *domain, char *secure)
	Set cookie.
bool	qCookieRemove (char *name, char *path, char *domain, char *secure)
	Remove cookie.
char *	qCookieGetValue (char *format,…)
	Find out the cookie value.
int	qCookieGetInt (char *format,…)
	Finds out the cookie value then converts to integer.
void	qFree (void)
	Deallocates the allocated memory by qDecoder().
void	qReset (void)
	Deallocates every allocated memory(including session data) and re-initialize.

---

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. All you need to know is you can get the value by calling qGetValue(“value name”). (See examples/fetch.c)

   [HTML sample]
   <form action="your_program.cgi">
     <input type="text" name="query">
     <input type="submit">
   </form>
   [Your Source]
   char *query;
   query = qGetValue("query");
   qPrint(stdout); // if you want to see debugging information

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 of COOKIE.

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. (see examples/uploadfile.c) 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. (see examples/uploadprogress.c)

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’, ‘application/vnd.ms-excel’.
• (VARIABLE_NAME).savepath – Only appended only in file mode. The file path where 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

The return value of qDecoder() only counts variables. So this will be regarded as 1.

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

• 1) copy “examples/qDecoder-upload/” folder under your Web Document Root.
• 2) see this sample codes.

     [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(...) {
       // change mode to "file mode".
       qDecoderInit(true, "/tmp", 86400); // must be called at
                                          // the first line of main();
       qDecoder();                        // must be called right next
                                          // of qDecoderInit().
       (...your codes here...)
     }
  

---

Function Documentation

bool qDecoderInit	(	bool	filemode,
		char *	upload_base,
		int	clear_olderthan
	)

Initialize how qDecoder() handle file uploading(multipart/form-data).

Parameters:

	filemode	to turn on file mode set to true. false means default mode.
	upload_base	the base path where the temporary created files are located. if filemode is false, just set to NULL.
	clear_olderthan	automatically remove temporary uploading file older than this secconds. to disable, set to 0.

Returns:

in case of success, returns true. otherwise(upload_base not found) false.

Note:

You do not need to call for setting up memory mode, because it’s default operation. But if you want to turn file mode on, you must call this at the first line of main().

   int main(...) {
     // change mode to "file mode".
     qDecoderInit(true, "/tmp", 86400); // must be called at
                                        // the first line of main();
     qDecoder();                        // must be called right next
                                        // of qDecoderInit().
     (...your codes here...)
   }

int qDecoder

(

void

)

Interprets encoded web query & cookie strings and stores them in the internal linked-list.

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 of COOKIE.

This function, qDecoder(), is called automatically when you use qGetValue() or related functions, so you do not need to call directly.

Returns:

the number of received arguments(not stored). otherwise returns -1.

char* qGetValue	(	char *	format,
			…
	)

Finds out the value.

Parameters:

format

variable name

Returns:

the pointer of the variable value. NULL if there is no such variable name.

Note:

   char *test;
   test = qGetValue("name");
   char *test;
   int i = 1;
   test = qGetValue("arg%d", i);

int qGetInt	(	char *	format,
			…
	)

Finds out the value then converts to integer.

Parameters:

format

variable name

Returns:

converted value. otherwise(convertion error, not found) returns 0.

Note:

   int num;
   num = qGetInt("num");

char* qGetValueDefault	(	char *	defstr,
		char *	format,
			…
	)

Finds out the value, if there is no such variable returns default value.

Parameters:

	defstr	default value
	format	variable name

Returns:

the pointer of the variable value.

Note:

   char *test;
   test = qGetValueDefault("this is default value", "name");

char* qGetValueNotEmpty	(	char *	errmsg,
		char *	format,
			…
	)

Exit program using the qError() function if there is no such variable.

Parameters:

	errmsg	error message
	format	variable name

Returns:

the pointer of the variable value. if there is no such variable, display errmsg then quit program.

Note:

   char *test;
   test = qGetValueNotEmpty("DO NOT USE MANUALLY", "name");

char* qGetValueReplace	(	char *	mode,
		char *	name,
		char *	tokstr,
		char *	word
	)

Find out the value with replacing tokens.

Basically, qGetValueReplace() is the wrapping function of qStrReplace(). The difference is that the source string is the query value (the value of the linked-list for names), and the conversion can be directly done to the linked-list itself.

Accordingly, the usage of arguments of qGetValueReplace() is basically the same as that of qStrReplace(). The ‘mode’ argument is a character string made up of two separate characters like “sr”.

Parameters:

	mode	same as qStrReplace(). “tn” : [t]oken transposition & stores results in a [n]ew space and returns “tr” : [t]oken transposition & [r]eplaces the linked-list itself “sn” : [s]tring transposition & stores results in a [n]ew space and returns “sr” : [s]tring transposition & [r]eplaces the linked-list itself
	name	variable name of the linked-list
	tokstr	token or string which you wishes to be replaced.
	word	the string to replace

Returns:

the pointer of the replaced variable value. if you set the mode to “tn” or “sn”, you must free yourself.

Note:

   char *test;
   // replace space, quotation, double quotation to '_'
   test = qGetValueReplace("tr", "name", " '"", "_");
   // replace "bad" to "good"
   test = qGetValueReplace("sr", "name", "bad", "good");

See also:

qStrReplace()

char* qGetValueFirst	(	char *	format,
			…
	)

Find out the first value.

If the query has multi-same-variables(same variable names), you can use this.

Parameters:

format

variable name

Returns:

the pointer of the first variable value. otherwise(not found) returns NULL.

Note:

   char *list;
   for(list = qGetValueFirst("checklist"); list; list = qGetValueNext()) {
     printf("checklist = %s<br>n", list);
   }

char* qGetValueNext

(

void

)

Find out the next value.

Returns:

the pointer of the next variable value. otherwise(no more value) returns NULL.

char* qAdd	(	char *	name,
		char *	format,
			…
	)

Add given variable to internal linked list.

If same variable name exists, it’ll be replaced.

Parameters:

	name	variable name to add
	format	value string

Returns:

the pointer of the value string. otherwise(can’t add) returns NULL.

Note:

   qAdd("NAME", "Seung-young Kim");

void qRemove	(	char *	format,
			…
	)

Remove variable from internal linked list.

Multi-same-variables will be removed too.

Parameters:

format

variable name to remove

Note:

   qRemove("NAME");

char qGetType	(	char *	format,
			…
	)

Get the type of variable.

Parameters:

format

variable name to remove

Returns:

type character

• COOKIE : ‘C’
• GET method : ‘G’
• POST method : ‘P’
• New(added by qAdd()) : ‘N’
• Not found : ‘-‘

Note:

   char t = qGetType("NAME");

Q_ENTRY* qGetFirstEntry

(

void

)

Get the first entry pointer of internal linked list.

Returns:

first entry pointer. if no data stored, returns NULL.

Note:

   Q_ENTRY *entry = qGetFirstEntry();

int qPrint

(

FILE *

out

)

Print out internal data for debugging.

Parameters:

out

output file stream

Returns:

the number of variables

Note:

   qPrint(stdout);

bool qCookieSet	(	char *	name,
		char *	value,
		int	exp_days,
		char *	path,
		char *	domain,
		char *	secure
	)

Set cookie.

This should be used before qContentType() is called.

When cookie is set up through qCookieSet(), the point of time when values are handed over through qGetValue() is when the next program is called. In some implementations, however, cookies need to be set up for the simplicity of logic while, at the same time, this needs to be applied to other routines.

In this case, qAdd() can prevent the alteration of logic and the waste of additional codes by adding values to the cookie linked-list. But with regard to qCookieSet(), setting up cookies at clients (browsers) does not succeed always. Thus, users should be careful when using qAdd().

Returns:

in case of success, returns true. otherwise(qContentType() is called before) false

Note:

   char *name = "NAME", *value = "Kim";
   // Apply the NAME=Kim information in the current domain and directory
   // for 30 days.
   qCookieSet(name, value, 30, NULL, NULL, NULL);
   // Apply the NAME=Kim information to the "/" directory of
   // "ANYTHING.qdecoder.org"
   // until the browser is shut down.
   qCookieSet(name, value, 0, "/", ".qdecoder.org", NULL);
   // As for the followings, cookies will be set up only when security
   // requirements are satisfied.
   qCookieSet(name, value, 0, NULL, NULL, "SECURE");

bool qCookieRemove	(	char *	name,
		char *	path,
		char *	domain,
		char *	secure
	)

Remove cookie.

This should be used before qContentType() is called and the arguments(path, domain, secure) must be exactly same as the arguments of qCookieSet().

When cookies are removed through qCookieRemove(), the point of time when values in linked-list removed is when the next program is called. In some implementations, however, cookies need to be removed for the simplicity of logic while, at the same time, this needs to be applied to other routines.

In this case, qRemove() can prevent the alteration of logic and the waste of additional codes by removing values to the linked-list. But with regard to qCookieRemove(), removing cookies at clients (browsers) does not succeed always.

Thus, users should be careful when using qRemove().

Returns:

in case of success, returns true. otherwise(qContentType() is called before) false

Note:

   qCookieSet("NAME", "VALUE", 0, NULL, NULL, NULL);
   qCookieRemove("NAME", NULL, NULL, NULL);
   qCookieSet("NAME", "VALUE", 0, "/", "www.qdecoder.org", NULL);
   qCookieRemove("NAME", "/", "www.qdecoder.org", NULL);

char* qCookieGetValue	(	char *	format,
			…
	)

Find out the cookie value.

This only find the cookie value. Of course, you can use qGetValue() instead but qGetValue() finds out variable from query(GET/POST) too. So it’s different. For some security reason, sometimes you need to get only cookie value, in case of that, use this.

Parameters:

format

variable name

Returns:

the pointer of the cookie value. otherwise(not found) returns NULL.

Note:

   char *cookie;
   cookie = qCookieGetValue("NAME");
   if(cookie == NULL) printf("cookie not found.n");

int qCookieGetInt	(	char *	format,
			…
	)

Finds out the cookie value then converts to integer.

Parameters:

format

variable name

Returns:

integer converted value. otherwise(convertion error, not found) returns 0.

Note:

   int cookieint;
   cookieint = qCookieGetInt("NAME");

void qFree

(

void

)

Deallocates the allocated memory by qDecoder().

Note:

   qFree();

void qReset

(

void

)

Deallocates every allocated memory(including session data) and re-initialize.

When you wish to make a daemon-type repetitive program or to initialize qDecoder new, you can use this function. qReset() deallocates all the allocated memory including the linked-list and restores internal static variables to the initial condition.

Note:

   qReset();

---

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