Apache::SubRequest - Perl API for Apache subrequests

Unsupported API

internal_fast_redirect
lookup_dirent

See Also
Copyright
Authors

NAME

Apache::SubRequest - Perl API for Apache subrequests

Synopsis

  use Apache::SubRequest ();


  # 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;

Description

Apache::SubRequest contains API for creating and running of Apache sub-requests.

Apache::SubRequest is a sub-class of Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>.

API

Apache::SubRequest provides the following functions and/or methods:

`DESTROY`

Free the memory associated with a sub request

  $subr->DESTROY();

obj: $subr ( Apache::SubRequest object|docs::2.0::api::Apache::SubRequest/Description> ): The sub request to finish
ret: no return value
since: 1.99_12

This method will be called automatically when $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).

`internal_redirect`

Redirect the current request to some other uri internally

  $r->internal_redirect($new_uri);

obj: $r ( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec ): The current request
arg1: $new_uri ( string ): The URI to replace the current request with
ret: no return value
since: 1.99_12

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 Apache::OK. The client will be unaware the a different request was served to her behind the scenes.

`internal_redirect_handler`

Identical to internal_redirect|/C_internal_redirect_, plus automatically sets $r->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 $r->handler|docs::2.0::api::Apache::RequestRec/C_handler_ is true.

  $r->internal_redirect_handler($new_uri);

obj: $r ( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec ): The current request
arg1: $new_uri ( string ): The URI to replace the current request with.
ret: no return value
since: 1.99_12

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.

`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);

obj: $r ( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec ): The current request
arg1: $new_file ( string ): The file to lookup
opt arg2: $next_filter ( Apache::Filter|docs::2.0::api::Apache::Filter ): See $r->lookup_uri|/C_lookup_uri_ for details.
ret: $ret ( Apache::SubRequest object|docs::2.0::api::Apache::SubRequest/Description> ): The sub request record.
since: 1.99_15

See $r->lookup_uri|/C_lookup_uri_ for further discussion.

`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);

obj: $r ( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec ): The current request
arg1: $method ( string ): The method to use in the new sub request (e.g. "GET")
arg2: $new_uri ( string ): The URI to lookup
opt arg3: $next_filter ( Apache::Filter object|docs::2.0::api::Apache::Filter ): See $r->lookup_uri|/C_lookup_uri_ for details.
ret: $ret ( Apache::SubRequest object|docs::2.0::api::Apache::SubRequest/Description> ): The sub request record.
since: 1.99_15

See $r->lookup_uri|/C_lookup_uri_ for further discussion.

`lookup_uri`

Create a sub request from the given URI. This sub request can be inspected to find information about the requested URI.

  $ret = $r->lookup_uri($new_uri);
  $ret = $r->lookup_uri($new_uri, $next_filter);

obj: $r ( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec ): The current request
arg1: $new_uri ( string ): The URI to lookup
opt arg2: $next_filter ( Apache::Filter object|docs::2.0::api::Apache::Filter ): 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 $r->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 $r->output_filters|docs::2.0::api::Apache::RequestRec/C_output_filters_ as an argument.
ret: $ret ( Apache::SubRequest object|docs::2.0::api::Apache::SubRequest/Description> ): The sub request record
since: 1.99_15

Here is an example of a simple subrequest which serves uri /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 (filterA), the code needs to be adjusted to be:

      my $subr = $r->lookup_uri("/new_uri", $r->output_filters->next);

`run`

Run a sub-request

  $rc = $subr->run();

obj: $subr ( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec ): The sub-request (e.g. returned by lookup_uri|/C_lookup_uri_)
ret: $rc ( integer ): The return code of the handler (Apache::OK, Apache::DECLINED, etc.)
since: 1.99_12

Unsupported API

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 the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

`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);

obj: $r ( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec ): The current request
arg1: $sub_req ( string ): A subrequest created from this request
ret: no return value
since: 1.99_12

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?

`lookup_dirent`

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);
  $lr = $r->lookup_dirent($finfo, $subtype);
  $lr = $r->lookup_dirent($finfo, $subtype, $next_filter);

obj: $r ( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )

The current request

arg1: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )

The apr_dir_read result to lookup

arg2: $subtype ( integer )

What type of subrequest to perform, one of;

  Apache::SUBREQ_NO_ARGS     ignore r->args and r->path_info
  Apache::SUBREQ_MERGE_ARGS  merge  r->args and r->path_info

arg3: $next_filter ( integer )

The first filter the sub_request should use. If this is NULL, it defaults to the first filter for the main request

ret: $lr ( Apache::RequestRec object|docs::2.0::api::Apache::RequestRec )

The new request record

since: 1.99_12

META: where do we take the apr_dir_read result from?

Copyright

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

Authors

The mod_perl development team and numerous contributors.

Apache::SubRequest - Perl API for Apache subrequests