The qDecoder Project

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_ENTRYqGetFirstEntry (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

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.

Basically, when file is uploaded qDecoder store it’s meta information like below.
   [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


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]