perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pgollu...@apache.org
Subject svn commit: r712938 - in /perl/modperl/docs/trunk/src/docs/2.0/user/handlers: filters.pod http.pod protocols.pod server.pod
Date Tue, 11 Nov 2008 04:35:08 GMT
Author: pgollucci
Date: Mon Nov 10 20:35:08 2008
New Revision: 712938

URL: http://svn.apache.org/viewvc?rev=712938&view=rev
Log:
Clarify filter arguments
Add some more cross linking
Correct some typos

Submitted by: Ian Goodacre <Ian.Goodacre@xtra.co.nz>


Modified:
    perl/modperl/docs/trunk/src/docs/2.0/user/handlers/filters.pod
    perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod
    perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod
    perl/modperl/docs/trunk/src/docs/2.0/user/handlers/server.pod

Modified: perl/modperl/docs/trunk/src/docs/2.0/user/handlers/filters.pod
URL: http://svn.apache.org/viewvc/perl/modperl/docs/trunk/src/docs/2.0/user/handlers/filters.pod?rev=712938&r1=712937&r2=712938&view=diff
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/handlers/filters.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/handlers/filters.pod Mon Nov 10 20:35:08 2008
@@ -711,6 +711,22 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
+B<Arguments>
+
+C<PerlInputFilterHander> handlers are passed two arguments:
+an C<L<Apache2::Filter>> object; and
+an C<L<APR::Brigade>> object;
+
+See the examples that follow in this chapter for further explanation.
+
+B<Return>
+
+Filters are expected to return C<L<Apache2::Const::OK|Apache2::Const>>
+or C<L<Apache2::Const::DECLINED|Apache2::Const>>.
+See the examples that follow in this chapter for further explanation.
+
+B<Examples>
+
 C<PerlInputFilterHandler> handlers are automatically
 C<L<AutoLoad|docs::2.0::user::config::config/C_AutoLoad_>>ed, since
 they need to be compiled before L<the filter
@@ -742,14 +758,25 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
-Similar to the C<PerlInputFilterHandler> handlers,
-C<PerlOutputFilterHandler> handlers are automatically
-C<AutoLoad>ed.
+B<Arguments>
+
+C<PerlOutputFilterHander> handlers are passed five arguments:
+an C<L<Apache2::Filter>> object;
+an C<L<APR::Brigade>> object;
+an  C<L<Apache2::Const :input_mode|docs::2.0::api::Apache2::Const/toc_C__input_mode_>>
constant;
+an C<L<APR::Const :read_type|docs::2.0::api::APR::Const/toc_C__read_type_>> constant;
and
+the number of bytes to read.
+
+See the examples that follow in this chapter for further explanation.
+
+B<Return>
+
+B<Examples>
 
 The following sections include several examples that use the
 C<PerlOutputFilterHandler> handler.
 
-Similar to C<L<PerlInputFilterHandler|/C_PerlInputFilterHandler_>>
+Similar to C<L<PerlInputFilterHandler|/C_PerlInputFilterHandler_>>,
 C<PerlOutputFilterHandler> handlers are automatically
 C<L<AutoLoad|docs::2.0::user::config::config/C_AutoLoad_>>ed.
 

Modified: perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod
URL: http://svn.apache.org/viewvc/perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod?rev=712938&r1=712937&r2=712938&view=diff
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod Mon Nov 10 20:35:08 2008
@@ -170,6 +170,17 @@
 phase the request has not yet been associated with a particular
 filename or directory.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 Now, let's look at an example. Consider the following registry script:
 
   #file:touch.pl
@@ -271,6 +282,17 @@
 phase the request has not yet been associated with a particular
 filename or directory.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 There are many useful things that can be performed at this
 stage. Let's look at the example handler that rewrites request URIs,
 similar to what mod_rewrite does. For example, if your web-site was
@@ -344,6 +366,17 @@
 phase the request has not yet been associated with a particular
 filename or directory.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 For example if you don't want Apache to try to attempt to translate
 URI into a filename, just add a handler:
 
@@ -440,6 +473,17 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 This phase is very similar to
 C<L<PerlPostReadRequestHandler|/PerlPostReadRequestHandler>>, with the
 only difference that it's run after the request has been mapped to the
@@ -687,6 +731,17 @@
 This phase is of type
 C<L<RUN_ALL|docs::2.0::user::handlers::intro/item_RUN_ALL>>.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 The best example here would be to use
 C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>> which takes the
 benefit of this directive. Usually
@@ -736,6 +791,17 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 The concept behind access checker handler is very simple, return
 C<Apache2::Const::FORBIDDEN> if the access is not allowed, otherwise
 return C<Apache2::Const::OK>.
@@ -821,6 +887,17 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 The following handler authenticates users by asking for a username and
 a password and lets them in only if the length of a string made from
 the supplied username and password and a single space equals to the
@@ -967,6 +1044,17 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 Here is the C<MyApache2::SecretResourceAuthz> handler which grants
 access to certain resources only to certain users who have already
 properly authenticated:
@@ -1074,6 +1162,17 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 The most important thing to remember when overriding the default
 I<type_checker> handler, which is usually the mod_mime handler, is
 that you have to set the handler that will take care of the response
@@ -1117,6 +1216,17 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 The following fixup handler example tells Apache at run time which
 handler and callback should be used to process the request based on
 the file extension of the request's URI.
@@ -1252,6 +1362,17 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 Most of the C<Apache::> modules on CPAN are dealing with this
 phase. In fact most of the developers spend the majority of their time
 working on handlers that generate response content.
@@ -1331,6 +1452,17 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 Imagine a situation where you have to log requests into individual
 files, one per user. Assuming that all requests start with
 I</~username/>, so it's easy to categorize requests by the
@@ -1457,6 +1589,17 @@
 The handler's configuration scope is
 C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
 
+B<Arguments>
+
+See the L<HTTP Request Handler Skeleton|docs::2.0::user::handlers::http/HTTP_Request_Handler_Skeleton>
for a description of handler arguments.
+
+B<Return>
+
+See L<Stacked Handlers|docs::2.0::user::handlers::intro/Stacked_Handlers> 
+for a description of handler return codes.
+
+B<Examples>
+
 There are two ways to register and run cleanup handlers:
 
 =over

Modified: perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod
URL: http://svn.apache.org/viewvc/perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod?rev=712938&r1=712937&r2=712938&view=diff
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod Mon Nov 10 20:35:08 2008
@@ -86,7 +86,9 @@
 C<L<SRV|docs::2.0::user::config::config/item_SRV>>, because it's not
 known yet which resource the request will be mapped to.
 
-A I<pre_connection> handler accepts a connection record at its argument:
+B<Arguments>
+
+A I<pre_connection> handler is passed a C<L<connection record|Apache2::Connection>>
as its argument:
 
   sub handler {
       my $c = shift;
@@ -95,7 +97,15 @@
   }
 
 [META: There is another argument passed (the actual client socket), but
-it currently an undef]
+it is currently an undef]
+
+B<Return>
+
+The handler should return C<L<Apache2::Const::OK|Apache2::Const>>
+if it completes successfully or C<L<Apache2::Const::FORBIDDEN|Apache2::Const>>
+if the request is forbidden.
+
+B<Examples>
 
 Here is a useful I<pre_connection> phase example: provide a facility
 to block remote clients by their IP, before too many resources were
@@ -159,9 +169,21 @@
 way to run protocol servers different than the core HTTP is inside
 dedicated virtual hosts.
 
-A I<process_connection> handler accepts a connection record object as
-its only argument, a socket object can be retrieved from the
-connection record object. Here is a simplified handler skeleton:
+B<Arguments>
+
+A I<process_connection> handler is passed a
+C<L<connection record|Apache2::Connection>> object as its only argument.
+
+A socket object can be retrieved from the connection record object.
+
+B<Return>
+
+The handler should return C<L<Apache2::Const::OK|Apache2::Const>>
+if it completes successfully.
+
+B<Examples>
+
+Here is a simplified handler skeleton:
 
   sub handler {
       my ($c) = @_;

Modified: perl/modperl/docs/trunk/src/docs/2.0/user/handlers/server.pod
URL: http://svn.apache.org/viewvc/perl/modperl/docs/trunk/src/docs/2.0/user/handlers/server.pod?rev=712938&r1=712937&r2=712938&view=diff
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/handlers/server.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/handlers/server.pod Mon Nov 10 20:35:08 2008
@@ -224,11 +224,48 @@
 The handler's configuration scope is
 C<L<SRV|docs::2.0::user::config::config/item_SRV>>.
 
-As we have seen in the
-C<L<MyApache2::StartupLog::open_logs|/Startup_Phases_Demonstration_Module>>
-handler, the I<open_logs> phase handlers accept four arguments: the
-configuration pool, the logging stream pool, the temporary pool and
-the main server object:
+B<Arguments>
+
+The I<open_logs> handler is passed four arguments: the configuration pool,
+the logging stream pool, the temporary pool and the main server object.
+
+The pool arguments are:
+
+=over
+
+=item *
+
+C<$conf_pool> is the main process sub-pool, therefore its life-span
+is the same as the main process's one. The main process is a sub-pool
+of the global pool.
+
+=item *
+
+C<$log_pool> is a global pool's sub-pool, therefore its life-span is
+the same as the Apache program's one.
+
+META: what is it good for if it lives the same life as conf pool?
+
+=item *
+
+C<$temp_pool> is a C<$conf_pool> subpool, created before the config
+phase, lives through the open_logs phase and get destroyed after the
+post_config phase. So you will want to use that pool for doing
+anything that can be discarded before the requests processing starts.
+
+=back
+
+All three pool arguments are instances of C<L<APR::Pool>>.
+
+C<$s> is the base server object (an instance of C<L<Apache2::ServerRec>>).
+
+B<Return>
+
+The handler should return C<L<Apache2::Const::OK|Apache2::Const>>
+if it completes successfully.
+
+
+B<Examples>
 
   sub open_logs {
       my ($conf_pool, $log_pool, $temp_pool, $s) = @_;
@@ -268,38 +305,6 @@
       return Apache2::Const::OK;
   }
 
-C<$s> is the base server object.
-
-The pool arguments in this phase and
-C<L<PerlPostConfigHandler|/C_PerlPostConfigHandler_>> are:
-
-=over
-
-=item *
-
-C<$conf_pool> is the main process sub-pool, therefore its life-span
-is the same as the main process's one. The main process is a sub-pool
-of the global pool.
-
-=item *
-
-C<$log_pool> is a global pool's sub-pool, therefore its life-span is
-the same as the Apache program's one.
-
-META: what is it good for if it lives the same life as conf pool?
-
-=item *
-
-C<$temp_pool> is a C<$conf_pool> subpool, created before the config
-phase, lives through the open_logs phase and get destroyed after the
-post_config phase. So you will want to use that pool for doing
-anything that can be discarded before the requests processing starts.
-
-=back
-
-
-
-
 
 
 
@@ -321,6 +326,17 @@
 The handler's configuration scope is
 C<L<SRV|docs::2.0::user::config::config/item_SRV>>.
 
+B<Arguments>
+
+Arguments are exactly as for C<L<PerlOpenLogsHandler|/C_PerlOpenLogsHandler_>>.
+
+B<Return>
+
+If the handler completes successfully it should return C<L<Apache2::Const::OK|Apache2::Const>>.
+
+
+B<Examples>
+
 In our C<L<MyApache2::StartupLog|/Startup_Phases_Demonstration_Module>>
 example we used the I<post_config()> handler:
 
@@ -373,6 +389,17 @@
 The handler's configuration scope is
 C<L<SRV|docs::2.0::user::config::config/item_SRV>>.
 
+B<Arguments>
+
+The I<child_init()> handler is passed two arguments: the child process
+pool (C<L<APR::Pool>>) and the server object (C<L<Apache2::ServerRec>>).
+
+B<Return>
+
+If the handler completes successfully it should return C<L<Apache2::Const::OK|Apache2::Const>>.
+
+B<Examples>
+
 In our C<L<MyApache2::StartupLog|/Startup_Phases_Demonstration_Module>>
 example we used the I<child_init()> handler:
 
@@ -382,9 +409,7 @@
       return Apache2::Const::OK;
   }
 
-The I<child_init()> handler accepts two arguments: the child process
-pool and the server object. The example handler logs the pid of the
-child process it's run in and returns.
+The example handler logs the pid of the child process it's run in and returns.
 
 As you've seen in the example this handler is configured by adding to
 I<httpd.conf>:
@@ -409,6 +434,17 @@
 The handler's configuration scope is
 C<L<SRV|docs::2.0::user::config::config/item_SRV>>.
 
+B<Arguments>
+
+The I<child_exit()> handler accepts two arguments: the child process
+pool (C<L<APR::Pool>>) and the server object (C<L<Apache2::ServerRec>>).
+
+B<Return>
+
+If the handler completes successfully it should return C<L<Apache2::Const::OK|Apache2::Const>>.
+
+B<Examples>
+
 In our C<L<MyApache2::StartupLog|/Startup_Phases_Demonstration_Module>>
 example we used the I<child_exit()> handler:
 
@@ -418,8 +454,7 @@
       return Apache2::Const::OK;
   }
 
-The I<child_exit()> handler accepts two arguments: the child process
-pool and the server object. The example handler logs the pid of the
+The example handler logs the pid of the
 child process it's run in and returns.
 
 As you've seen in the example this handler is configured by adding to



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