perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/api/Apache Access.pod Const.pod
Date Thu, 05 Aug 2004 08:36:51 GMT
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: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message