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/user/handlers intro.pod
Date Wed, 26 Nov 2003 07:55:48 GMT
stas        2003/11/25 23:55:48

  Modified:    src/docs/2.0/user/handlers intro.pod
  Log:
  explain the difference between Handler Return Values
  
  Revision  Changes    Path
  1.14      +56 -8     modperl-docs/src/docs/2.0/user/handlers/intro.pod
  
  Index: intro.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/intro.pod,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -u -r1.13 -r1.14
  --- intro.pod	14 Oct 2003 18:36:56 -0000	1.13
  +++ intro.pod	26 Nov 2003 07:55:48 -0000	1.14
  @@ -68,6 +68,59 @@
   
   
   
  +
  +
  +=head1 Handler Return Values
  +
  +Different handler groups are supposed to return different values. The
  +only value that can be returned by all handlers is C<Apache::OK>,
  +which tells Apache that the handler has successfully finished it's
  +execution.
  +
  +C<Apache::DECLINED> is another return value that indicates success,
  +but it's only relevant for
  +L<phases|docs::2.0::user::handlers::intro/Single_Phase_s_Multiple_Handlers_Behavior>
  +of type C<L<RUN_FIRST|/RUN_FIRST>>
  +
  +L<HTTP handlers|docs::2.0::user::handlers::http> may also return
  +C<Apache::DONE> which tells Apache to stop the normal L<HTTP request
  +cycle|docs::2.0::user::handlers::http/HTTP_Request_Cycle_Phases> and
  +fastforward to the
  +C<L<PerlLogHandler|docs::2.0::user::handlers::http/PerlLogHandler>>,
  +followed by
  +C<L<PerlCleanupHandler|docs::2.0::user::handlers::http/PerlCleanupHandler>>.
  +L<HTTP handlers|docs::2.0::user::handlers::http> may return any HTTP
  +status, which similarly to C<Apache::DONE> will cause an abort of the
  +request cycle, by also will be interpreted as an error. Therefore you
  +don't want to return C<Apache::HTTP_OK> from your HTTP response
  +handler, but C<Apache::OK>. If you want to set the status for the HTTP
  +response, use the C<$r-E<gt>status()> method.
  +
  +L<Filter handlers|docs::2.0::user::handlers::filters> return
  +C<Apache::OK> to indicate that the filter has successfully
  +finished. If the return value is C<Apache::DECLINED>, mod_perl will
  +read and forward the data on behalf of the filter. Please notice that
  +this feature is specific to mod_perl. If there is some problem with
  +obtaining or sending the bucket brigades, or the buckets in it,
  +filters need to return the error returned by the method that tried to
  +manipulate the bucket brigade or the bucket. Normally it'd be an
  +C<L<APR::|docs::2.0::api::APR::Const>> constant.
  +
  +L<Protocol handler|docs::2.0::user::handlers::protocols> return values
  +aren't really handled by Apache, the protocol handler is supposed to
  +take care of any errors by itself. The only special case is the
  +C<L<PerlPreConnectionHandler|docs::2.0::user::handlers::protocols/PerlPreConnectionHandler>>
  +handler, which, if returning anything but C<Apache::OK>, will prevent
  +from
  +C<L<PerlConnectionHandler|docs::2.0::user::handlers::protocols/PerlConnectionHandler>>
  +to be
  +run. C<L<PerlPreConnectionHandler|docs::2.0::user::handlers::protocols/PerlPreConnectionHandler>>
  +handlers should always return C<Apache::OK>.
  +
  +
  +
  +
  +
   =head1 mod_perl Handlers Categories
   
   The mod_perl handlers can be divided by their application scope in
  @@ -271,15 +324,13 @@
   
   And here is the description of the possible types:
   
  -=over
  -
  -=item * VOID
  +=head2 C<VOID>
   
   Handlers of the type C<VOID> will be I<all> executed in the order they
   have been registered disregarding their return values. Though in
   mod_perl they are expected to return C<Apache::OK>.
   
  -=item * RUN_FIRST
  +=head2 C<RUN_FIRST>
   
   Handlers of the type C<RUN_FIRST> will be executed in the order they
   have been registered until the first handler that returns something
  @@ -288,21 +339,18 @@
   return value is C<Apache::OK> the next phase will start. In all other
   cases the execution will be aborted.
   
  -=item * RUN_ALL
  +=head2 C<RUN_ALL>
   
   Handlers of the type C<RUN_ALL> will be executed in the order they
   have been registered until the first handler that returns something
   other than C<Apache::OK> or C<Apache::DECLINED>.
   
  -=back
   
   For C API declarations see I<include/ap_config.h>, which includes
   other types which aren't exposed by mod_perl handlers.
   
   Also see L<mod_perl Directives Argument Types and Allowed
   Location|docs::2.0::user::config::config/mod_perl_Directives_Argument_Types_and_Allowed_Location>
  -
  -
   
   
   
  
  
  

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