Detailed Description

qDecoder Header file

Data Structures
struct	_Q_ENTRY
struct	_Q_ENTOBJ_T
Defines
#define	_Q_PRGNAME "qDecoder"
#define	_Q_VERSION "11.0.0"
Typedefs
typedef struct _Q_ENTRY	Q_ENTRY
typedef struct _Q_ENTOBJ_T	Q_ENTOBJ_T
Enumerations
enum	Q_CGI_T { Q_CGI_ALL = 0, Q_CGI_COOKIE, Q_CGI_GET, Q_CGI_POST }
Functions
Q_ENTRY *	qCgiRequestSetOption (Q_ENTRY request, 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, Q_CGI_T method)
	Parse one or more request(COOKIE/GET/POST) queries.
char *	qCgiRequestGetQuery (Q_CGI_T method)
	Get raw query string.
bool	qCgiResponseSetCookie (Q_ENTRY request, const char name, const char value, int expire, const char path, const char *domain, bool secure)
	Set cookie.
bool	qCgiResponseRemoveCookie (Q_ENTRY request, const char name, const char path, const char domain, bool secure)
	Remove cookie.
bool	qCgiResponseSetContentType (Q_ENTRY request, const char mimetype)
	Set responding content-type.
const char *	qCgiResponseGetContentType (Q_ENTRY *request)
	Get content-type.
bool	qCgiResponseRedirect (Q_ENTRY request, const char uri)
	Send redirection header.
int	qCgiResponseDownload (Q_ENTRY request, const char filepath, const char *mimetype)
	Force to send(download) file to client in accordance with given mime type.
void	qCgiResponseError (Q_ENTRY request, char format,...)
	Print out HTML error page and exit program.
Q_ENTRY *	qSessionInit (Q_ENTRY request, const char dirpath)
	Initialize session.
bool	qSessionSetTimeout (Q_ENTRY *session, time_t seconds)
	Set the auto-expiration seconds about user session.
const char *	qSessionGetId (Q_ENTRY *session)
	Get user session id.
time_t	qSessionGetCreated (Q_ENTRY *session)
	Get user session created time.
bool	qSessionSave (Q_ENTRY *session)
	Update session data.
bool	qSessionDestroy (Q_ENTRY *session)
	Destroy user session.
Q_ENTRY *	qEntry (void)
	Create new Q_ENTRY linked-list object.

Function Documentation

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

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

Parameters:

	request	Q_ENTRY 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:: Q_ENTRY container pointer, otherwise returns NULL.

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

   Q_ENTRY *req = qCgiRequestSetOption(NULL, true, "/tmp", 86400);
   req = qCgiRequestParse(req, 0);
   req->free(req);

Q_ENTRY* qCgiRequestParse	(	Q_ENTRY *	request,
		Q_CGI_T	method
	)

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

Parameters:

	request	Q_ENTRY 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_GET and Q_CGI_POST. Q_CGI_ALL or 0 can be used for parsing all of those types.

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

   Q_ENTRY *req = qCgiRequestParse(NULL, 0);
   char *name = req->getStr(req, "name", false);
   if(name != NULL) printf("%s\n", name);
   req->free(req);

Note:: The queries are parsed with sequence of (1)COOKIE, (2)GET (3)POST.

char* qCgiRequestGetQuery ( Q_CGI_T method )

Get raw query string.

Parameters:

method

One of Q_CGI_COOKIE, Q_CGI_GET and Q_CGI_POST.

Returns:: malloced query string otherwise returns NULL;

   char *query = qCgiRequestGetQuery(Q_CGI_GET);
   if(query != NULL) {
     printf("%s\n", query);
     free(query);
   }

bool qCgiResponseSetCookie	(	Q_ENTRY *	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.
   qCgiResponseSetCookie(req, "NAME", "qDecoder", 86400, NULL, NULL, false);

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

   // As for the followings, cookies will be set up only when security
   // requirements are satisfied.
   qCgiResponseSetCookie(req, name, value, 0, NULL, NULL, true);

bool qCgiResponseRemoveCookie	(	Q_ENTRY *	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

   qCgiResponseSetCookie(req, "NAME", "VALUE", 0, NULL, NULL, NULL);
   qCgiResponseRemoveCookie(req, "NAME", NULL, NULL, NULL);

   qCgiResponseSetCookie(req, "NAME", "VALUE", 0, "/", "www.qdecoder.org", NULL);
   qCgiResponseRemoveCookie(req, "NAME", "/", "www.qdecoder.org", NULL);

bool qCgiResponseSetContentType	(	Q_ENTRY *	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

   qCgiResponseSetContentType(req, "text/html");

const char* qCgiResponseGetContentType ( Q_ENTRY * request )

Get content-type.

Parameters:

request

a pointer of request structure

Returns:: a pointer of mimetype string in case of success, otherwise returns NULL

   qCgiResponseSetContentType(req, "text/html");

bool qCgiResponseRedirect	(	Q_ENTRY *	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

   qCgiResponseRedirect(req, "http://www.qdecoder.org/");

int qCgiResponseDownload	(	Q_ENTRY *	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" mimetype.

Returns:: the number of bytes sent. otherwise(file not found) returns -1.

Note:: Do not call qCgiResponseGetContentType() 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 qCgiResponseError	(	Q_ENTRY *	request,
		char *	format,
			...
	)

Print out HTML error page and exit program.

Parameters:

	request	a pointer of request structure
	format	error message

Returns:: none

   qCgiResponseError(req, "Error: can't find userid.");

Q_ENTRY* qSessionInit	(	Q_ENTRY *	request,
		const char *	dirpath
	)

Initialize session.

Parameters:

	request	a pointer of request structure returned by qCgiRequestParse()
	dirpath	directory path where session data will be kept

Returns:: a pointer of malloced session data list (Q_ENTRY type)

Note:: The returned Q_ENTRY list must be de-allocated by calling Q_ENTRY->free(). And if you want to append or remove some user session data, use Q_ENTRY->*() functions then finally call qSessionSave() to store updated session data.

bool qSessionSetTimeout	(	Q_ENTRY *	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* qSessionGetId ( Q_ENTRY * 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 qSessionGetCreated ( Q_ENTRY * session )

Get user session created time.

Parameters:

session

a pointer of session structure

Returns:: user session created time in UTC time seconds

bool qSessionSave ( Q_ENTRY * session )

Update session data.

Parameters:

session

a pointer of session structure

Returns:: true if successful, otherwise returns false

bool qSessionDestroy ( Q_ENTRY * 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 Q_ENTRY->free(). This will remove all user session data permanantely and also free the session structure.

Q_ENTRY* qEntry ( void )

Create new Q_ENTRY linked-list object.

Returns:: a pointer of malloced Q_ENTRY structure in case of successful, otherwise returns NULL.

   Q_ENTRY *entry = qEntry();

qDecoder API Reference

qdecoder.h File Reference

Detailed Description

Data Structures

Defines

Typedefs

Enumerations

Functions

Function Documentation