=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