stas 2004/08/05 01:36:51
Modified: src/docs/2.0/api/Apache Access.pod Const.pod
Log:
work in progress
Revision Changes Path
1.5 +258 -22 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.4
retrieving revision 1.5
diff -u -u -r1.4 -r1.5
--- Access.pod 22 May 2004 02:03:27 -0000 1.4
+++ Access.pod 5 Aug 2004 08:36:50 -0000 1.5
@@ -1,21 +1,32 @@
=head1 NAME
-Apache::Access - A Perl API for Apache request object
+Apache::Access - A Perl API for Apache request object: Access,
+Authentication and Authorization.
+
=head1 Synopsis
+ use Apache::Access ();
+
META: needs to be completed
- use Apache::Access ();
+
+
=head1 Description
-C<Apache::Access> provides the Perl API for Apache request object.
+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.
+
+
+
@@ -27,50 +38,250 @@
-=head2 C<allow_options>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<allow_methods>
-Retrieve the value of Options for this request
+Specify which HTTP methods are allowed
- $ret = $r->allow_options();
+ $r->allow_methods($reset);
+ $r->allow_methods($reset, @methods);
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item ret: C<$ret> (integer)
+=item arg1: C<$reset> ( boolean )
+
+If a true value is passed all the previously allowed methods are
+removed. Otherwise the list is left intact.
+
+=item opt arg2: C<@methods> ( array of strings )
+
+a list of HTTP methods to be allowed (e.g. C<GET> and C<POST>)
+
+=item ret: no return value
-the Options bitmask
+=item since: 1.99_12
=back
+For example: here is how to allow only C<GET> and C<POST> methods,
+regardless to what was the previous setting:
+
+ $r->allow_methods(1, qw(GET POST));
+
+
+
+
+
+
+=head2 C<allow_options>
+
+Retrieve the value of C<Options> for this request
+
+ $options = $r->allow_options();
+
+=over 4
+
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+
+The current request
+
+=item ret: C<$options> ( integer )
+
+the C<Options> bitmask. Normally used with bitlogic operators against
+C<L<Apache::Const :options
+constants|docs::2.0::api::Apache::Const/C__options_>>.
+
+=item since: 1.99_12
+
+=back
+
+For example if the configuration for the current request was:
+
+ Options None
+ Options Indexes FollowSymLinks
+
+The following applies:
+
+ use Apache::Const -compile => qw(:options);
+ $r->allow_options & Apache::OPT_INDEXES; # TRUE
+ $r->allow_options & Apache::OPT_SYM_LINKS; # TRUE
+ $r->allow_options & Apache::OPT_EXECCGI; # FALSE
+
+
+
+
=head2 C<allow_overrides>
-META: Autogenerated - needs to be reviewed/completed
+Retrieve the value of C<AllowOverride> for this request
+
+ $allow_override = $r->allow_overrides();
+
+=over 4
+
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+
+The current request
+
+=item ret: C<$allow_override> ( integer )
+
+the C<AllowOverride> bitmask. Normally used with bitlogic operators
+against C<L<Apache::Const :override
+constants|docs::2.0::api::Apache::Const/C__override_>>.
+
+=item since: 1.99_12
+
+=back
+
+For example if the configuration for the current request was:
+
+ AllowOverride AuthConfig
+
+The following applies:
+
+ use Apache::Const -compile => qw(:override);
+ $r->allow_overrides & Apache::OR_AUTHCFG; # TRUE
+ $r->allow_overrides & Apache::OR_LIMIT; # FALSE
+
+
+
+
+
+
+=head2 C<auth_name>
-Retrieve the value of the AllowOverride for this request
+Get/set the current Authorization realm (the per directory
+configuration directive C<AuthName>):
- $ret = $r->allow_overrides();
+ $auth_name = $r->auth_name();
+ $auth_name = $r->auth_name($new_auth_name);
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item ret: C<$ret> (integer)
+=item opt arg1: C<$new_auth_name> ( string )
+
+If C<$new_auth_name> is passed a new C<AuthName> value is set
+
+=item ret: C<$> ( integer )
+
+The current value of C<AuthName>
+
+=item since: 1.99_12
+
+=back
+
+The C<AuthName> directive creates protection realm within the server
+document space. To quote RFC 1945 "These realms allow the protected
+resources on a server to be partitioned into a set of protection
+spaces, each with its own authentication scheme and/or authorization
+database." The client uses the root URL of the server to determine
+which authentication credentials to send with each HTTP request. These
+credentials are tagged with the name of the authentication realm that
+created them. Then during the authentication stage the server uses
+the current authentication realm, from C<$r-E<gt>auth_name>, to
+determine which set of credentials to authenticate.
+
+
+
+
+
+
+
+
+=head2 C<auth_type>
+
+Get/set the type of authorization required for this request (the per
+directory configuration directive C<AuthType>):
+
+ $auth_type = $r->auth_type();
+ $auth_type = $r->auth_type($new_auth_type);
+
+=over 4
+
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+
+The current request
+
+=item opt arg1: C<$new_auth_type> ( string )
+
+If C<$new_auth_type> is passed a new C<AuthType> value is set
+
+=item ret: C<$> ( integer )
+
+The current value of C<AuthType>
+
+=item since: 1.99_12
+
+=back
+
+Normally C<AuthType> would be set to C<Basic> to use the basic
+authentication scheme defined in RFC 1945, I<Hypertext Transfer
+Protocol -- HTTP/1.0>. However, you could set to something else and
+implement your own authentication scheme.
+
+
-the overrides bitmask
+
+
+
+
+
+=head2 C<get_basic_auth_pw>
+
+Get the password from the request headers
+
+ my($rc, $passwd) = $r->get_basic_auth_pw();
+
+=over 4
+
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+
+The current request
+
+=item ret1: C<$rc>
+( C<L<Apache::Const constant|docs::2.0::api::Apache::Const>> )
+
+C<Apache::OK> if the C<$passwd> value is set (and assured a correct
+value in
+C<L<$r-E<gt>user|docs::2.0::api::Apache::RequestRec/C_user_>>);
+otherwise it returns an error code, either
+C<Apache::HTTP_INTERNAL_SERVER_ERROR> if things are really confused,
+C<Apache::HTTP_UNAUTHORIZED> if no authentication at all seemed to be
+in use, or C<Apache::DECLINED> if there was authentication, but it
+wasn't C<Basic> (in which case, the caller should presumably decline
+as well).
+
+=item ret2: C<$ret> (string)
+
+The password as set in the headers (decoded)
+
+=item since: 1.99_12
=back
+If C<L<AuthType|/C_auth_type_>> is not set, this handler first sets it
+to C<Basic>.
+
+
+
+
@@ -86,7 +297,8 @@
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
@@ -94,6 +306,8 @@
The user logged in to the client machine
+=item since: 1.99_12
+
=back
@@ -112,12 +326,15 @@
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
=item ret: no return value
+=item since: 1.99_12
+
=back
@@ -136,12 +353,15 @@
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
=item ret: no return value
+=item since: 1.99_12
+
=back
@@ -160,18 +380,28 @@
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
=item ret: no return value
+=item since: 1.99_12
+
=back
+=head2 C<requires>
+
+
+
+
+
+
=head2 C<satisfies>
META: Autogenerated - needs to be reviewed/completed
@@ -182,7 +412,8 @@
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
@@ -194,6 +425,8 @@
Apache::SATISFY_ALL -- all of the requirements must be met.
Apache::SATISFY_NOSPEC -- There are no applicable satisfy lines
+=item since: 1.99_12
+
=back
@@ -211,13 +444,16 @@
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
=item ret: C<$ret> (integer)
1 if authentication is required, 0 otherwise
+
+=item since: 1.99_12
=back
1.14 +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.13
retrieving revision 1.14
diff -u -u -r1.13 -r1.14
--- Const.pod 4 Jul 2004 01:41:49 -0000 1.13
+++ Const.pod 5 Aug 2004 08:36:50 -0000 1.14
@@ -1900,7 +1900,9 @@
use Apache::Const -compile => qw(:options);
-The C<:options> group is for XXX constants.
+The C<:options> group is contains constants corresponding to the
+C<Options> configuration directive. For examples see:
+C<L<$r-E<gt>allow_options|docs::2.0::api::Apache::Access/C_allow_options_>>.
@@ -2029,7 +2031,9 @@
use Apache::Const -compile => qw(:override);
-The C<:override> group is for XXX constants.
+The C<:override> group is contains constants corresponding to the
+C<AllowOverride> configuration directive. For examples see:
+C<L<$r-E<gt>allow_options|docs::2.0::api::Apache::Access/C_allow_overrides_>>.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
