Apache2::SubRequest(3pm)

1docs::api::Apache2::SubURseeqrueCsotn(t3r)ibuted Perl Dodcoucmse:n:taaptii:o:nApache2::SubRequest(3)
2
3
4

NAME

6       Apache2::SubRequest - Perl API for Apache subrequests
7

Synopsis

9         use Apache2::SubRequest ();
10
11         # run internal redirects at once
12         $r->internal_redirect($new_uri);
13         $r->internal_redirect_handler($new_uri);
14
15         # create internal redirect objects
16         $subr = $r->lookup_uri("/foo");
17         $subr = $r->lookup_method_uri("GET", "/tmp/bar")
18         $subr = $r->lookup_file("/tmp/bar");
19         # optionally manipulate the output through main request filters
20         $subr = $r->lookup_uri("/foo", $r->output_filters);
21         # now run them
22         my $rc = $subr->run;
23

Description

25       "Apache2::SubRequest" contains API for creating and running of Apache
26       sub-requests.
27
28       "Apache2::SubRequest" is a sub-class of "Apache2::RequestRec object".
29

API

31       "Apache2::SubRequest" provides the following functions and/or methods:
32
33       "DESTROY"
34
35       Free the memory associated with a sub request:
36
37         undef $subr; # but normally don't do that
38
39       obj: $subr ( "Apache2::SubRequest object" )
40           The sub request to finish
41
42       ret: no return value
43       since: 2.0.00
44
45       "DESTROY" is called automatically when $subr goes out of scope.
46
47       If you want to free the memory earlier than that (for example if you
48       run several subrequests), you can "undef" the object as:
49
50         undef $subr;
51
52       but never call "DESTROY" explicitly, since it'll result in
53       "ap_destroy_sub_req" being called more than once, resulting in multiple
54       brain injuries and certain hair loss.
55
56       "internal_redirect"
57
58       Redirect the current request to some other uri internally
59
60         $r->internal_redirect($new_uri);
61
62       obj: $r ( "Apache2::RequestRec object" )
63           The current request
64
65       arg1: $new_uri ( string )
66           The URI to replace the current request with
67
68       ret: no return value
69       since: 2.0.00
70
71       In case that you want some other request to be served as the top-level
72       request instead of what the client requested directly, call this method
73       from a handler, and then immediately return "Apache2::Const::OK". The
74       client will be unaware the a different request was served to her behind
75       the scenes.
76
77       "internal_redirect_handler"
78
79       Identical to "internal_redirect", plus automatically sets "$r->con‐
80       tent_type" is of the sub-request to be the same as of the main request,
81       if "$r->handler" is true.
82
83         $r->internal_redirect_handler($new_uri);
84
85       obj: $r ( "Apache2::RequestRec object" )
86           The current request
87
88       arg1: $new_uri ( string )
89           The URI to replace the current request with.
90
91       ret: no return value
92       since: 2.0.00
93
94       This function is designed for things like actions or CGI scripts, when
95       using "AddHandler", and you want to preserve the content type across an
96       internal redirect.
97
98       "lookup_file"
99
100       Create a subrequest for the given file.  This sub request can be
101       inspected to find information about the requested file
102
103         $ret = $r->lookup_file($new_file);
104         $ret = $r->lookup_file($new_file, $next_filter);
105
106       obj: $r ( "Apache2::RequestRec object" )
107           The current request
108
109       arg1: $new_file ( string )
110           The file to lookup
111
112       opt arg2: $next_filter ( "Apache2::Filter" )
113           See "$r->lookup_uri" for details.
114
115       ret: $ret ( "Apache2::SubRequest object" )
116           The sub request record.
117
118       since: 2.0.00
119
120       See "$r->lookup_uri" for further discussion.
121
122       "lookup_method_uri"
123
124       Create a sub request for the given URI using a specific method.  This
125       sub request can be inspected to find information about the requested
126       URI
127
128         $ret = $r->lookup_method_uri($method, $new_uri);
129         $ret = $r->lookup_method_uri($method, $new_uri, $next_filter);
130
131       obj: $r ( "Apache2::RequestRec object" )
132           The current request
133
134       arg1: $method ( string )
135           The method to use in the new sub request (e.g. "GET")
136
137       arg2: $new_uri ( string )
138           The URI to lookup
139
140       opt arg3: $next_filter ( "Apache2::Filter object" )
141           See "$r->lookup_uri" for details.
142
143       ret: $ret ( "Apache2::SubRequest object" )
144           The sub request record.
145
146       since: 2.0.00
147
148       See "$r->lookup_uri" for further discussion.
149
150       "lookup_uri"
151
152       Create a sub request from the given URI.  This sub request can be
153       inspected to find information about the requested URI.
154
155         $ret = $r->lookup_uri($new_uri);
156         $ret = $r->lookup_uri($new_uri, $next_filter);
157
158       obj: $r ( "Apache2::RequestRec object" )
159           The current request
160
161       arg1: $new_uri ( string )
162           The URI to lookup
163
164       opt arg2: $next_filter ( "Apache2::Filter object" )
165           The first filter the subrequest should pass the data through.  If
166           not specified it defaults to the first connection output filter for
167           the main request "$r->proto_output_filters". So if the subrequest
168           sends any output it will be filtered only once. If for example you
169           desire to apply the main request's output filters to the sub-
170           request output as well pass "$r->output_filters" as an argument.
171
172       ret: $ret ( "Apache2::SubRequest object" )
173           The sub request record
174
175       since: 2.0.00
176
177       Here is an example of a simple subrequest which serves uri /new_uri:
178
179         sub handler {
180             my $r = shift;
181
182             my $subr = $r->lookup_uri("/new_uri");
183             $sub->run;
184
185             return Apache2::Const::OK;
186         }
187
188       If let's say you have three request output filters registered to run
189       for the main request:
190
191         PerlOutputFilterHandler MyApache2::SubReqExample::filterA
192         PerlOutputFilterHandler MyApache2::SubReqExample::filterB
193         PerlOutputFilterHandler MyApache2::SubReqExample::filterC
194
195       and you wish to run them all, the code needs to become:
196
197             my $subr = $r->lookup_uri("/new_uri", $r->output_filters);
198
199       and if you wish to run them all, but the first one ("filterA"), the
200       code needs to be adjusted to be:
201
202             my $subr = $r->lookup_uri("/new_uri", $r->output_filters->next);
203
204       "run"
205
206       Run a sub-request
207
208         $rc = $subr->run();
209
210       obj: $subr ( "Apache2::RequestRec object" )
211           The sub-request (e.g. returned by "lookup_uri")
212
213       ret: $rc ( integer )
214           The return code of the handler ("Apache2::Const::OK",
215           "Apache2::Const::DECLINED", etc.)
216
217       since: 2.0.00
218

Unsupported API

220       "Apache2::SubRequest" also provides auto-generated Perl interface for a
221       few other methods which aren't tested at the moment and therefore their
222       API is a subject to change. These methods will be finalized later as a
223       need arises. If you want to rely on any of the following methods please
224       contact the the mod_perl development mailing list so we can help each
225       other take the steps necessary to shift the method to an officially
226       supported API.
227
228       "internal_fast_redirect"
229
230       META: Autogenerated - needs to be reviewed/completed
231
232       Redirect the current request to a sub_req, merging the pools
233
234         $r->internal_fast_redirect($sub_req);
235
236       obj: $r ( "Apache2::RequestRec object" )
237           The current request
238
239       arg1: $sub_req ( string )
240           A subrequest created from this request
241
242       ret: no return value
243       since: 2.0.00
244
245       META: httpd-2.0/modules/http/http_request.c declares this function as:
246
247         /* XXX: Is this function is so bogus and fragile that we deep-6 it? */
248
249       do we really want to expose it to mod_perl users?
250
251       "lookup_dirent"
252
253       META: Autogenerated - needs to be reviewed/completed
254
255       Create a sub request for the given apr_dir_read result.  This sub
256       request can be inspected to find information about the requested file
257
258         $lr = $r->lookup_dirent($finfo);
259         $lr = $r->lookup_dirent($finfo, $subtype);
260         $lr = $r->lookup_dirent($finfo, $subtype, $next_filter);
261
262       obj: $r ( "Apache2::RequestRec object" )
263           The current request
264
265       arg1: $finfo ( "APR::Finfo object" )
266           The apr_dir_read result to lookup
267
268       arg2: $subtype ( integer )
269           What type of subrequest to perform, one of;
270
271             Apache2::SUBREQ_NO_ARGS     ignore r->args and r->path_info
272             Apache2::SUBREQ_MERGE_ARGS  merge  r->args and r->path_info
273
274       arg3: $next_filter ( integer )
275           The first filter the sub_request should use.  If this is NULL, it
276           defaults to the first filter for the main request
277
278       ret: $lr ( "Apache2::RequestRec object" )
279           The new request record
280
281       since: 2.0.00
282
283       META: where do we take the apr_dir_read result from?
284

Copyright

289       mod_perl 2.0 and its core modules are copyrighted under The Apache
290       Software License, Version 2.0.
291

Authors

293       The mod_perl development team and numerous contributors.
294
295
296
297perl v5.8.8                       2006-11-19 docs::api::Apache2::SubRequest(3)