qDecoder API Reference

Data Structures | Defines | Typedefs | Enumerations | Functions

qdecoder.h File Reference


Detailed Description

qDecoder Header file

Data Structures

struct  qentry_s
struct  qentobj_s

Defines

#define _Q_PRGNAME   "qdecoder"
#define _Q_VERSION   "12.0.2"

Typedefs

typedef struct qentry_s qentry_t
typedef struct qentobj_s qentobj_t

Enumerations

enum  Q_CGI_T { Q_CGI_ALL = 0, Q_CGI_COOKIE = 0x01, Q_CGI_POST = 0x02, Q_CGI_GET = 0x04 }

Functions

qentry_tqcgireq_setoption (qentry_t *request, bool filemode, const char *basepath, int clearold)
 Set request parsing option for file uploading in case of multipart/form-data encoding.
qentry_tqcgireq_parse (qentry_t *request, Q_CGI_T method)
 Parse one or more request(COOKIE/POST/GET) queries.
char * qcgireq_getquery (Q_CGI_T method)
 Get raw query string.
bool qcgires_setcookie (qentry_t *request, const char *name, const char *value, int expire, const char *path, const char *domain, bool secure)
 Set cookie.
bool qcgires_removecookie (qentry_t *request, const char *name, const char *path, const char *domain, bool secure)
 Remove cookie.
bool qcgires_setcontenttype (qentry_t *request, const char *mimetype)
 Set responding content-type.
const char * qcgires_getcontenttype (qentry_t *request)
 Get content-type.
bool qcgires_redirect (qentry_t *request, const char *uri)
 Send redirection header.
int qcgires_download (qentry_t *request, const char *filepath, const char *mimetype)
 Force to send(download) file to client in accordance with given mime type.
void qcgires_error (qentry_t *request, char *format,...)
 Print out HTML error page and exit program.
qentry_tqcgisess_init (qentry_t *request, const char *dirpath)
 Initialize session.
bool qcgisess_settimeout (qentry_t *session, time_t seconds)
 Set the auto-expiration seconds about user session.
const char * qcgisess_getid (qentry_t *session)
 Get user session id.
time_t qcgisess_getcreated (qentry_t *session)
 Get user session created time.
bool qcgisess_save (qentry_t *session)
 Update session data.
bool qcgisess_destroy (qentry_t *session)
 Destroy user session.
qentry_tqEntry (void)
 Create new qentry_t linked-list object.

Function Documentation

qentry_t* qcgireq_setoption ( qentry_t request,
bool  filemode,
const char *  basepath,
int  clearold 
)

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

Parameters:
request qentry_t container pointer that options will be set. NULL can be used to create a new container.
filemode false for parsing in memory, true for storing attached files into file-system directly.
basepath the base path where the uploaded files are located. Set to NULL if filemode is false.
clearold saved files older than this seconds will be removed automatically. Set to 0 to disable.
Returns:
qentry_t container pointer, otherwise returns NULL.
Note:
This method should be called before calling qcgireq_parse().
   qentry_t *req = qcgireq_setoption(NULL, true, "/tmp", 86400);
   req = qcgireq_parse(req, 0);
   req->free(req);
qentry_t* qcgireq_parse ( qentry_t request,
Q_CGI_T  method 
)

Parse one or more request(COOKIE/POST/GET) queries.

Parameters:
request qentry_t container pointer that parsed key/value pairs will be stored. NULL can be used to create a new container.
method Target mask consists of one or more of Q_CGI_COOKIE, Q_CGI_POST and Q_CGI_GET. Q_CGI_ALL or 0 can be used for parsing all of those types.
Returns:
qentry_t* handle if successful, NULL if there was insufficient memory to allocate a new object.
   qentry_t *req = qcgireq_parse(NULL, 0);
   qentry_t *req = qcgireq_parse(req, Q_CGI_COOKIE | Q_CGI_POST);
Note:
When multiple methods are specified, it'll be parsed in the order of (1)COOKIE, (2)POST (3)GET unless you call it separately multiple times.
char* qcgireq_getquery ( Q_CGI_T  method  ) 

Get raw query string.

Parameters:
method One of Q_CGI_COOKIE, Q_CGI_POST or Q_CGI_GET.
Returns:
malloced query string otherwise returns NULL;
   char *query = qcgireq_getquery(Q_CGI_GET);
   if(query != NULL) {
     printf("%s\n", query);
     free(query);
   }
bool qcgires_setcookie ( qentry_t request,
const char *  name,
const char *  value,
int  expire,
const char *  path,
const char *  domain,
bool  secure 
)

Set cookie.

Parameters:
request a pointer of request structure
name cookie name
value cookie value
expire expire related time in seconds (0 means end of session)
path cookie path (NULL can current path)
domain cookie domain (NULL means current domain)
secure secure flag
Returns:
true in case of success, otherwise returns false
   // Apply cookie in the current domain and directory for 1 day.
   qcgires_setcookie(req, "NAME", "qDecoder", 86400, NULL, NULL, false);

   // Apply cookie to the "/" directory of "*.qdecoder.org" until the
   // browser is closed.
   qcgires_setcookie(req, name, value, 0, "/", ".qdecoder.org", false);

   // As for the followings, cookies will be set up only when security
   // requirements are satisfied.
   qcgires_setcookie(req, name, value, 0, NULL, NULL, true);
bool qcgires_removecookie ( qentry_t request,
const char *  name,
const char *  path,
const char *  domain,
bool  secure 
)

Remove cookie.

Parameters:
request a pointer of request structure
name cookie name
path cookie path
domain cookie domain
secure secure flag
Returns:
true in case of success, otherwise returns false
   qcgires_setcookie(req, "NAME", "VALUE", 0, NULL, NULL, NULL);
   qcgires_removecookie(req, "NAME", NULL, NULL, NULL);

   qcgires_setcookie(req, "NAME", "VALUE", 0, "/", "www.qdecoder.org", NULL);
   qcgires_removecookie(req, "NAME", "/", "www.qdecoder.org", NULL);
bool qcgires_setcontenttype ( qentry_t request,
const char *  mimetype 
)

Set responding content-type.

Parameters:
request a pointer of request structure
mimetype mimetype
Returns:
true in case of success, otherwise returns false
   qcgires_setcontenttype(req, "text/html");
const char* qcgires_getcontenttype ( qentry_t request  ) 

Get content-type.

Parameters:
request a pointer of request structure
Returns:
a pointer of mimetype string in case of success, otherwise returns NULL
   qcgires_setcontenttype(req, "text/html");
bool qcgires_redirect ( qentry_t request,
const char *  uri 
)

Send redirection header.

Parameters:
request a pointer of request structure
uri new URI
Returns:
true in case of success, otherwise returns false
   qcgires_redirect(req, "http://www.qdecoder.org/");
int qcgires_download ( qentry_t request,
const char *  filepath,
const char *  mimetype 
)

Force to send(download) file to client in accordance with given mime type.

Parameters:
request a pointer of request structure
filepath file to send
mimetype mimetype. NULL can be used for "application/octet-stream".
Returns:
the number of bytes sent. otherwise(file not found) returns -1.
Note:
Do not call qcgires_getcontenttype() before. The results of this function are the same as those acquired when the corresponding files are directly linked to the Web. But this is especially useful in preprocessing files to be downloaded only with user certification and in enabling downloading those files, which cannot be opend on the Web, only through specific programs.
void qcgires_error ( qentry_t request,
char *  format,
  ... 
)

Print out HTML error page and exit program.

Parameters:
request a pointer of request structure
format error message
Returns:
none
   qcgires_error(req, "Error: can't find userid.");
qentry_t* qcgisess_init ( qentry_t request,
const char *  dirpath 
)

Initialize session.

Parameters:
request a pointer of request structure returned by qcgireq_parse()
dirpath directory path where session data will be kept
Returns:
a pointer of malloced session data list (qentry_t type)
Note:
The returned qentry_t list must be de-allocated by calling qentry_t->free(). And if you want to append or remove some user session data, use qentry_t->*() functions then finally call qcgisess_save() to store updated session data.
bool qcgisess_settimeout ( qentry_t session,
time_t  seconds 
)

Set the auto-expiration seconds about user session.

Parameters:
session a pointer of session structure
seconds expiration seconds
Returns:
true if successful, otherwise returns false
Note:
Default timeout is defined as SESSION_DEFAULT_TIMEOUT_INTERVAL. 1800 seconds
const char* qcgisess_getid ( qentry_t session  ) 

Get user session id.

Parameters:
session a pointer of session structure
Returns:
a pointer of session identifier
Note:
Do not free manually
time_t qcgisess_getcreated ( qentry_t session  ) 

Get user session created time.

Parameters:
session a pointer of session structure
Returns:
user session created time in UTC time seconds
bool qcgisess_save ( qentry_t session  ) 

Update session data.

Parameters:
session a pointer of session structure
Returns:
true if successful, otherwise returns false
bool qcgisess_destroy ( qentry_t session  ) 

Destroy user session.

Parameters:
session a pointer of session structure
Returns:
true if successful, otherwise returns false
Note:
If you only want to de-allocate session structure, just call qentry_t->free(). This will remove all user session data permanantely and also free the session structure.
qentry_t* qEntry ( void   ) 

Create new qentry_t linked-list object.

Returns:
a pointer of malloced qentry_t structure in case of successful, otherwise returns NULL.
   qentry_t *entry = qEntry();