--- name: "libapreq" section: "3pm" platform: "linux" package: "libapache-request-perl" version: "1.33-1" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/libapreq" --- # libapreq(3pm) libapreq - Apache Request C Library 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"); ``` 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; } ``` 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; } ``` Sets the directory where upload files are spooled. ``` char dir[] = "/usr/tmp"; req->temp_dir = dir; ``` 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 success, 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** otherwise. See *ApacheUpload*. ``` ApacheUpload *upload = ApacheRequest_upload(req); ``` The *ApacheUpload* structure holds all information for all uploaded files and is accessed via the *upload* field of an *ApacheRequest* structure. The name of the filefield parameter: ``` char *name = upload->name; ``` The name of the upload file as reported by the client: ``` char *filename = upload->filename; ``` A file pointer to the uploaded file: ``` FILE *fp = upload->fp; ``` The name of the temporary upload file on the server: char \*tempname = upload-\>tempname; The size of the uploaded file in bytes: ``` long size = upload->size; ``` The additional header information for the uploaded file: ``` table *info = upload->info; const char *type = ap_table_get(info, "Content-type"); ``` 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\_new (request\_rec \*r, ...)** This function creates a new *ApacheCookie* object, using the given *request\_request* and optional attribute arguments which are as follows: Sets the *name* field to the given value. Adds the value to *values* field. Sets the *expires* field to the calculated date string. See *ApacheCookie\_expires* for a listing of format options. The default is **NULL**. Sets the *domain* field to the given value. The default is **NULL**. Sets the *path* field to the given value. The default *path* is derived from the requested *uri*. 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 *n*th 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 *n*th 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)); ``` This library is based on Perl modules by Lincoln Stein. ``` 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. ```