=head1 NAME
libapreq - Apache Request C Library
=head1 SYNOPSIS
=head1 DESCRIPTION
=head1 ApacheRequest
=over 4
=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
=item ApacheRequest_set_post_max(req, 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 req->temp_dir
=item ApacheRequest_set_temp_dir(req, dir)
Sets the directory where upload files are spooled.
char dir[] = "/usr/tmp";
req->temp_dir = dir;
=item req->hook_data
=item req->upload_hook
Redirects upload data to be processed by the hook.
req->hook_data = (void *) data;
req->upload_hook = (int(*)(void*,char*,int,ApacheUpload*)) func;
In this case
func(req->hook_data,buffer,bufsize,upload);
will be called repeatedly during the file upload instead of writing the
data to a temp file.
=back
=head2 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);
=head2 int ApacheRequest_parse (ApacheRequest *req)
If the request method is B<GET> or B<POST>, the query string
arguments and the client form data will be read, parsed and saved.
In addition, if the request method is B<POST> and the I<Content-type> is
I<multipart/form-data>, the uploaded files will be written to
temporary files which can be accessed with the I<upload> field names.
The return value is B<OK> on success, otherwise an error code that
your handler should return.
=head2 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");
=head2 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");
=head2 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");
=head2 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);
=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 as reported by the client:
char *filename = upload->filename;
=item upload->fp
A file pointer to the uploaded file:
FILE *fp = upload->fp;
=item upload->tempname
The name of the temporary upload file on the server:
char *tempname = upload->tempname;
=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;
...
}
=back
=head2 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);
=head2 const char *ApacheUpload_info (ApacheUpload *upload, char *key)
Shortcut for accessing the I<info> table:
const char *type = ApacheUpload_info(upload, "Content-Type");
=head2 const char *ApacheUpload_type (ApacheUpload *upload)
Shortcut for accessing the uploaded file I<Content-Type>:
const char *type = ApacheUpload_type(upload);
=head1 ApacheCookie
=over 4
=head2 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);
=head2 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");
=head2 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);
...
}
}
=head2 int ApacheCookieItems (ApacheCookie *c)
The number of values for the given cookie.
=head2 char *ApacheCookieFetch (ApacheCookie *c, int n)
The I<n>th value for the given cookie.
=head2 void ApacheCookieAdd (ApacheCookie *c, char *value)
Add a new value to the cookie.
=head2 int ApacheCookieJarItems (ApacheCookieJar *cookies)
The number of cookies in the given cookie jar.
=head2 ApacheCookie *ApacheCookieJarFetch (ApacheCookieJar *cookies, int n)
The I<n>th cookie in the given cookie jar.
=head2 void ApacheCookieJarAdd (ApacheCookieJar *cookies, ApacheCookie *c)
Add a new cookie to the cookie jar.
=head2 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
=head2 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);
=head2 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 BUGS
=over 4
=item * multi-select file uploads are currently unsupported
=item * header-folding is unsupported for multipart/form-data
=item * newer XML-based MIME-encodings are not supported
=back
=head1 CREDITS
This library is based on Perl modules by Lincoln Stein.
=head1 AUTHOR
Doug MacEachern, updated for v1.0 by Joe Schaefer