stas 2004/08/08 17:26:23
Modified: src/docs/2.0/api/Apache Access.pod Const.pod
Log:
Apache::Access is complete
Revision Changes Path
1.6 +205 -40 modperl-docs/src/docs/2.0/api/Apache/Access.pod
Index: Access.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Access.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -u -r1.5 -r1.6
--- Access.pod 5 Aug 2004 08:36:50 -0000 1.5
+++ Access.pod 9 Aug 2004 00:26:23 -0000 1.6
@@ -10,8 +10,47 @@
=head1 Synopsis
use Apache::Access ();
+
+ # allow only GET method
+ $r->allow_methods(1, qw(GET));
+
+ # Apache Options value
+ $options = $r->allow_options();
+
+ # Apache AllowOverride value
+ $allow_override = $r->allow_overrides();
+
+ # auth name ("foo bar")
+ $auth_name = $r->auth_name();
+
+ # auth type
+ $auth_type = $r->auth_type();
+ $r->auth_type("Digest");
+
+ # Basic authentication process
+ my($rc, $passwd) = $r->get_basic_auth_pw();
+
+ # the login name of the remote user (RFC1413)
+ $remote_logname = $r->get_remote_logname();
+
+ # dynamically figure out which auth has failed
+ $r->note_auth_failure();
+
+ # note Basic auth failure
+ $r->note_basic_auth_failure();
+
+ # note Digest auth failure
+ $r->note_digest_auth_failure();
+
+ # Apache Request value(s)
+ $requires = $r->requires();
+
+ # Apache Satisfy value (as a number)
+ $satisfy = $r->satisfies();
+
+ # check whether some auth is configured
+ $need_auth = $r->some_auth_required();
-META: needs to be completed
@@ -20,10 +59,12 @@
=head1 Description
-C<Apache::Access> provides an additional Perl API for
-C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec|/Description>>
-object. The API provided by this module deals with access,
-authentication and authorization phases.
+The API provided by this module deals with access, authentication and
+authorization phases.
+
+C<Apache::Access> extends
+C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec|/Description>>.
+
@@ -242,6 +283,7 @@
+
=head2 C<get_basic_auth_pw>
Get the password from the request headers
@@ -288,12 +330,9 @@
=head2 C<get_remote_logname>
-META: Autogenerated - needs to be reviewed/completed
+Retrieve the login name of the remote user (RFC1413)
-Retrieve the login name of the remote user. Undef if it could not be
-determined
-
- $ret = $r->get_remote_logname();
+ $remote_logname = $r->get_remote_logname();
=over 4
@@ -302,25 +341,33 @@
The current request
-=item ret: C<$ret> (string)
+=item ret: C<$remote_logname> ( string )
-The user logged in to the client machine
+The username of the user logged in to the client machine, or an empty
+string if it could not be determined via RFC1413, which involves
+querying the client's identd or auth daemon.
=item since: 1.99_12
=back
+Do not confuse this method with
+C<L<$r-E<gt>user|docs::2.0::api::Apache::RequestRec/C_user_>>, which
+provides the username provided by the user during the server
+authentication.
-=head2 C<note_auth_failure>
-META: Autogenerated - needs to be reviewed/completed
+
+
+
+=head2 C<note_auth_failure>
Setup the output headers so that the client knows how to authenticate
-itself the next time, if an authentication request failed. This function
-works for both basic and digest authentication
+itself the next time, if an authentication request failed. This
+function works for both basic and digest authentication
$r->note_auth_failure();
@@ -337,17 +384,24 @@
=back
+This method requires C<AuthType> to be set to C<Basic> or
+C<Digest>. Depending on the setting it'll call either
+C<L<$r-E<gt>note_basic_auth_failure|/C_note_basic_auth_failure_>> or
+C<L<$r-E<gt>note_digest_auth_failure|/C_note_digest_auth_failure_>>.
+
+
-=head2 C<note_basic_auth_failure>
-META: Autogenerated - needs to be reviewed/completed
+
+
+=head2 C<note_basic_auth_failure>
Setup the output headers so that the client knows how to authenticate
-itself the next time, if an authentication request failed. This function
-works only for basic authentication
+itself the next time, if an authentication request failed. This
+function works only for basic authentication
$r->note_basic_auth_failure();
@@ -368,13 +422,15 @@
-=head2 C<note_digest_auth_failure>
-META: Autogenerated - needs to be reviewed/completed
+
+
+
+=head2 C<note_digest_auth_failure>
Setup the output headers so that the client knows how to authenticate
-itself the next time, if an authentication request failed. This function
-works only for digest authentication
+itself the next time, if an authentication request failed. This
+function works only for digest authentication.
$r->note_digest_auth_failure();
@@ -395,20 +451,126 @@
+
+
=head2 C<requires>
+Retrieve information about all of the requires directives for this request
+
+ $requires = $r->requires
+
+=over 4
+
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+The current request
+=item ret: C<$requires> ( ARRAY ref )
+Returns an array reference of hash references, containing information
+related to the C<require> directive.
+=item since: 1.99_12
-=head2 C<satisfies>
+=back
+
+This is normally used for access control.
+
+For example if the configuration had the following require directives:
+
+ Require user goo bar
+ Require group bar tar
+
+this method will return the following datastructure:
+
+ [
+ {
+ 'method_mask' => -1,
+ 'requirement' => 'user goo bar'
+ },
+ {
+ 'method_mask' => -1,
+ 'requirement' => 'group bar tar'
+ }
+ ];
+
+The I<requirement> field is what was passed to the C<Require>
+directive. The I<method_mask> field is a bitmask which can be
+modified by the C<Limit> directive, but normally it can be safely
+ignored as it's mostly used internally. For example if the
+configuration was:
+
+ Require user goo bar
+ Require group bar tar
+ <Limit POST>
+ Require valid-user
+ </Limit>
+
+and the request method was C<POST>, C<$r-E<gt>requires> will return:
+
+ [
+ {
+ 'method_mask' => -1,
+ 'requirement' => 'user goo bar'
+ },
+ {
+ 'method_mask' => -1,
+ 'requirement' => 'group bar tar'
+ }
+ {
+ 'method_mask' => 4,
+ 'requirement' => 'valid-user'
+ }
+ ];
+
+But if the request method was C<GET>, it will return only:
+
+ [
+ {
+ 'method_mask' => -1,
+ 'requirement' => 'user goo bar'
+ },
+ {
+ 'method_mask' => -1,
+ 'requirement' => 'group bar tar'
+ }
+ ];
-META: Autogenerated - needs to be reviewed/completed
+As you can see Apache gives you the requirements relevant for the
+current request, so the I<method_mask> is irrelevant.
-How the requires lines must be met.
+It is also a good time to remind that in the general case, access
+control directives should not be placed within a E<lt>LimitE<gt>
+section. Refer to the Apache documentation for more information.
- $ret = $r->satisfies();
+Using the same configuration and assuming that the request was of type
+POST, the following code inside an Auth handler:
+
+ my %require =
+ map { my($k, $v) = split /\s+/, $_->{requirement}, 2; ($k, $v||'') }
+ @{ $r->requires };
+
+will populate C<%require> with the following pairs:
+
+ 'group' => 'bar tar',
+ 'user' => 'goo bar',
+ 'valid-user' => '',
+
+
+
+
+
+
+
+
+
+=head2 C<satisfies>
+
+How the requires lines must be met. What's the applicable value of the
+C<Satisfy> directive:
+
+ $satisfy = $r->satisfies();
=over 4
@@ -417,30 +579,33 @@
The current request
-=item ret: C<$ret> (integer)
+=item ret: C<$satisfy> ( integer )
-How the requirements must be met. One of:
+How the requirements must be met. One of the C<L<Apache::Const
+:satisfy constants|docs::2.0::api::Apache::Const/C__satisfy_>>:
- Apache::SATISFY_ANY -- any of the requirements must be met.
- Apache::SATISFY_ALL -- all of the requirements must be met.
- Apache::SATISFY_NOSPEC -- There are no applicable satisfy lines
+C<L<Apache::SATISFY_ANY|docs::2.0::api::Apache::Const/C_Apache::SATISFY_ANY_>>,
+C<L<Apache::SATISFY_ALL|docs::2.0::api::Apache::Const/C_Apache::SATISFY_ALL_>>
+and
+C<L<Apache::SATISFY_NOSPEC|docs::2.0::api::Apache::Const/C_Apache::SATISFY_NOSPEC_>>.
=item since: 1.99_12
=back
+See the documentation for the C<Satisfy> directive in the Apache
+documentation.
-=head2 C<some_auth_required>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<some_auth_required>
-Can be used within any handler to determine if any authentication
-is required for the current request
+Can be used within any handler to determine if any authentication is
+required for the current request:
- $ret = $r->some_auth_required();
+ $need_auth = $r->some_auth_required();
=over 4
@@ -449,9 +614,9 @@
The current request
-=item ret: C<$ret> (integer)
+=item ret: C<$need_auth> ( boolean )
-1 if authentication is required, 0 otherwise
+TRUE if authentication is required, FALSE otherwise
=item since: 1.99_12
1.16 +6 -2 modperl-docs/src/docs/2.0/api/Apache/Const.pod
Index: Const.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Const.pod,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -u -r1.15 -r1.16
--- Const.pod 8 Aug 2004 18:26:20 -0000 1.15
+++ Const.pod 9 Aug 2004 00:26:23 -0000 1.16
@@ -2267,7 +2267,8 @@
use Apache::Const -compile => qw(:satisfy);
-The C<:satisfy> group is for XXX constants.
+The C<:satisfy> constants group is used in conjunction with
+C<L<$r-E<gt>satisfies|docs::2.0::api::Apache::Access/C_satisfies_>>.
@@ -2280,7 +2281,7 @@
=back
-
+All of the requirements must be met.
@@ -2292,6 +2293,7 @@
=back
+any of the requirements must be met.
@@ -2303,6 +2305,8 @@
=item since: 1.99_12
=back
+
+There are no applicable satisfy lines
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
