=head1 NAME
libapreq - Apache Request C Library
=head1 SYNOPSIS
=head1 DESCRIPTION
=head1 ApacheRequest
=over 4
=item ApacheRequest *ApacheRequest_new (request_rec *r)
This function creates a new I<ApacheRequest> object using the given
I<request_rec> structure:
ApacheRequest *req = ApacheRequest_new(r);
=item int ApacheRequest_parse (ApacheRequest *req)
If the request method is B<GET>, query string arguments, if any will
be parsed and saved. If the request method is B<POST> and
I<Content-type> is I<application/x-www-form-urlencoded> the client
data will be read, parsed and saved. If the request method is B<POST>
and the I<Content-type> is I<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 I<upload> field.
The return value is B<OK> on success, otherwise an error code that
your handler should return.
=item const char *ApacheRequest_param (ApacheRequest *req, const char *key)
This function will return the value of the given parameter I<key>:
const char *value = ApacheRequest_param(req, "Key");
=item array_header *ApacheRequest_params (ApacheRequest *req, const char *key)
This function will return an I<array_header> of values for the given
parameter I<key>:
array_header *values = ApacheRequest_params(req, "Key");
=item 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");
=item req->parms
This field is an Apache I<table> that holds the parsed contents of
B<GET> and B<POST> requests.
Example:
table *data = req->parms;
ap_table_set(data, "Key", "Value");
=item req->post_max
Limit the size of POST data. I<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;
}
=item req->disable_uploads
Disable file uploads. I<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;
}
=item ApacheUpload *upload = ApacheRequest_upload (ApacheRequest *req)
If the request I<Content-type> was that of I<multipart/form-data>,
this will return an I<ApacheUpload> pointer containing the upload data,
B<NULL> otherwise. See I<ApacheUpload>.
ApacheUpload *upload = ApacheRequest_upload(req);
=back
=head1 ApacheUpload
The I<ApacheUpload> structure holds all information for all uploaded
files and is accessed via the I<upload> field of an I<ApacheRequest>
structure.
=over 4
=item upload->name
The name of the filefield parameter:
char *name = upload->name;
=item upload->filename
The name of the upload file:
char *filename = upload->filename;
=item upload->fp
A file pointer to the uploaded file:
FILE *fp = upload->fp;
=item upload->size
The size of the uploaded file in bytes:
long size = upload->size;
=item upload->info
The additional header information for the uploaded file:
table *info = upload->info;
const char *type = ap_table_get(info, "Content-type");
=item upload->next
Pointer to the next I<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;
...
}
=item ApacheUpload *ApacheUpload_find (ApacheUpload *upload, char *name)
Returns the I<ApacheUpload> pointer associated with I<name> or
B<NULL> if I<name> is not found in the list:
ApacheUpload *upload = ApacheUpload_find(upload, name);
=item const char *ApacheUpload_info (ApacheUpload *upload, char *key)
Shortcut for accessing the I<info> table:
const char *type = ApacheUpload_info(upload, "Content-Type");
=item const char *ApacheUpload_type (ApacheUpload *upload)
Shortcut for accessing the uploaded file I<Content-Type>:
const char *type = ApacheUpload_type(upload);
=back
=head1 ApacheCookie
=over 4
=item ApacheCookie *ApacheCookie_new (request_rec *r, ...)
This function creates a new I<ApacheCookie> object, using the given
I<request_request> and optional attribute arguments which are as follows:
=over 4
=item -name
Sets the I<name> field to the given value.
=item -value
Adds the value to I<values> field.
=item -expires
Sets the I<expires> field to the calculated date string.
See I<ApacheCookie_expires> for a listing of format options.
The default is B<NULL>.
=item -domain
Sets the I<domain> field to the given value.
The default is B<NULL>.
=item -path
Sets the I<path> field to the given value.
The default I<path> is derived from the requested I<uri>.
=item -secure
Sets the I<secure> field to true or false using a given string value
of I<On> or I<Off>.
The default is I<Off>.
=back
Example:
ApacheCookie *c = ApacheCookie_new(r,
"-name", "foo",
"-value", "bar",
"-expires", "+3M",
"-domain", ".cp.net",
"-path", "/mypath/database",
"-secure", "On",
NULL);
=item 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");
=item ApacheCookieJar *ApacheCookie_parse (request_rec *r, const char *data)
This function parses the given I<data> string or the incoming
I<Cookie> header, returning an I<ApacheCookieJar> of I<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);
...
}
}
=item int ApacheCookieItems (ApacheCookie *c)
The number of values for the given cookie.
=item char *ApacheCookieFetch (ApacheCookie *c, int n)
The I<n>th value for the given cookie.
=item void ApacheCookieAdd (ApacheCookie *c, char *value)
Add a new value to the cookie.
=item int ApacheCookieJarItems (ApacheCookieJar *cookies)
The number of cookies in the given cookie jar.
=item ApacheCookie *ApacheCookieJarFetch (ApacheCookieJar *cookies, int n)
The I<n>th cookie in the given cookie jar.
=item void ApacheCookieJarAdd (ApacheCookieJar *cookies, ApacheCookie *c)
Add a new cookie to the cookie jar.
=item 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 I<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
=item void ApacheCookie_bake (ApacheCookie *c)
Put cookie in the oven to bake.
(Add a I<Set-Cookie> header to the outgoing headers table.)
ApacheCookie_bake(c);
=item 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));
=back
=head1 CREDITS
This library is based on Perl modules by Lincoln Stein.
=head1 AUTHOR
Doug MacEachern