qdecoder.h File Reference

# qDecoder API Reference

- Main Page
- Data Structures
- Files

- File List
- Globals

Data Structures | Macros | Typedefs | Enumerations | Functions
qdecoder.h File Reference

## Detailed Description

qDecoder Header file

## Data Structures
struct | qentry_s
struct | qentobj_s

## Macros
#define | _Q_PRGNAME "qdecoder"
#define | _Q_VERSION "12.0.4"

## 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.
qentry_t * | qcgireq_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_t * | qcgisess_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_t * | qEntry (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", "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();