/ 
libapreq-0.30_04
River stage two • 25 direct dependents • 25 total dependents
/ libapreq

NAME

libapreq - Apache Request C Library

SYNOPSIS

DESCRIPTION

ApacheRequest

ApacheRequest *ApacheRequest_new (request_rec *r)

This function creates a new ApacheRequest object using the given request_rec structure:

ApacheRequest *req = ApacheRequest_new(r);
int ApacheRequest_parse (ApacheRequest *req)

If the request method is GET, query string arguments, if any will be parsed and saved. If the request method is POST and Content-type is application/x-www-form-urlencoded the client data will be read, parsed and saved. If the request method is POST and the Content-type is multipart/form-data, the form parameters will be parsed and saved, the uploaded file will be written to a temporary file which can be accessed with the upload field. The return value is OK on success, otherwise an error code that your handler should return.

const char *ApacheRequest_param (ApacheRequest *req, const char *key)

This function will return the value of the given parameter key:

const char *value = ApacheRequest_param(req, "Key");
array_header *ApacheRequest_params (ApacheRequest *req, const char *key)

This function will return an array_header of values for the given parameter key:

array_header *values = ApacheRequest_params(req, "Key");
char *ApacheRequest_params_as_string (ApacheRequest *req, const char *key)

This function will format multi-value parmeters into a comma delimited string.

char *list = ApacheRequest_params_as_string(req, "Key");
req->parms

This field is an Apache table that holds the parsed contents of GET and POST requests. Example:

table *data = req->parms;
ap_table_set(data, "Key", "Value");
req->post_max

Limit the size of POST data. ApacheRequest_parse will return an error code if the size is exceeded:

int status;
ApacheRequest *req = ApacheRequest_new(r);

req->post_max = 1204;
if((status = ApacheRequest_parse(req)) != OK) {
    char *errmsg = ap_table_get(r->notes, "error-notes");
    ...
    return status;
}
req->disable_uploads

Disable file uploads. ApacheRequest_parse will return an error code if a file upload is attempted:

int status;
ApacheRequest *req = ApacheRequest_new(r);

req->disable_uploads = 1;
if((status = ApacheRequest_parse(req)) != OK) {
    char *errmsg = ap_table_get(r->notes, "error-notes");
    ...
    return status;
}
ApacheUpload *upload = ApacheRequest_upload (ApacheRequest *req)

If the request Content-type was that of multipart/form-data, this will return an ApacheUpload pointer containing the upload data, NULL otherwise. See ApacheUpload.

ApacheUpload *upload = ApacheRequest_upload(req);

ApacheUpload

The ApacheUpload structure holds all information for all uploaded files and is accessed via the upload field of an ApacheRequest structure.

upload->name

The name of the filefield parameter:

char *name = upload->name;
upload->filename

The name of the upload file:

char *filename = upload->filename;
upload->fp

A file pointer to the uploaded file:

FILE *fp = upload->fp;
upload->size

The size of the uploaded file in bytes:

long size = upload->size;
upload->info

The additional header information for the uploaded file:

table *info = upload->info;
const char *type = ap_table_get(info, "Content-type");
upload->next

Pointer to the next ApacheUpload structure if multiple files were uploaded:

    ApacheUpload *uptr;
    for (uptr = ApacheRequest_upload(req); uptr; uptr = uptr->next) {
	char *name = uptr->name;
	FILE *fp   = uptr->fp;
	...
    }
ApacheUpload *ApacheUpload_find (ApacheUpload *upload, char *name)

Returns the ApacheUpload pointer associated with name or NULL if name is not found in the list:

ApacheUpload *upload = ApacheUpload_find(upload, name);
const char *ApacheUpload_info (ApacheUpload *upload, char *key)

Shortcut for accessing the info table:

const char *type = ApacheUpload_info(upload, "Content-Type");
const char *ApacheUpload_type (ApacheUpload *upload)

Shortcut for accessing the uploaded file Content-Type:

const char *type = ApacheUpload_type(upload);

ApacheCookie

ApacheCookie *ApacheCookie_new (request_rec *r, ...)

This function creates a new ApacheCookie object, using the given request_request and optional attribute arguments which are as follows:

-name

Sets the name field to the given value.

-value

Adds the value to values field.

-expires

Sets the expires field to the calculated date string. See ApacheCookie_expires for a listing of format options. The default is NULL.

-domain

Sets the domain field to the given value. The default is NULL.

-path

Sets the path field to the given value. The default path is derived from the requested uri.

-secure

Sets the secure field to true or false using a given string value of On or Off. The default is Off.

Example:

 ApacheCookie *c = ApacheCookie_new(r,
			"-name",    "foo", 
                        "-value",   "bar", 
                        "-expires", "+3M", 
                        "-domain",  ".cp.net", 
                        "-path",    "/mypath/database", 
                        "-secure",  "On", 
                        NULL);
char *ApacheCookie_attr (ApacheCookie *c, char *key, char *val)

This function is used to get or set a cookie attribute pair, accepting the same attributes as the list above. Example:

char *name = ApacheCookie_attr(c, "-name"); /* same as c->name */
(void *)ApacheCookie_attr(c, "-expires", "+3h");
ApacheCookieJar *ApacheCookie_parse (request_rec *r, const char *data)

This function parses the given data string or the incoming Cookie header, returning an ApacheCookieJar of ApacheCookie objects.

Example:

int i;
ApacheCookieJar *cookies = ApacheCookie_parse(r, NULL);
for (i = 0; i < ApacheCookieJarItems(cookies); i++) { 
    ApacheCookie *c = ApacheCookieJarFetch(cookies, i);
    int j;
    for (j = 0; j < ApacheCookieItems(c); j++) {
        char *name = c->name;
        char *value = ApacheCookieFetch(c, j);
        ...
    }
}
int ApacheCookieItems (ApacheCookie *c)

The number of values for the given cookie.

char *ApacheCookieFetch (ApacheCookie *c, int n)

The nth value for the given cookie.

void ApacheCookieAdd (ApacheCookie *c, char *value)

Add a new value to the cookie.

int ApacheCookieJarItems (ApacheCookieJar *cookies)

The number of cookies in the given cookie jar.

ApacheCookie *ApacheCookieJarFetch (ApacheCookieJar *cookies, int n)

The nth cookie in the given cookie jar.

void ApacheCookieJarAdd (ApacheCookieJar *cookies, ApacheCookie *c)

Add a new cookie to the cookie jar.

char *ApacheCookie_expires (ApacheCookie *c, char *time_str)

This function gets or sets the expiration date for cookie. The following forms are all valid for the time_str parmeter:

+30s                              30 seconds from now 
+10m                              ten minutes from now 
+1h                               one hour from now 
-1d                               yesterday (i.e. "ASAP!") 
now                               immediately 
+3M                               in three months 
+10y                              in ten years time 
Thursday, 25-Apr-1999 00:40:33 GMT  at the indicated time & date
void ApacheCookie_bake (ApacheCookie *c)

Put cookie in the oven to bake. (Add a Set-Cookie header to the outgoing headers table.)

ApacheCookie_bake(c);
char *ApacheCookie_as_string (ApacheCookie *c)

Returns a string version of the cookie:

ap_table_add(r->headers_out, "Set-Cookie", ApacheCookie_as_string(c));

CREDITS

This library is based on Perl modules by Lincoln Stein.

AUTHOR

Doug MacEachern