libapreq.pod

=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 LICENSE

  Copyright 2000-2004  The Apache Software Foundation

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.