branches/1.x/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.

1	=head1 NAME
2
3	libapreq - Apache Request C Library
4
5	=head1 SYNOPSIS
6
7	=head1 DESCRIPTION
8
9	=head1 ApacheRequest
10
11	=over 4
12
13	=item req->parms
14
15	This field is an Apache I<table> that holds the parsed contents of
16	B<GET> and B<POST> requests.
17	Example:
18
19	table *data = req->parms;
20	ap_table_set(data, "Key", "Value");
21
22	=item req->post_max
23
24	=item ApacheRequest_set_post_max(req, max)
25
26	Limit the size of POST data. I<ApacheRequest_parse> will return an
27	error code if the size is exceeded:
28
29	int status;
30	ApacheRequest *req = ApacheRequest_new(r);
31
32	req->post_max = 1204;
33	if((status = ApacheRequest_parse(req)) != OK) {
34	char *errmsg = ap_table_get(r->notes, "error-notes");
35	...
36	return status;
37	}
38
39	=item req->disable_uploads
40
41	Disable file uploads. I<ApacheRequest_parse> will return an
42	error code if a file upload is attempted:
43
44	int status;
45	ApacheRequest *req = ApacheRequest_new(r);
46
47	req->disable_uploads = 1;
48	if((status = ApacheRequest_parse(req)) != OK) {
49	char *errmsg = ap_table_get(r->notes, "error-notes");
50	...
51	return status;
52	}
53
54
55	=item req->temp_dir
56
57	=item ApacheRequest_set_temp_dir(req, dir)
58
59	Sets the directory where upload files are spooled.
60
61	char dir[] = "/usr/tmp";
62	req->temp_dir = dir;
63
64
65	=item req->hook_data
66
67	=item req->upload_hook
68
69	Redirects upload data to be processed by the hook.
70
71	req->hook_data = (void *) data;
72	req->upload_hook = (int()(void,char,int,ApacheUpload)) func;
73
74	In this case
75
76	func(req->hook_data,buffer,bufsize,upload);
77
78	will be called repeatedly during the file upload instead of writing the
79	data to a temp file.
80
81	=back
82
83	=head2 ApacheRequest ApacheRequest_new (request_rec r)
84
85	This function creates a new I<ApacheRequest> object using the given
86	I<request_rec> structure:
87
88	ApacheRequest *req = ApacheRequest_new(r);
89
90	=head2 int ApacheRequest_parse (ApacheRequest *req)
91
92	If the request method is B<GET> or B<POST>, the query string
93	arguments and the client form data will be read, parsed and saved.
94	In addition, if the request method is B<POST> and the I<Content-type> is
95	I<multipart/form-data>, the uploaded files will be written to
96	temporary files which can be accessed with the I<upload> field names.
97	The return value is B<OK> on success, otherwise an error code that
98	your handler should return.
99
100	=head2 const char ApacheRequest_param (ApacheRequest req, const char *key)
101
102	This function will return the value of the given parameter I<key>:
103
104	const char *value = ApacheRequest_param(req, "Key");
105
106	=head2 array_header ApacheRequest_params (ApacheRequest req, const char *key)
107
108	This function will return an I<array_header> of values for the given
109	parameter I<key>:
110
111	array_header *values = ApacheRequest_params(req, "Key");
112
113	=head2 char ApacheRequest_params_as_string (ApacheRequest req, const char *key)
114
115	This function will format multi-value parmeters into a comma delimited string.
116
117	char *list = ApacheRequest_params_as_string(req, "Key");
118
119	=head2 ApacheUpload upload = ApacheRequest_upload (ApacheRequest req)
120
121	If the request I<Content-type> was that of I<multipart/form-data>,
122	this will return an I<ApacheUpload> pointer containing the upload data,
123	B<NULL> otherwise. See I<ApacheUpload>.
124
125	ApacheUpload *upload = ApacheRequest_upload(req);
126
127	=head1 ApacheUpload
128
129	The I<ApacheUpload> structure holds all information for all uploaded
130	files and is accessed via the I<upload> field of an I<ApacheRequest>
131	structure.
132
133	=over 4
134
135	=item upload->name
136
137	The name of the filefield parameter:
138
139	char *name = upload->name;
140
141	=item upload->filename
142
143	The name of the upload file as reported by the client:
144
145	char *filename = upload->filename;
146
147	=item upload->fp
148
149	A file pointer to the uploaded file:
150
151	FILE *fp = upload->fp;
152
153	=item upload->tempname
154
155	The name of the temporary upload file on the server:
156
157	char *tempname = upload->tempname;
158
159	=item upload->size
160
161	The size of the uploaded file in bytes:
162
163	long size = upload->size;
164
165	=item upload->info
166
167	The additional header information for the uploaded file:
168
169	table *info = upload->info;
170	const char *type = ap_table_get(info, "Content-type");
171
172	=item upload->next
173
174	Pointer to the next I<ApacheUpload> structure if multiple files were
175	uploaded:
176
177	ApacheUpload *uptr;
178	for (uptr = ApacheRequest_upload(req); uptr; uptr = uptr->next) {
179	char *name = uptr->name;
180	FILE *fp = uptr->fp;
181	...
182	}
183
184	=back
185
186	=head2 ApacheUpload ApacheUpload_find (ApacheUpload upload, char *name)
187
188	Returns the I<ApacheUpload> pointer associated with I<name> or
189	B<NULL> if I<name> is not found in the list:
190
191	ApacheUpload *upload = ApacheUpload_find(upload, name);
192
193	=head2 const char ApacheUpload_info (ApacheUpload upload, char *key)
194
195	Shortcut for accessing the I<info> table:
196
197	const char *type = ApacheUpload_info(upload, "Content-Type");
198
199	=head2 const char ApacheUpload_type (ApacheUpload upload)
200
201	Shortcut for accessing the uploaded file I<Content-Type>:
202
203	const char *type = ApacheUpload_type(upload);
204
205	=head1 ApacheCookie
206
207	=over 4
208
209	=head2 ApacheCookie ApacheCookie_new (request_rec r, ...)
210
211	This function creates a new I<ApacheCookie> object, using the given
212	I<request_request> and optional attribute arguments which are as follows:
213
214	=over 4
215
216	=item -name
217
218	Sets the I<name> field to the given value.
219
220	=item -value
221
222	Adds the value to I<values> field.
223
224	=item -expires
225
226	Sets the I<expires> field to the calculated date string.
227	See I<ApacheCookie_expires> for a listing of format options.
228	The default is B<NULL>.
229
230	=item -domain
231
232	Sets the I<domain> field to the given value.
233	The default is B<NULL>.
234
235	=item -path
236
237	Sets the I<path> field to the given value.
238	The default I<path> is derived from the requested I<uri>.
239
240	=item -secure
241
242	Sets the I<secure> field to true or false using a given string value
243	of I<On> or I<Off>.
244	The default is I<Off>.
245
246	=back
247
248	Example:
249
250	ApacheCookie *c = ApacheCookie_new(r,
251	"-name", "foo",
252	"-value", "bar",
253	"-expires", "+3M",
254	"-domain", ".cp.net",
255	"-path", "/mypath/database",
256	"-secure", "On",
257	NULL);
258
259
260	=head2 char ApacheCookie_attr (ApacheCookie c, char key, char val)
261
262	This function is used to get or set a cookie attribute pair, accepting
263	the same attributes as the list above. Example:
264
265	char name = ApacheCookie_attr(c, "-name"); / same as c->name */
266	(void *)ApacheCookie_attr(c, "-expires", "+3h");
267
268	=head2 ApacheCookieJar ApacheCookie_parse (request_rec r, const char *data)
269
270	This function parses the given I<data> string or the incoming
271	I<Cookie> header, returning an I<ApacheCookieJar> of I<ApacheCookie>
272	objects.
273
274	Example:
275
276	int i;
277	ApacheCookieJar *cookies = ApacheCookie_parse(r, NULL);
278	for (i = 0; i < ApacheCookieJarItems(cookies); i++) {
279	ApacheCookie *c = ApacheCookieJarFetch(cookies, i);
280	int j;
281	for (j = 0; j < ApacheCookieItems(c); j++) {
282	char *name = c->name;
283	char *value = ApacheCookieFetch(c, j);
284	...
285	}
286	}
287
288	=head2 int ApacheCookieItems (ApacheCookie *c)
289
290	The number of values for the given cookie.
291
292	=head2 char ApacheCookieFetch (ApacheCookie c, int n)
293
294	The I<n>th value for the given cookie.
295
296	=head2 void ApacheCookieAdd (ApacheCookie c, char value)
297
298	Add a new value to the cookie.
299
300	=head2 int ApacheCookieJarItems (ApacheCookieJar *cookies)
301
302	The number of cookies in the given cookie jar.
303
304	=head2 ApacheCookie ApacheCookieJarFetch (ApacheCookieJar cookies, int n)
305
306	The I<n>th cookie in the given cookie jar.
307
308	=head2 void ApacheCookieJarAdd (ApacheCookieJar cookies, ApacheCookie c)
309
310	Add a new cookie to the cookie jar.
311
312	=head2 char ApacheCookie_expires (ApacheCookie c, char *time_str)
313
314	This function gets or sets the expiration date for cookie.
315	The following forms are all valid for the I<time_str> parmeter:
316
317	+30s 30 seconds from now
318	+10m ten minutes from now
319	+1h one hour from now
320	-1d yesterday (i.e. "ASAP!")
321	now immediately
322	+3M in three months
323	+10y in ten years time
324	Thursday, 25-Apr-1999 00:40:33 GMT at the indicated time & date
325
326	=head2 void ApacheCookie_bake (ApacheCookie *c)
327
328	Put cookie in the oven to bake.
329	(Add a I<Set-Cookie> header to the outgoing headers table.)
330
331	ApacheCookie_bake(c);
332
333	=head2 char ApacheCookie_as_string (ApacheCookie c)
334
335	Returns a string version of the cookie:
336
337	ap_table_add(r->headers_out, "Set-Cookie", ApacheCookie_as_string(c));
338
339	=back
340
341	=head1 BUGS
342
343	=over 4
344
345	=item * multi-select file uploads are currently unsupported
346
347	=item * header-folding is unsupported for multipart/form-data
348
349	=item * newer XML-based MIME-encodings are not supported
350
351	=back
352
353	=head1 CREDITS
354
355	This library is based on Perl modules by Lincoln Stein.
356
357	=head1 LICENSE
358
359	Copyright 2000-2004 The Apache Software Foundation
360
361	Licensed under the Apache License, Version 2.0 (the "License");
362	you may not use this file except in compliance with the License.
363	You may obtain a copy of the License at
364
365	http://www.apache.org/licenses/LICENSE-2.0
366
367	Unless required by applicable law or agreed to in writing, software
368	distributed under the License is distributed on an "AS IS" BASIS,
369	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
370	See the License for the specific language governing permissions and
371	limitations under the License.
372
infrastructure at apache.org	ViewVC Help
Powered by ViewVC 1.1.26