stas 2004/08/13 22:10:32
Modified: src/docs/2.0/api/Apache SubRequest.pod
Log:
finish the manpage
Revision Changes Path
1.5 +255 -91 modperl-docs/src/docs/2.0/api/Apache/SubRequest.pod
Index: SubRequest.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/SubRequest.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -u -r1.4 -r1.5
--- SubRequest.pod 22 May 2004 02:03:27 -0000 1.4
+++ SubRequest.pod 14 Aug 2004 05:10:31 -0000 1.5
@@ -8,15 +8,35 @@
=head1 Synopsis
use Apache::SubRequest ();
-
-META: to be completed
+
+ # run internal redirects at once
+ $r->internal_redirect($new_uri);
+ $r->internal_redirect_handler($new_uri);
+
+ # create internal redirect objects
+ $subr = $r->lookup_uri("/foo");
+ $subr = $r->lookup_method_uri("GET", "/tmp/bar")
+ $subr = $r->lookup_file("/tmp/bar");
+ # optionally manipulate the output through main request filters
+ $subr = $r->lookup_uri("/foo", $r->output_filters);
+ # now run them
+ my $rc = $subr->run;
+ # optional
+ $subr->DESTROY;
=head1 Description
-META: to be completed
+C<Apache::SubRequest> contains API for creating and running of Apache
+sub-requests.
+
+C<Apache::SubRequest> is a sub-class of C<L<Apache::RequestRec
+object|docs::2.0::api::Apache::RequestRec>>.
+
+
+
@@ -28,255 +48,399 @@
-=head2 C<DESTROY>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<DESTROY>
Free the memory associated with a sub request
- $r->DESTROY();
+ $subr->DESTROY();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$subr> ( C<L<Apache::SubRequest
+object|docs::2.0::api::Apache::SubRequest/Description>> )
The sub request to finish
=item ret: no return value
+=item since: 1.99_12
+
=back
+This method will be called automatically when C<$subr> goes out of
+scope, so there is no need to call it explicitly, unless you want to
+free the memory earlier than that (for example if you run several
+subrequests).
+
+
+
+
-=head2 C<internal_fast_redirect>
-META: Autogenerated - needs to be reviewed/completed
-Redirect the current request to a sub_req, merging the pools
- $r->internal_fast_redirect($sub_req);
+
+=head2 C<internal_redirect>
+
+Redirect the current request to some other uri internally
+
+ $r->internal_redirect($new_uri);
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item arg1: C<$sub_req> (string)
+=item arg1: C<$new_uri> ( string )
-A subrequest created from this request
+The URI to replace the current request with
=item ret: no return value
+=item since: 1.99_12
+
=back
+In case that you want some other request to be served as the top-level
+request instead of what the client requested directly, call this
+method from a handler, and then immediately return C<Apache::OK>. The
+client will be unaware the a different request was served to her
+behind the scenes.
-=head2 C<internal_redirect>
-META: Autogenerated - needs to be reviewed/completed
-Then there's the case that you want some other request to be served as
-the top-level request INSTEAD of what the client requested directly.
-If so, call this from a handler, and then immediately return OK.
-Redirect the current request to some other uri
- $r->internal_redirect($new_uri);
+=head2 C<internal_redirect_handler>
+
+Identical to C<internal_redirect|/C_internal_redirect_>, plus
+automatically sets
+C<L<$r-E<gt>content_type|docs::2.0::api::Apache::RequestRec/C_content_type_>>
+is of the sub-request to be the same as of the main request, if
+C<L<$r-E<gt>handler|docs::2.0::api::Apache::RequestRec/C_handler_>> is
+true.
+
+ $r->internal_redirect_handler($new_uri);
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item arg1: C<$new_uri> (string)
+=item arg1: C<$new_uri> ( string )
-The URI to replace the current request with
+The URI to replace the current request with.
=item ret: no return value
+=item since: 1.99_12
+
=back
+This function is designed for things like actions or CGI scripts, when
+using C<AddHandler>, and you want to preserve the content type across
+an internal redirect.
-=head2 C<internal_redirect_handler>
-META: Autogenerated - needs to be reviewed/completed
-This function is designed for things like actions or CGI scripts, when
-using AddHandler, and you want to preserve the content type across an
-internal redirect.
- $r->internal_redirect_handler($new_uri);
+
+
+
+=head2 C<lookup_file>
+
+Create a subrequest for the given file. This sub request can be
+inspected to find information about the requested file
+
+ $ret = $r->lookup_file($new_file);
+ $ret = $r->lookup_file($new_file, $next_filter);
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item arg1: C<$new_uri> (string)
+=item arg1: C<$new_file> ( string )
-The URI to replace the current request with.
+The file to lookup
-=item ret: no return value
+=item opt arg2: C<$next_filter>
+( C<L<Apache::Filter|docs::2.0::api::Apache::Filter>> )
-=back
+See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for details.
+=item ret: C<$ret> ( C<L<Apache::SubRequest
+object|docs::2.0::api::Apache::SubRequest/Description>> )
+The sub request record.
+=item since: 1.99_15
+=back
-=head2 C<lookup_dirent>
+See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for further discussion.
-META: Autogenerated - needs to be reviewed/completed
-Create a sub request for the given apr_dir_read result. This sub request
-can be inspected to find information about the requested file
- $lr = $r->lookup_dirent($finfo, $subtype, $next_filter);
+
+=head2 C<lookup_method_uri>
+
+Create a sub request for the given URI using a specific method. This
+sub request can be inspected to find information about the requested
+URI
+
+ $ret = $r->lookup_method_uri($method, $new_uri);
+ $ret = $r->lookup_method_uri($method, $new_uri, $next_filter);
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item arg1: C<$finfo> (C<L<APR::Finfo|docs::2.0::api::APR::Finfo>>)
+=item arg1: C<$method> ( string )
-The apr_dir_read result to lookup
+The method to use in the new sub request (e.g. C<"GET">)
-=item arg2: C<$subtype> (integer)
+=item arg2: C<$new_uri> ( string )
-What type of subrequest to perform, one of;
+The URI to lookup
- Apache::SUBREQ_NO_ARGS ignore r->args and r->path_info
- Apache::SUBREQ_MERGE_ARGS merge r->args and r->path_info
+=item opt arg3: C<$next_filter>
+( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
-=item arg3: C<$next_filter> (integer)
+See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for details.
-The first filter the sub_request should use. If this is
-NULL, it defaults to the first filter for the main request
+=item ret: C<$ret> ( C<L<Apache::SubRequest
+object|docs::2.0::api::Apache::SubRequest/Description>> )
-=item ret: C<$lr>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+The sub request record.
-The new request record
+=item since: 1.99_15
=back
+See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for further discussion.
-=head2 C<lookup_file>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<lookup_uri>
-Create a sub request for the given file. This sub request can be
-inspected to find information about the requested file
+Create a sub request from the given URI. This sub request can be
+inspected to find information about the requested URI.
- $ret = $r->lookup_file($new_file, $next_filter);
+ $ret = $r->lookup_uri($new_uri);
+ $ret = $r->lookup_uri($new_uri, $next_filter);
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item arg1: C<$new_file> (string)
+=item arg1: C<$new_uri> ( string )
The URI to lookup
-=item arg2: C<$next_filter>
(C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)
+=item opt arg2: C<$next_filter>
+( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
-The first filter the sub_request should use. If this is NULL, it
-defaults to the first filter for the main request
+The first filter the subrequest should pass the data through. If not
+specified it defaults to the first connection output filter for the
+main request
+C<L<$r-E<gt>proto_output_filters|docs::2.0::api::Apache::RequestRec/C_proto_output_filters_>>.
So
+if the subrequest sends any output it will be filtered only once. If
+for example you desire to apply the main request's output filters to
+the sub-request output as well pass
+C<L<$r-E<gt>output_filters|docs::2.0::api::Apache::RequestRec/C_output_filters_>>
+as an argument.
-=item ret: C<$ret>
(C<L<Apache::SubRequest|docs::2.0::api::Apache::SubRequest>>)
+=item ret: C<$ret> ( C<L<Apache::SubRequest
+object|docs::2.0::api::Apache::SubRequest/Description>> )
-The new request record
+The sub request record
+
+=item since: 1.99_15
=back
+Here is an example of a simple subrequest which serves uri
+I</new_uri>:
+ sub handler {
+ my $r = shift;
+
+ my $subr = $r->lookup_uri("/new_uri");
+ $sub->run;
+
+ return Apache::OK;
+ }
+If let's say you have three request output filters registered to run
+for the main request:
+
+ PerlOutputFilterHandler MyApache::SubReqExample::filterA
+ PerlOutputFilterHandler MyApache::SubReqExample::filterB
+ PerlOutputFilterHandler MyApache::SubReqExample::filterC
+
+and you wish to run them all, the code needs to become:
+
+ my $subr = $r->lookup_uri("/new_uri", $r->output_filters);
+
+and if you wish to run them all, but the first one (C<filterA>), the
+code needs to be adjusted to be:
+
+ my $subr = $r->lookup_uri("/new_uri", $r->output_filters->next);
+
+
+
+
+
+=head2 C<run>
+
+Run a sub-request
+
+ $rc = $subr->run();
+
+=over 4
+
+=item obj: C<$subr>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+
+The sub-request (e.g. returned by C<L<lookup_uri|/C_lookup_uri_>>)
+
+=item ret: C<$rc> ( integer )
+
+The return code of the handler (C<Apache::OK>, C<Apache::DECLINED>,
+etc.)
+
+=item since: 1.99_12
+
+=back
+
+
+
+
+
+
+=head1 Unsupported API
+
+C<Apache::SubRequest> also provides auto-generated Perl interface for
+a few other methods which aren't tested at the moment and therefore
+their API is a subject to change. These methods will be finalized
+later as a need arises. If you want to rely on any of the following
+methods please contact the L<the mod_perl development mailing
+list|maillist::dev> so we can help each other take the steps necessary
+to shift the method to an officially supported API.
-=head2 C<lookup_uri>
+
+
+
+
+=head2 C<internal_fast_redirect>
META: Autogenerated - needs to be reviewed/completed
-Create a sub request from the given URI. This sub request can be
-inspected to find information about the requested URI.
+Redirect the current request to a sub_req, merging the pools
- $ret = $r->lookup_uri($new_file, $next_filter);
+ $r->internal_fast_redirect($sub_req);
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item arg1: C<$new_file> (string)
+=item arg1: C<$sub_req> ( string )
-The URI to lookup
+A subrequest created from this request
-=item arg2: C<$next_filter>
(C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)
+=item ret: no return value
-The first filter the sub_request should use. If this is NULL, it
-defaults to the first filter for the main request
+=item since: 1.99_12
-=item ret: C<$ret>
(C<L<Apache::SubRequest|docs::2.0::api::Apache::SubRequest>>)
+=back
-The new request record
-=back
+META: httpd-2.0/modules/http/http_request.c declares this function as:
+ /* XXX: Is this function is so bogus and fragile that we deep-6 it? */
+
+do we really want to expose it to mod_perl users?
-=head2 C<lookup_method_uri>
+
+
+=head2 C<lookup_dirent>
META: Autogenerated - needs to be reviewed/completed
-Create a sub request for the given URI using a specific method. This
-sub request can be inspected to find information about the requested
-URI
+Create a sub request for the given apr_dir_read result. This sub request
+can be inspected to find information about the requested file
- $ret = $r->lookup_method_uri($method, $new_file, $next_filter);
+ $lr = $r->lookup_dirent($finfo);
+ $lr = $r->lookup_dirent($finfo, $subtype);
+ $lr = $r->lookup_dirent($finfo, $subtype, $next_filter);
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item arg1: C<$method> (string)
+=item arg1: C<$finfo>
+( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
-The method to use in the new sub request
+The apr_dir_read result to lookup
-=item arg2: C<$new_file> (string)
+=item arg2: C<$subtype> ( integer )
-The URI to lookup
+What type of subrequest to perform, one of;
-=item arg3: C<$next_filter>
(C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)
+ Apache::SUBREQ_NO_ARGS ignore r->args and r->path_info
+ Apache::SUBREQ_MERGE_ARGS merge r->args and r->path_info
-The first filter the sub_request should use. If this is NULL, it
-defaults to the first filter for the main request
+=item arg3: C<$next_filter> ( integer )
-=item ret: C<$ret>
(C<L<Apache::SubRequest|docs::2.0::api::Apache::SubRequest>>)
+The first filter the sub_request should use. If this is
+NULL, it defaults to the first filter for the main request
+
+=item ret: C<$lr>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The new request record
+=item since: 1.99_12
+
=back
+
+META: where do we take the apr_dir_read result from?
+
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
