stas 2004/07/04 21:37:20
Modified: src/docs/2.0/api/Apache RequestUtil.pod
src/docs/2.0/user/handlers http.pod
src/docs/2.0/user/porting compat.pod
Log:
- finish Apache::RequestUtil
- update related manpages
Revision Changes Path
1.20 +249 -35 modperl-docs/src/docs/2.0/api/Apache/RequestUtil.pod
Index: RequestUtil.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/RequestUtil.pod,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -u -r1.19 -r1.20
--- RequestUtil.pod 5 Jul 2004 01:40:31 -0000 1.19
+++ RequestUtil.pod 5 Jul 2004 04:37:20 -0000 1.20
@@ -9,10 +9,75 @@
use Apache::RequestUtil ();
+ # add httpd config dynamically
+ $r->add_config(['require valid-user']);
+
+ # dump the request object as a string
+ print $r->as_string();
+
+ # default content_type
+ $content_type = $r->default_type();
+
+ # get PerlSetVar/PerlAddVar values
+ @values = $r->dir_config($key);
+
+ # get server docroot
+ $docroot = $r->document_root();
+
+ # what are the registered perl handlers for a given phase
+ my @handlers = @{ $r->get_handlers('PerlResponseHandler') || [] };
+
+ # push a new handler for a given phase
+ $r->push_handlers(PerlCleanupHandler => \&handler);
+
+ # set handlers for a given phase (resetting previous values)
+ $r->set_handlers(PerlCleanupHandler => []);
+
+ # what's the request body limit
+ $limit = $r->get_limit_req_body();
+
+ # server and port names
+ $server = $r->get_server_name();
+ $port = $r->get_server_port();
+
+ # what string Apache is going to send for a given status code
+ $status_line = Apache::RequestUtil::get_status_line(404);
+
+ # are we in the main request?
+ $is_initial = $r->is_initial_req();
+
# directory level PerlOptions flags lookup
$r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');
+
+ # current <Location> value
+ $location = $r->location();
+
+ # merge a <Location> container in a request object
+ $r->location_merge($location);
+
+ # extend HTTP to support a new method
+ Apache::RequestUtil::method_register($pool, $methname);
+
+ # create a new Apache::RequestRec object
+ $r = Apache::RequestRec->new($c);
+
+ # tell the client not to cache the response
+ $r->no_cache($boolean);
+
+ # share perl objects like $r->notes
+ $r->pnotes($key => [$obj1, $obj2]);
+
+ # get the global request object (requires PerlOptions +GlobalRequest)
+ $r = Apache->request;
+
+ # insert auth credentials into the request as if the client did that
+ $r->set_basic_credentials($username, $password);
+
+ # slurp the contents of $r->filename
+ $content = $r->slurp_filename($tainted);
+
+
-META: to be completed
@@ -374,7 +439,7 @@
=over 4
-=item obj: C<$status> (integer)
+=item arg1: C<$status> (integer)
The HTTP status code
@@ -489,6 +554,9 @@
=head2 C<location_merge>
+Merge a given C<E<lt>LocationE<lt>> container into the current request
+object:
+
$ret = $r->location_merge($location);
=over 4
@@ -498,86 +566,164 @@
=item arg1: C<$location> ( string )
-=item ret: C<$ret> (integer)
+The argument in a C<E<lt>LocationE<lt>> section. For example to merge
+a container:
+
+ <Location /foo>
+ ...
+ </Location>
+
+that argument will be I</foo>
+
+=item ret: C<$ret> ( true/false )
+
+a true value if the merge was successful (i.e. the request
+C<$location> match was found), otherwise false.
=item since: 1.99_10
=back
+Useful for insertion of a configuration section into a custom
+C<Apache::RequestRec> object, created via the
+C<Apache::RequestRec-E<gt>new()> method. See for example the L<Command
+Server protocol
+example|docs::2.0::user::handlers::protocols/Command_Server>.
+
+
+
-=head2 C<method_register>
-META: Autogenerated - needs to be reviewed/completed
+
+=head2 C<method_register>
Register a new request method, and return the offset that will be
associated with that method.
- $ret = $p->method_register($methname);
+ $offset = Apache::RequestUtil::method_register($pool, $methname);
=over 4
-=item obj: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>> )
+=item arg1: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>> )
+
+The pool to create registered method numbers from. Use a long lived
+pool like:
-The pool to create registered method numbers from.
+ $r->server->process->pconf;
=item arg1: C<$methname> ( string )
-The name of the new method to register.
+The name of the new method to register (in addition to the already
+supported C<GET>, C<HEAD>, etc.)
-=item ret: C<$ret> (integer)
+=item ret: C<$offset> ( integer )
-An int value representing an offset into a bitmask.
+An int value representing an offset into a bitmask. You can probably
+ignore it.
-=item since: 1.99_10
+=item since: 1.99_15
=back
+This method allows you to extend the HTTP protocol to support new
+methods, which fit the HTTP paradigm. Of course you will need to
+write a client that understands that protocol extension. For a good
+example, refer to the C<MyApache::SendEmail> example presented in
+C<L<the PerlHeaderParserHandler
+section|docs::2.0::user::handlers::http/PerlHeaderParserHandler>>,
+which demonstrates how a new method C<EMAIL> is registered and used.
-=head2 C<new>
-META: Autogenerated - needs to be reviewed/completed
- $ret = $r->new(classname, c, base_pool));
+
+=head2 C<new>
+
+Create a new C<Apache::RequestRec> object.
+
+ $r = Apache::RequestRec->new($c);
+ $r = Apache::RequestRec->new($c, $pool);
=over 4
-=item obj: C<$r>
-( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+=item obj: C<Apache::RequestRec>
+( C<L<Apache::RequestRec class name|docs::2.0::api::Apache::RequestRec>> )
+
+=item arg1: C<$c>
+(C<L<Apache::Connection object|docs::2.0::api::Apache::Connection>>)
+
+=item opt arg2: C<$pool>
-=item arg1: C<$flag> (number)
+If no C<$pool> argument is passed, C<$c-E<gt>pool> is used. That means
+that the created C<Apache::RequestRec> object will be valid as long as
+the connection object is valid.
-=item ret: C<$ret> (integer)
+=item ret: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
=item since: 1.99_10
=back
+It's possible to reuse the HTTP framework features outside the
+familiar HTTP request cycle. It's possible to write your own full or
+partial HTTP implementation without needing a running Apache
+server. You will need the C<Apache::RequestRec> object in order to be
+able to reuse the rich functionality supplied via this object.
+
+See for example the L<Command Server protocol
+example|docs::2.0::user::handlers::protocols/Command_Server> which
+reuses HTTP AAA model under non-HTTP protocol.
+
+
+
+
+
-=head2 C<no_cache>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<no_cache>
+Add/remove cache control headers:
- $ret = $r->no_cache($flag);
+ $prev_no_cache = $r->no_cache($boolean);
=over 4
=item obj: C<$r>
( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-=item arg1: C<$flag> (number)
+=item arg1: C<$boolean> ( boolean )
+
+A true value sets the C<no_cache> request record member to a true
+value and inserts:
+
+ Pragma: no-cache
+ Cache-control: no-cache
+
+into the response headers, indicating that the data being returned is
+volatile and the client should not cache it.
+
+A false value unsets the C<no_cache> request record member and the
+mentioned headers if they were previously set.
+
+=item ret: C<$prev_no_cache> ( boolean )
-=item ret: C<$ret> (integer)
+Should you care, the C<no_cache> request record member value prior to
+the change is returned.
=item since: 1.99_10
=back
+This method should be invoked before any response data has been sent
+out.
+
+
+
=head2 C<pnotes>
@@ -617,23 +763,78 @@
=back
-Similar to
-( C<L<Apache::RequestRec
object|docs::2.0::api::Apache::RequestRec/C_notes_>> ),
+This method provides functionality similar to
+(C<L<Apache::RequestRec::notes|docs::2.0::api::Apache::RequestRec/C_notes_>>),
but values can be any Perl variables. That also means that it can be
used only between Perl modules.
The values get reset automatically at the end of each HTTP request.
-META: Examples (t/response/TestModperl/pnotes.pm)
+Examples:
+
+Set a key/value pair:
+
+ $r->pnotes(foo => [1..5]);
+
+Get the value:
+
+ $val = $r->pnotes("foo");
+
+C<$val> now contains an array ref containing 5 elements (C<1..5>).
+
+Now change the existing value:
+
+ $old_val = $r->pnotes(foo => ['a'..'c']);
+ $val = $r->pnotes("foo");
+
+C<$old_val> now contains an array ref with 5 elements (C<1..5>) and
+C<$val> contains an array ref with 3 elements C<'a'>, C<'b'>, C<'c'>.
+
+Alternatively you can access the hash reference with all pnotes
+values:
+
+ $pnotes = $r->pnotes;
+
+Now we can read what's in there for the key I<foo>:
+
+ $val = $pnotes->{foo};
+
+and as before C<$val> still gives us an array ref with 3 elements
+C<'a'>, C<'b'>, C<'c'>.
+
+Now we can add elements to it:
+
+ push @{ $pnotes{foo} }, 'd'..'f';
+
+and we can try to retrieve them using the hash and non-hash API:
+
+ $val1 = $pnotes{foo};
+ $val2 = $r->pnotes("foo");
+
+Both C<$val1> and C<$val2> contain an array ref with 6 elements
+(letters 'a' to 'f').
+
+Finally to reset an entry you could just assign C<undef> as a value:
+
+ $r->pnotes(foo => undef);
+
+but the entry for the key I<foo> still remains with the value
+C<undef>. If you really want to completely remove it, use the hash
+interface:
+
+ delete $r->pnotes->{foo};
+
+
+
=head2 C<request>
-Retrieve the
-( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> ) object
-for the current request.
+Retrieve the ( C<L<Apache::RequestRec
+object|docs::2.0::api::Apache::RequestRec>> ) object for the current
+request.
$r = Apache->request;
@@ -641,9 +842,10 @@
=item obj: C<Apache> (class name)
-The Apache class
+The Apache class name
-=item ret: C<$r> ( C<L<Apache::RequestRec
object|docs::2.0::api::Apache::RequestRec>> )
+=item ret: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
=item since: 1.99_10
@@ -656,6 +858,8 @@
+
+
=head2 C<push_handlers>
Add one or more handlers to a list of handlers to be called for a
@@ -709,11 +913,13 @@
-=head2 C<set_basic_credentials>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<set_basic_credentials>
+Populate the incoming request headers table (C<headers_in>) with
+authentication headers for Basic Authorization as if the client has
+submitted those in first place:
$r->set_basic_credentials($username, $password);
@@ -732,6 +938,14 @@
=back
+See for example the L<Command Server protocol
+example|docs::2.0::user::handlers::protocols/Command_Server> which
+reuses HTTP AAA model under non-HTTP protocol.
+
+
+
+
+
=head2 C<set_handlers>
@@ -805,7 +1019,7 @@
=head2 C<slurp_filename>
-Return a reference to contents of C<$r-E<gt>filename>.
+Slurp the contents of C<$r-E<gt>filename>:
$content = $r->slurp_filename($tainted);
1.39 +15 -5 modperl-docs/src/docs/2.0/user/handlers/http.pod
Index: http.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -u -r1.38 -r1.39
--- http.pod 4 Jul 2004 02:38:15 -0000 1.38
+++ http.pod 5 Jul 2004 04:37:20 -0000 1.39
@@ -444,6 +444,8 @@
use Apache::RequestRec ();
use Apache::RequestIO ();
use Apache::RequestUtil ();
+ use Apache::Server ();
+ use Apache::Process ();
use APR::Table ();
use Apache::Const -compile => qw(DECLINED OK);
@@ -456,7 +458,8 @@
return Apache::DECLINED unless $r->method eq METHOD;
- Apache::method_register($r->pool, METHOD);
+ Apache::RequestUtil::method_register($r->server->process->pconf,
+ METHOD);
$r->handler("perl-script");
$r->push_handlers(PerlResponseHandler => \&send_email_handler);
@@ -531,12 +534,19 @@
return Apache::DECLINED unless $r->method eq METHOD;
Next it tells Apache that this new method is a valid one and that the
-C<perl-script> handler will do the processing. Finally it pushes the
-function C<send_email_handler()> to the C<PerlResponseHandler> list of
-handlers:
+C<perl-script> handler will do the processing.
- Apache::Server::method_register($r->pool, METHOD);
+ Apache::RequestUtil::method_register($r->server->process->pconf,
+ METHOD);
$r->handler("perl-script");
+
+Notice that we use the C<pconf> pool which persists through the server
+life, and not C<$r-E<gt>pool> whose life span will end at the end of
+the request.
+
+Finally it pushes the function C<send_email_handler()> to the
+C<PerlResponseHandler> list of handlers:
+
$r->push_handlers(PerlResponseHandler => \&send_email_handler);
The function terminates the header_parser phase by:
1.54 +1 -0 modperl-docs/src/docs/2.0/user/porting/compat.pod
Index: compat.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/porting/compat.pod,v
retrieving revision 1.53
retrieving revision 1.54
diff -u -u -r1.53 -r1.54
--- compat.pod 4 Jul 2004 17:11:26 -0000 1.53
+++ compat.pod 5 Jul 2004 04:37:20 -0000 1.54
@@ -680,6 +680,7 @@
Though the C function C<modperl_perl_gensym()> is available for XS/C
extensions writers.
+
=head2 C<Apache::log_error()>
C<Apache::log_error()> is not available in mod_perl 2.0 API. You can
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
