From 91865279044543480ed470b5329f8ad7d497deb9 Mon Sep 17 00:00:00 2001
From: Marko Lindqvist <cazfi74@gmail.com>
Date: Wed, 7 Apr 2021 16:58:54 +0300
Subject: [PATCH 44/44] Update fcdb lua api documentation

See osdn #41935

Signed-off-by: Marko Lindqvist <cazfi74@gmail.com>
---
 doc/README.fcdb  | 39 +++++++++++++++------------------------
 lua/database.lua |  8 ++++----
 2 files changed, 19 insertions(+), 28 deletions(-)

diff --git a/doc/README.fcdb b/doc/README.fcdb
index 6ce1663039..c6db6d56b2 100644
--- a/doc/README.fcdb
+++ b/doc/README.fcdb
@@ -182,29 +182,29 @@ If that's sufficient for you, it's not necessary to read on.
 
 Freeciv expects the following lua functions to be defined in database.lua:
 
-  -- try to load data for an existing user
-  -- return TRUE if user exists, FALSE otherwise
-  function user_load(conn)
-  -- save a new user to the database
-  function user_save(conn)
-  -- log the connection attempt (success is boolean)
+  -- Check if user exists.
+  -- return TRUE if user from connection exist in the auth system
+  function user_exists(conn)
+
+  -- Check use password.
+  -- return TRUE if user exist and password is correct, nil otherwise
+  function user_verify(conn, plaintext)
+
+  -- Save a new user to the database
+  function user_save(conn, password)
+
+  -- Log the connection attempt (success is boolean)
   function user_log(conn, success)
 
-  -- test and initialise the database connection
+  -- Test and initialise the database connection
   function database_init()
-  -- free the database connection
+
+  -- Free the database connection
   function database_free()
 
 Where 'conn' is on object representing the connection to the client which
 requests access.
 
-The return status of all of these functions should be one of
-
-  fcdb.status.ERROR
-  fcdb.status.TRUE
-  fcdb.status.FALSE
-
-indicating an error, a positive or a negative result.
 
 The following lua functions are provided by Freeciv:
 
@@ -212,13 +212,6 @@ The following lua functions are provided by Freeciv:
   auth.get_username(conn)
   -- return the client IP address (string)
   auth.get_ipaddr(conn)
-  -- tell the server (the MD5 hash of) the correct password to check against
-  -- for this connection (usually to be called by user_load())
-  -- returns whether this succeeded
-  auth.set_password(conn, password)
-  -- return (the MD5 hash of) the password for this connection (as specified
-  -- by the client in user_save(), or as previously set by set_password()).
-  auth.get_password(conn)
 
   -- return a value from the --Database configuration file
   fcdb.option(type)
@@ -239,8 +232,6 @@ data, etc.
 
 * Move password comparison / policy to Lua script
   <http://www.hostedredmine.com/issues/660267>
-* Give database.lua access to do more stuff
-  <https://www.hostedredmine.com/issues/657141>
 * Allow setting cmdlevel per-user, etc
   <https://www.hostedredmine.com/issues/657143>
 * Give database.lua access to game signals and events
diff --git a/lua/database.lua b/lua/database.lua
index 9ce3da896d..68a13fbbf5 100644
--- a/lua/database.lua
+++ b/lua/database.lua
@@ -229,7 +229,7 @@ function user_verify(conn, plaintext)
   return row.password == md5sum(plaintext)
 end
 
--- save a user to the database
+-- Save a new user to the database
 function user_save(conn, password)
   local table_user = get_option("table_user")
 
@@ -252,7 +252,7 @@ function user_save(conn, password)
   user_log(conn, true)
 end
 
--- log the session
+-- Log the connection attempt (success is boolean)
 function user_log(conn, success)
   local query   -- sql query
 
@@ -286,7 +286,7 @@ end
 -- freeciv database entry functions
 -- **************************************************************************
 
--- test and initialise the database connection
+-- Test and initialise the database connection
 function database_init()
   options_init()
 
@@ -307,7 +307,7 @@ function database_init()
     backend))
 end
 
--- free the database connection
+-- Free the database connection
 function database_free()
   log.verbose('Closing database connection...')
 
-- 
2.30.2