pgollucci at apache
Nov 10, 2008, 8:35 PM
Post #1 of 1
(912 views)
Permalink
|
|
svn commit: r712938 - in /perl/modperl/docs/trunk/src/docs/2.0/user/handlers: filters.pod http.pod protocols.pod server.pod
|
|
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[at]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[at]perl.apache.org
For additional commands, e-mail: docs-cvs-help[at]perl.apache.org
|
