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

Unsupported API

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

Copyright

280       mod_perl 2.0 and its core modules are copyrighted under The Apache
281       Software License, Version 2.0.
282

Authors

284       The mod_perl development team and numerous contributors.
285
286
287
288perl v5.36.0                      2022-07-21 docs::api::Apache2::SubRequest(3)