X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=cgi-auth-flexible.git;a=blobdiff_plain;f=caf.pod;h=fcb061521d4858218e432dd3cbd31f83d90bbb5d;hp=e93beb29e3df2135ec909003dd80f480d9702ff3;hb=8fdc8b3c4aafee033887c600384a7a78521b9a18;hpb=e08366d69f299c58c79213df79c0378c34067964

diff --git a/caf.pod b/caf.pod
index e93beb2..fcb0615 100644
--- a/caf.pod
+++ b/caf.pod
@@ -420,7 +420,8 @@ C<check_mutate>.
 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.
+I<$params> is a hashref specifying the parameters and the PATH_INFO
+(not including any parameters related to CGI::Auth::Flexible).
 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
@@ -461,6 +462,13 @@ Returns the value of the secret cookie.  CGI::Auth::Flexible sets this
 cookie in the forms generated by C<check_ok>.  You may also set it
 yourself (and indeed you must do so if you use C<check_divert>).
 
+item C<< $authreq->_chain_params() >>
+
+Returns a hash of the "relevant" parameters to this request, in a form
+suitable for C<url_with_query_params>.  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
 
 =head1 OTHER FUNCTIONS AND METHODS
@@ -618,8 +626,8 @@ any tags.
 
 =item C<CookieSecret>
 
-The secret cookie which should be set along with whatever response is
-sent to the client.  The value in the hash is the actual secret value
+The login cookie which should be set along with whatever response is
+sent to the client.  The value in the hash is the actual value
 of the cookie as a string.  C<undef> means no cookie setting header
 should be sent; C<''> means the cookie should be cleared.
 
@@ -752,7 +760,7 @@ path settings are relative values.
 
 Must be an absolute filename.
 
-=item C<assocdb_dbh>
+=item C<db_dbh>
 
 CGI::Auth::Flexible needs a database for recording users' login
 session.  This database needs to be shared across all instances of the
@@ -766,26 +774,26 @@ particular, there is no need for transactional integrity across
 changes made by CAF and your own application.)
 
 By default, CAF uses a sqlite3 database stored on local disk in the
-file named by C<assocdb_path>.  This will be suitable for all
+file named by C<db_path>.  This will be suitable for all
 applications which run on a single host.
 
 This value, if supplied, should be a DBI handle for the database.
 
-=item C<assocdb_dsn>
+=item C<db_dsn>
 
 This is the DSN to pass to C<< DBI->connect >>.  Used only if
-C<assocdb_dbh> is not supplied.
+C<db_dbh> is not supplied.
 
-=item C<assocdb_path>
+=item C<db_path>
 
 Path to the sqlite3 database used for CAF's session storage.  The
-default is currently C<caf-assocs.db> but will change in the future.
+default is C<caf.db>.
 
-Used only if neither C<assocdb_dbh> or C<assocdb_dsn> are supplied.
+Used only if neither C<db_dbh> or C<db_dsn> are supplied.
 
 If this is a relative path, it is in C<dir>.
 
-=item C<assocdb_table>
+=item C<db_prefix>
 
 Prefix for the SQL tables and indices to use (and to create, if
 necessary).
@@ -1311,12 +1319,27 @@ your application runs on multiple frontend hosts with a shared
 database, you may need to create for yourself the tables and indices
 used by CGI::Auth::Flexible.
 
+By default, every time CAF starts up, it attempts to execute certain
+fixed database statements to create the tables and indices it needs.
+These are run with C<$dbh->{PrintError}> set to 0.  The effect with
+sqlite (the default database) is that the tables and indices are
+created iff they do not already exist, and that no spurious errors are
+reported anywhere.
+
+If you use a different database, or just prefer to do things
+differently, you can set up the tables yourself and/or disable or
+modify the default setup statements, via the C<db_setup_stmts>
+setting.
+
+The tables needed are:
+
+
 xxx document _db_setup_do
 xxx make _db_setup_do explicitly overrideable
 
 
 xxx remaining settings
- assocdb_password
+ db_password
  username_password_error
  login_ok
  get_cookie_domain
@@ -1324,11 +1347,13 @@ xxx remaining settings
  print
  debug
 
-xxx document cookie
+xxx document cookie usage
+xxx document construct_cookie fn
+
+xxx document @default_db_setup_statements
 
 xxx bugs wrong default random on Linux
 xxx bugs wrong default random on *BSD
 xxx bugs keys not shared should be in db
-xxx rename caf-assocs.db
 xxx rename caf_assocsecret default cookie name
 xxx mention relationship between login_timeout and cookies