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