Detailed Description

qDecoder Header file

Data Structures
struct	qentry_s

struct	qentobj_s

Macros
#define	_Q_PRGNAME "qdecoder"

#define	_Q_VERSION "12.0.8"

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_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. More...

qentry_t *	qcgireq_parse (qentry_t *request, Q_CGI_T method)
	Parse one or more request(COOKIE/POST/GET) queries. More...

char *	qcgireq_getquery (Q_CGI_T method)
	Get raw query string. More...

bool	qcgires_setcookie (qentry_t request, const char name, const char value, int expire, const char path, const char *domain, bool secure)
	Set cookie. More...

bool	qcgires_removecookie (qentry_t request, const char name, const char path, const char domain, bool secure)
	Remove cookie. More...

bool	qcgires_setcontenttype (qentry_t request, const char mimetype)
	Set responding content-type. More...

const char *	qcgires_getcontenttype (qentry_t *request)
	Get content-type. More...

bool	qcgires_redirect (qentry_t request, const char uri)
	Send redirection header. More...

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. More...

void	qcgires_error (qentry_t request, char format,...)
	Print out HTML error page and exit program. More...

qentry_t *	qcgisess_init (qentry_t request, const char dirpath)
	Initialize session. More...

bool	qcgisess_settimeout (qentry_t *session, time_t seconds)
	Set the auto-expiration seconds about user session. More...

const char *	qcgisess_getid (qentry_t *session)
	Get user session id. More...

time_t	qcgisess_getcreated (qentry_t *session)
	Get user session created time. More...

bool	qcgisess_save (qentry_t *session)
	Update session data. More...

bool	qcgisess_destroy (qentry_t *session)
	Destroy user session. More...

qentry_t *	qEntry (void)
	Create new qentry_t linked-list object. More...

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", "VALUE", 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();

qDecoder API Reference

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Function Documentation