docs: more work

[cgi-auth-flexible.git] / caf.pod

diff --git a/caf.pod b/caf.pod
index 7921b357b33e80f63ff642a5f8fb316d4d2b9cab..5dd2f07fb56ebe9ddecf6dc4955489022f74190e 100644 (file)
--- a/caf.pod
+++ b/caf.pod
@@ -111,7 +111,7 @@ The resulting verifier object can be used to process individual
 requests, in each case with
 C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>.
 
 requests, in each case with
 C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>.
 

-=head2 RESPONSE GENERATION - SIMPLE APPLICATIONS
+=head2 RESPONSES - SIMPLE APPLICATIONS

 
 The simplist usage is to call C<< $request->check_ok() >> which will
 check the user's authentication.  If the user is not logged in it will
 
 The simplist usage is to call C<< $request->check_ok() >> which will
 check the user's authentication.  If the user is not logged in it will


@@ -126,7 +126,7 @@ After C<check_ok> returns true you should go ahead and process the
 request; you can use C<< $request->get_username >> to find out which
 user the request came from.
 
 request; you can use C<< $request->get_username >> to find out which
 user the request came from.
 

-=head2 RESPONSE GENERATION - SOPHISTICATED APPLICATIONS
+=head2 RESPONSES - SOPHISTICATED APPLICATIONS

 
 If you want to handle the control flow and to generate login forms,
 redirections, etc., yourself, you can say
 
 If you want to handle the control flow and to generate login forms,
 redirections, etc., yourself, you can say


@@ -268,7 +268,7 @@ C</usr/local>.  See C<srcdump_system_dir>.
 
 For each source item in a dvcs, the entire dvcs history does
 not contain anything confidential (or libellous).  Also, all files which
 
 For each source item in a dvcs, the entire dvcs history does
 not contain anything confidential (or libellous).  Also, all files which

-contain secrets are in the dvcs's C<.ignore> file.  See
+contain secrets are in the dvcs's I<.ignore> file.  See

 C<srcdump_vcsscript_git> et al.
 
 =item *
 C<srcdump_vcsscript_git> et al.
 
 =item *


@@ -304,13 +304,13 @@ See L</SETTINGS> below.
 
 =item C<< $verifier->new_request($cgi_query) >>
 
 
 =item C<< $verifier->new_request($cgi_query) >>
 

-Prepares to process a request.  C<$cgi_query> should normally
+Prepares to process a request.  I<$cgi_query> should normally

 be the query object from L<CGI(3perl)>.  Most of the default
 hook methods assume that it is; however if you replace enough of
 the hook methods then you can pass any value you like and it
 will be passed to your hooks.
 
 be the query object from L<CGI(3perl)>.  Most of the default
 hook methods assume that it is; however if you replace enough of
 the hook methods then you can pass any value you like and it
 will be passed to your hooks.
 

-The return value is the authentication request object (C<$authreq>)
+The return value is the authentication request object (I<$authreq>)

 which is used to check the incoming request and will contain
 information about its credentials.
 
 which is used to check the incoming request and will contain
 information about its credentials.
 


@@ -337,3 +337,47 @@ the application should not process the request further.
 Discards the resources (open files, etc.) in the verifier object.
 
 =back
 Discards the resources (open files, etc.) in the verifier object.
 
 =back

+
+=head REQUEST-HANDLING FUNCTIONS AND METHODS
+
+All of these are only valid after C<check_divert> or C<check_ok> has
+been called.  (In the case of C<check_ok> it won't normally be sensible
+to call these functions unless C<check_ok> returned true.)
+
+=item C<< $authreq->get_divert() >>
+
+Returns the value previously returned by C<check_divert>.
+
+=item C<< $authreq->get_username() >>
+
+Returns the name of the logged-in user.  If the user was not logged
+in (or their session had timed out, or something), returns undef.
+
+=head RESPONSE-RELATED FUNCTIONS AND METHODS
+
+=item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
+
+Convenience function which returns a url for a GET request to this
+application.
+
+I<$params> is a hashref specifying the parameters and the PATH_INFO.
+The keys are the parameter names, and the values are array refs with
+the parameter value(s) (as strings, as yet unquoted).  (They are array
+refs because it is possible to pass multiple values for the same
+parameter in a single request; normally each arrayref would be a
+singleton.)
+
+The request path will be the path to the application.  If a parameter
+with name C<< '' >> is supplied, it is taken as the PATH_INFO to
+supply - its value will be appended to the application path.  (It
+should normally start with C<< / >>, and only one value should be
+supplied.)
+
+=item C<< $authreq->chain_params() >>
+
+Returns a hash of the "relevant" parameters to this request, in a form
+used by XXX.  This is all of the query parameters which are not
+related to CGI::Auth::Flexible.  The PATH_INFO from the request is
+returned as the parameter C<< '' >>.
+
+=back