libapreq(3) User Contributed Perl Documentation libapreq(3)NAMElibapreq - Apache Request C Library
SYNOPSISDESCRIPTIONApacheRequest
req->parms
This field is an Apache table that holds the parsed contents of GET
and POST requests. Example:
table *data = req->parms;
ap_table_set(data, "Key", "Value");
req->post_max
ApacheRequest_set_post_max(req, max)
Limit the size of POST data. 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;
}
req->disable_uploads
Disable file uploads. 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;
}
req->temp_dir
ApacheRequest_set_temp_dir(req, dir)
Sets the directory where upload files are spooled.
char dir[] = "/usr/tmp";
req->temp_dir = dir;
req->hook_data
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.
ApacheRequest *ApacheRequest_new (request_rec *r)
This function creates a new ApacheRequest object using the given
request_rec structure:
ApacheRequest *req = ApacheRequest_new(r);
int ApacheRequest_parse (ApacheRequest *req)
If the request method is GET or POST, the query string arguments and
the client form data will be read, parsed and saved. In addition, if
the request method is POST and the Content-type is multipart/form-data,
the uploaded files will be written to temporary files which can be
accessed with the upload field names. The return value is OK on suc-
cess, otherwise an error code that your handler should return.
const char *ApacheRequest_param (ApacheRequest *req, const char *key)
This function will return the value of the given parameter key:
const char *value = ApacheRequest_param(req, "Key");
array_header *ApacheRequest_params (ApacheRequest *req, const char
*key)
This function will return an array_header of values for the given
parameter key:
array_header *values = ApacheRequest_params(req, "Key");
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");
ApacheUpload *upload = ApacheRequest_upload (ApacheRequest *req)
If the request Content-type was that of multipart/form-data, this will
return an ApacheUpload pointer containing the upload data, NULL other-
wise. See ApacheUpload.
ApacheUpload *upload = ApacheRequest_upload(req);
ApacheUpload
The ApacheUpload structure holds all information for all uploaded files
and is accessed via the upload field of an ApacheRequest structure.
upload->name
The name of the filefield parameter:
char *name = upload->name;
upload->filename
The name of the upload file as reported by the client:
char *filename = upload->filename;
upload->fp
A file pointer to the uploaded file:
FILE *fp = upload->fp;
upload->tempname
The name of the temporary upload file on the server:
char *tempname = upload->tempname;
upload->size
The size of the uploaded file in bytes:
long size = upload->size;
upload->info
The additional header information for the uploaded file:
table *info = upload->info;
const char *type = ap_table_get(info, "Content-type");
upload->next
Pointer to the next 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;
...
}
ApacheUpload *ApacheUpload_find (ApacheUpload *upload, char *name)
Returns the ApacheUpload pointer associated with name or NULL if name
is not found in the list:
ApacheUpload *upload = ApacheUpload_find(upload, name);
const char *ApacheUpload_info (ApacheUpload *upload, char *key)
Shortcut for accessing the info table:
const char *type = ApacheUpload_info(upload, "Content-Type");
const char *ApacheUpload_type (ApacheUpload *upload)
Shortcut for accessing the uploaded file Content-Type:
const char *type = ApacheUpload_type(upload);
ApacheCookie
ApacheCookie *ApacheCookie_new (request_rec *r, ...)
This function creates a new ApacheCookie object, using the given
request_request and optional attribute arguments which are as fol-
lows:
-name
Sets the name field to the given value.
-value
Adds the value to values field.
-expires
Sets the expires field to the calculated date string. See
ApacheCookie_expires for a listing of format options. The
default is NULL.
-domain
Sets the domain field to the given value. The default is NULL.
-path
Sets the path field to the given value. The default path is
derived from the requested uri.
-secure
Sets the secure field to true or false using a given string
value of On or Off. The default is Off.
Example:
ApacheCookie *c = ApacheCookie_new(r,
"-name", "foo",
"-value", "bar",
"-expires", "+3M",
"-domain", ".cp.net",
"-path", "/mypath/database",
"-secure", "On",
NULL);
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");
ApacheCookieJar *ApacheCookie_parse (request_rec *r, const char
*data)
This function parses the given data string or the incoming Cookie
header, returning an ApacheCookieJar of 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);
...
}
}
int ApacheCookieItems (ApacheCookie *c)
The number of values for the given cookie.
char *ApacheCookieFetch (ApacheCookie *c, int n)
The nth value for the given cookie.
void ApacheCookieAdd (ApacheCookie *c, char *value)
Add a new value to the cookie.
int ApacheCookieJarItems (ApacheCookieJar *cookies)
The number of cookies in the given cookie jar.
ApacheCookie *ApacheCookieJarFetch (ApacheCookieJar *cookies, int
n)
The nth cookie in the given cookie jar.
void ApacheCookieJarAdd (ApacheCookieJar *cookies, ApacheCookie *c)
Add a new cookie to the cookie jar.
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 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
void ApacheCookie_bake (ApacheCookie *c)
Put cookie in the oven to bake. (Add a Set-Cookie header to the
outgoing headers table.)
ApacheCookie_bake(c);
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));
BUGS
* multi-select file uploads are currently unsupported
* header-folding is unsupported for multipart/form-data
* newer XML-based MIME-encodings are not supported
CREDITS
This library is based on Perl modules by Lincoln Stein.
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.
perl v5.8.8 2004-11-26 libapreq(3)
