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) >>.
 
-=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
@@ -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.
 
-=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
@@ -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
-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 *
@@ -304,13 +304,13 @@ See L</SETTINGS> below.
 
 =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.
 
-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.
 
@@ -337,3 +337,47 @@ the application should not process the request further.
 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