perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/api/Apache HookRun.pod
Date Wed, 18 Aug 2004 06:29:08 GMT
stas        2004/08/17 23:29:08

  Modified:    src/docs/2.0/api/Apache HookRun.pod
  Log:
  complete Apache::HookRun
  
  Revision  Changes    Path
  1.4       +310 -138  modperl-docs/src/docs/2.0/api/Apache/HookRun.pod
  
  Index: HookRun.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/HookRun.pod,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -u -r1.3 -r1.4
  --- HookRun.pod	22 May 2004 02:03:27 -0000	1.3
  +++ HookRun.pod	18 Aug 2004 06:29:07 -0000	1.4
  @@ -1,22 +1,112 @@
   =head1 NAME
   
  -Apache::HookRun - Perl API for XXX
  +Apache::HookRun - Perl API for Invoking Apache HTTP phases
   
   
   
   
   =head1 Synopsis
   
  +  # httpd.conf
  +  PerlProcessConnectionHandler MyApache::PseudoHTTP::handler
  +
  +  #file:MyApache/PseudoHTTP.pm
  +  #---------------------------
  +  package MyApache::PseudoHTTP;
  +  
     use Apache::HookRun ();
  +  use Apache::RequestUtil ();
  +  use Apache::RequestRec ();
  +  
  +  use Apache::Const -compile => qw(OK DECLINED DONE SERVER_ERROR);
  +  
  +  # implement the HTTP protocol cycle in protocol handler
  +  sub handler {
  +      my $c = shift;
  +      my $r = Apache::RequestRec->new($c);
  +  
  +      # register any custom callbacks here, e.g.:
  +      # $r->push_handlers(PerlAccessHandler => \&my_access);
  +  
  +      $rc = $r->run_post_read_request();
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      $rc = $r->run_translate_name;
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      $rc = $r->run_map_to_storage;
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      # this must be run all a big havoc will happen in the following
  +      # phases
  +      $r->location_merge($path);
  +  
  +      $rc = $r->run_header_parser;
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      my $args = $r->args || '';
  +      if ($args eq 'die') {
  +          $r->die(Apache::SERVER_ERROR);
  +          return Apache::DONE;
  +      }
  +  
  +      $rc = $r->run_access_checker;
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      $rc = $r->run_auth_checker;
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      $rc = $r->run_check_user_id;
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      $rc = $r->run_type_checker;
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      $rc = $r->run_fixups;
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      # $r->run_handler is called internally by $r->invoke_handler,
  +      # invoke_handler sets all kind of filters, and does a few other
  +      # things but it's possible to call $r->run_handler, bypassing
  +      # invoke_handler
  +      $rc = $r->invoke_handler;
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      $rc = $r->run_log_transaction;
  +      return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
  +  
  +      return Apache::OK;
  +  }
   
  -META: to be completed
   
   
   
   
   =head1 Description
   
  -META: to be completed
  +C<Apache::HookRun> exposes parts of the Apache HTTP protocol
  +implementation, responsible for invoking callbacks for each L<HTTP
  +Request cycle
  +phase|docs::2.0::user::handlers::http/HTTP_Request_Cycle_Phases>.
  +
  +Armed with that API, you could run some of the http protocol framework
  +parts when implementing your own protocols. For example see how HTTP
  +AAA (access, auth and authz) hooks are called from a protocol handler,
  +implementing L<a command
  +server|docs::2.0::user::handlers::protocols/Command_Server>, which has
  +nothing to do with HTTP. Also you can see in L<Synopsis|/Synopsis> how
  +to re-implement Apache HTTP cycle in the protocol handler.
  +
  +Using this API you could probably also change the normal Apache
  +behavior (e.g. invoking some hooks earlier than normal, or later), but
  +before doing that you will probably need to spend some time reading
  +through the Apache C code. That's why some of the methods in this
  +document, point you to the specific functions in the Apache source
  +code. If you just try to use the methods from this module, without
  +understanding them well, don't be surprised if you will get some nasty
  +crashes, from which mod_perl can't protect you.
  +
  +
   
   
   
  @@ -28,9 +118,11 @@
   
   
   
  -=head2 C<die>
   
  -META: Autogenerated - needs to be reviewed/completed
  +
  +
  +
  +=head2 C<die>
   
   Kill the current request
   
  @@ -38,152 +130,178 @@
   
   =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<$type> (XXX)
  +=item arg1: C<$type> ( integer )
   
  -Why the request is dieing
  +Why the request is dieing. Expects an Apache status constant.
   
   =item ret: no return value
   
  +=item since: 1.99_12
  +
   =back
   
  +This method doesn't really abort the request, it just handles the
  +sending of the error response, logging the error and such.  You want
  +to take a look at the internals of C<ap_die()> in
  +F<httpd-2.0/modules/http/http_request.c> for more details.
   
   
   
   
  -=head2 C<invoke_handler>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=head2 C<invoke_handler>
   
  -Run the handler phase of each module until a module accepts the
  -responsibility of serving the request
  +Run the
  +L<response|docs::2.0::user::handlers::http/PerlResponseHandler> phase.
   
  -  $ret = $r->invoke_handler();
  +  $rc = $r->invoke_handler();
   
   =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 ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
   
  -The status of the current request
  +The status of the current phase run: C<Apache::OK>,
  +C<Apache::HTTP_...>
  +
  +=item since: 1.99_12
   
   =back
   
  +C<invoke_handler()> allows modules to insert filters, sets a default
  +handler if none is set, runs C<L<run_handler()|/C_run_handler_>> and
  +handles some errors.
  +
  +For more details see C<ap_invoke_handler()> in
  +F<httpd-2.0/server/config.c>.
  +
  +
   
   
   
   
  -=head2 C<run_access_checker>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -This hook is used to apply additional access control to this resource.
  -It runs *before* a user is authenticated, so this hook is really to
  -apply additional restrictions independent of a user. It also runs
  -independent of 'Require' directive usage.
  +=head2 C<run_access_checker>
  +
  +Run the resource L<access
  +control|docs::2.0::user::handlers::http/PerlAccessHandler> phase.
   
  -  $ret = $r->run_access_checker();
  +  $rc = $r->run_access_checker();
   
   =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 ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
  +
  +The status of the current phase run: C<Apache::OK>,
  +C<Apache::DECLINED>, C<Apache::HTTP_...>.
   
  -Apache::OK, Apache::DECLINED, or Apache::HTTP_...
  +=item since: 1.99_12
   
   =back
   
  +This phase runs before a user is authenticated, so this hook is really
  +to apply additional restrictions independent of a user. It also runs
  +independent of 'C<Require>' directive usage.
   
   
   
   
  -=head2 C<run_auth_checker>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -This hook is used to check to see if the resource being requested is
  -available for the authenticated user (r-E<gt>user and
  -r-E<gt>ap_auth_type).  It runs after the access_checker and
  -check_user_id hooks. Note that it will *only* be called if Apache
  -determines that access control has been applied to this resource
  -(through a 'Require' directive).
   
  -  $ret = $r->run_auth_checker();
  +=head2 C<run_auth_checker>
   
  -=over 4
  +Run the
  +L<authentication|docs::2.0::user::handlers::http/PerlAuthenHandler>
  +phase.
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +  $rc = $r->run_auth_checker();
   
  -the current request
  +=over 4
   
  -=item ret: C<$ret> (integer)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -Apache::OK, Apache::DECLINED, or Apache::HTTP_...
  +the current request
   
  -=back
  +=item ret: C<$rc> ( integer )
   
  +The status of the current phase run: C<Apache::OK>,
  +C<Apache::DECLINED>, C<Apache::HTTP_...>.
   
  +=item since: 1.99_12
   
  +=back
   
  +This phase is used to check to see if the resource being requested is
  +available for the authenticated user (C<$r-E<gt>user> and
  +C<$r-E<gt>ap_auth_type>).
   
  -=head2 C<run_check_user_id>
  +It runs after the L<access_checker|/C_run_access_checker_> and
  +L<check_user_id|/C_run_auth_checker_> hooks.
   
  -META: Autogenerated - needs to be reviewed/completed
  +Note that it will only be called if Apache determines that access
  +control has been applied to this resource (through a 'C<Require>'
  +directive).
   
  -This hook is used to analyze the request headers, authenticate the
  -user, and set the user information in the request record (r-E<gt>user
  -and r-E<gt>ap_auth_type). This hook is only run when Apache determines
  -that authentication/authorization is required for this resource (as
  -determined by the 'Require' directive). It runs after the
  -access_checker hook, and before the auth_checker hook.
   
  -  $ret = $r->run_check_user_id();
   
  -=over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
   
  -The current request
   
  -=item ret: C<$ret> (integer)
   
  -Apache::OK, Apache::DECLINED, or Apache::HTTP_...
  +=head2 C<run_check_user_id>
   
  -=back
  +Run the
  +L<authorization|docs::2.0::user::handlers::http/PerlAuthzHandler>
  +phase.
   
  +  $rc = $r->run_check_user_id();
   
  +=over 4
   
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  +The current request
   
  -=head2 C<run_create_request>
  +=item ret: C<$rc> ( integer )
   
  -META: Autogenerated - needs to be reviewed/completed
  +The status of the current phase run: C<Apache::OK>,
  +C<Apache::DECLINED>, C<Apache::HTTP_...>.
   
  -Gives modules a chance to create their request_config entry when the
  -request is created.
  +=item since: 1.99_12
   
  -  $ret = $r->run_create_request();
  +=back
   
  -=over 4
  +This hook is used to analyze the request headers, authenticate the
  +user, and set the user information in the request record
  +(C<$r-E<gt>user> and C<$r-E<gt>ap_auth_type>).
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +This hook is only run when Apache determines that
  +authentication/authorization is required for this resource (as
  +determined by the 'C<Require>' directive).
   
  -The current request
  +It runs after the L<access_checker|/C_run_access_checker_> hook, and
  +before the L<auth_checker|/C_run_auth_checker_> hook.
   
  -=item ret: C<$ret> (integer)
   
  -Apache::OK, Apache::DECLINED, or Apache::HTTP_...
   
  -=back
   
   
   
  @@ -191,69 +309,90 @@
   
   =head2 C<run_fixups>
   
  -META: Autogenerated - needs to be reviewed/completed
  -
  -Allows modules to perform module-specific fixing of header fields.  This
  -is invoked just before any content-handler
  +Run the L<fixup|docs::2.0::user::handlers::http/PerlFixupHandler>
  +phase.
   
  -  $ret = $r->run_fixups();
  +  $rc = $r->run_fixups();
   
   =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 ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
   
  -Apache::OK, Apache::DECLINED, or Apache::HTTP_...
  +The status of the current phase run: C<Apache::OK>,
  +C<Apache::DECLINED>, C<Apache::HTTP_...>.
  +
  +=item since: 1.99_12
   
   =back
   
  +This phase allows modules to perform module-specific fixing of HTTP
  +header fields.  This is invoked just before the
  +L<response|docs::2.0::user::handlers::http/PerlResponseHandler> phase.
  +
   
   
   
   
  -=head2 C<run_handler>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=head2 C<run_handler>
   
  -Run the handler functions for each module
  +Run the
  +L<response|docs::2.0::user::handlers::http/PerlResponseHandler> phase.
   
  -  $ret = $r->run_handler();
  +  $rc = $r->run_handler();
   
   =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 request_rec
   
  -=item ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
  +
  +The status of the current phase run: C<Apache::OK>,
  +C<Apache::DECLINED>, C<Apache::HTTP_...>.
   
  +=item since: 1.99_12
   
   =back
   
  -non-wildcard handlers should HOOK_MIDDLE, wildcard HOOK_LAST
  +C<run_handler()> is called internally by
  +C<L<invoke_handler()|/C_invoke_handler_>>. Use C<run_handler()> only
  +if you want to bypass the extra functionality provided by
  +C<L<invoke_handler()|/C_invoke_handler_>>.
   
   
   
  -=head2 C<run_header_parser>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Run the header parser functions for each module
   
  -  $ret = $r->run_header_parser();
  +
  +
  +=head2 C<run_header_parser>
  +
  +Run the L<header
  +parser|docs::2.0::user::handlers::http/PerlHeaderParserHandler> phase.
  +
  +  $rc = $r->run_header_parser();
   
   =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 ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
   
  -Apache::OK or Apache::DECLINED
  +C<Apache::OK> or C<Apache::DECLINED>.
  +
  +=item since: 1.99_12
   
   =back
   
  @@ -263,134 +402,167 @@
   
   =head2 C<run_log_transaction>
   
  -META: Autogenerated - needs to be reviewed/completed
  -
  -This hook allows modules to perform any module-specific logging activities
  -over and above the normal server things.
  +Run the L<logging|docs::2.0::user::handlers::http/PerlLogHandler>
  +phase.
   
  -  $ret = $r->run_log_transaction();
  +  $rc = $r->run_log_transaction();
   
   =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 ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
  +
  +The status of the current phase run: C<Apache::OK>,
  +C<Apache::DECLINED>, C<Apache::HTTP_...>
   
  -Apache::OK, Apache::DECLINED, or Apache::HTTP_...
  +=item since: 1.99_12
   
   =back
   
  +This hook allows modules to perform any module-specific logging
  +activities over and above the normal server things.
  +
   
   
   
   
  -=head2 C<run_map_to_storage>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=head2 C<run_map_to_storage>
   
  -This hook allow modules to set the per_dir_config based on their own
  -context (such as E<lt>ProxyE<gt> sections) and responds to contextless
  -requests such as TRACE that need no security or filesystem mapping.
  -based on the filesystem.
  +Run the
  +L<map_to_storage|docs::2.0::user::handlers::http/PerlMapToStorageHandler>
  +phase.
   
  -  $ret = $r->run_map_to_storage();
  +  $rc = $r->run_map_to_storage();
   
   =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 ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
  +
  +C<Apache::DONE> (or C<Apache::HTTP_*>) if this contextless request was
  +just fulfilled (such as C<TRACE>), C<Apache::OK> if this is not a
  +file, and C<Apache::DECLINED> if this is a file.  The core
  +map_to_storage (C<Apache::HOOK_RUN_LAST>) will C<directory_walk()> and
  +C<file_walk()> the C<$r-E<gt>filename> (all internal C functions).
   
  -Apache::DONE (or Apache::HTTP_) if this contextless request was just
  -fulfilled (such as TRACE), OK if this is not a file, and
  -Apache::DECLINED if this is a file.  The core map_to_storage
  -(HOOK_RUN_LAST) will directory_walk and file_walk the r-E<gt>filename.
  +=item since: 1.99_12
   
   =back
   
  +This phase allows modules to set the per_dir_config based on their own
  +context (such as C<E<lt>ProxyE<gt>> sections) and responds to
  +contextless requests such as C<TRACE> that need no security or
  +filesystem mapping based on the filesystem.
  +
  +
   
   
   
   
   =head2 C<run_post_read_request>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -post_read_request --- run right after read_request or
  -internal_redirect, and not run during any subrequests.  This hook
  -allows modules to affect the request immediately after the request has
  -been read, and before any other phases have been processes.  This
  -allows modules to make decisions based upon the input header fields
  +Run the
  +L<post_read_request|docs::2.0::user::handlers::http/PerlPostReadRequestHandler>
  +phase.
   
  -  $ret = $r->run_post_read_request();
  +  $rc = $r->run_post_read_request();
   
   =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 ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
  +
  +The status of the current phase run: C<Apache::OK> or
  +C<Apache::DECLINED>.
   
  -Apache::OK or Apache::DECLINED
  +=item since: 1.99_12
   
   =back
   
  +This phase is run right after C<read_request()> or
  +C<internal_redirect()>, and not run during any subrequests.  This hook
  +allows modules to affect the request immediately after the request has
  +been read, and before any other phases have been processes.  This
  +allows modules to make decisions based upon the input header fields
  +
   
   
   
   
   =head2 C<run_translate_name>
   
  -META: Autogenerated - needs to be reviewed/completed
  +Run the L<translate|docs::2.0::user::handlers::http/PerlTransHandler>
  +phase.
   
  -This hook allow modules an opportunity to translate the URI into an
  -actual filename.  If no modules do anything special, the server's
  -default rules will be followed.
  -
  -  $ret = $r->run_translate_name();
  +  $rc = $r->run_translate_name();
   
   =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 ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
  +
  +The status of the current phase run: C<Apache::OK>,
  +C<Apache::DECLINED>, C<Apache::HTTP_...>.
   
  -Apache::OK, Apache::DECLINED, or Apache::HTTP_...
  +=item since: 1.99_12
   
   =back
   
  +This phase gives modules an opportunity to translate the URI into an
  +actual filename.  If no modules do anything special, the server's
  +default rules will be applied.
  +
   
   
   
   
   =head2 C<run_type_checker>
   
  -META: Autogenerated - needs to be reviewed/completed
  +Run the
  +L<type_checker|docs::2.0::user::handlers::http/PerlTypeHandler> phase.
   
  -This routine is called to determine and/or set the various document
  -type information bits, like Content-type (via r-E<gt>content_type),
  -language, etc.
  -
  -  $ret = $r->run_type_checker();
  +  $rc = $r->run_type_checker();
   
   =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 ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
  +
  +The status of the current phase run: C<Apache::OK>,
  +C<Apache::DECLINED>, C<Apache::HTTP_...>.
   
  -Apache::OK, Apache::DECLINED, or Apache::HTTP_...
  +=item since: 1.99_12
   
   =back
  +
  +This phase is used to determine and/or set the various document type
  +information bits, like C<Content-type> (via C<$r-E<gt>content_type>),
  +language, etc.
  +
  +
  +
   
   
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message