=head1 NAME
libapreq - Apache Request C Library
=head1 SYNOPSIS
=head1 DESCRIPTION
=head1 ApacheRequest
=over 4
=item req->parms
This field is an Apache I
that holds the parsed contents of
B and B 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 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 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 object using the given
I structure:
ApacheRequest *req = ApacheRequest_new(r);
=head2 int ApacheRequest_parse (ApacheRequest *req)
If the request method is B or B, the query string
arguments and the client form data will be read, parsed and saved.
In addition, if the request method is B and the I is
I, the uploaded files will be written to
temporary files which can be accessed with the I field names.
The return value is B 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:
const char *value = ApacheRequest_param(req, "Key");
=head2 array_header *ApacheRequest_params (ApacheRequest *req, const char *key)
This function will return an I of values for the given
parameter I:
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 was that of I,
this will return an I pointer containing the upload data,
B otherwise. See I.
ApacheUpload *upload = ApacheRequest_upload(req);
=head1 ApacheUpload
The I structure holds all information for all uploaded
files and is accessed via the I field of an I
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 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 pointer associated with I or
B if I 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 table:
const char *type = ApacheUpload_info(upload, "Content-Type");
=head2 const char *ApacheUpload_type (ApacheUpload *upload)
Shortcut for accessing the uploaded file I:
const char *type = ApacheUpload_type(upload);
=head1 ApacheCookie
=over 4
=head2 ApacheCookie *ApacheCookie_new (request_rec *r, ...)
This function creates a new I object, using the given
I and optional attribute arguments which are as follows:
=over 4
=item -name
Sets the I field to the given value.
=item -value
Adds the value to I field.
=item -expires
Sets the I field to the calculated date string.
See I for a listing of format options.
The default is B.
=item -domain
Sets the I field to the given value.
The default is B.
=item -path
Sets the I field to the given value.
The default I is derived from the requested I.
=item -secure
Sets the I field to true or false using a given string value
of I or I.
The default is I.
=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 string or the incoming
I header, returning an I of I
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 Ith 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 Ith 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 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 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