From 7cbcadcb21215c06e9d738031197ccfd8ec77bb2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Love=20H=C3=B6rnquist=20=C3=85strand?= <lha@kth.se>
Date: Sat, 28 Mar 2009 17:08:10 +0000
Subject: [PATCH] document

git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@24973 ec53bebd-3082-4978-b11e-865c3cabbd6b
---
 lib/hdb/hdb.h | 104 ++++++++++++++++++++++++++------------------------
 1 file changed, 55 insertions(+), 49 deletions(-)

diff --git a/lib/hdb/hdb.h b/lib/hdb/hdb.h
index 26d0c24d5..fd1fbe420 100644
--- a/lib/hdb/hdb.h
+++ b/lib/hdb/hdb.h
@@ -85,49 +85,63 @@ typedef struct HDB{
      * Then done the caller should call hdb_close(), and to release
      * all resources hdb_destroy().
      */
-    krb5_error_code (*hdb_open)(krb5_context,
-				struct HDB*,
-				int,
-				mode_t);
+    krb5_error_code (*hdb_open)(krb5_context, struct HDB*, int, mode_t);
     /**
      * Close the database for transaction
      *
      * Closes the database for further transactions, wont release any
      * permanant resources. the database can be ->hdb_open-ed again.
      */
-    krb5_error_code (*hdb_close)(krb5_context,
-				 struct HDB*);
-    void	    (*hdb_free)(krb5_context,
-				struct HDB*,
-				hdb_entry_ex*);
-    krb5_error_code (*hdb_fetch)(krb5_context,
-				 struct HDB*,
-				 krb5_const_principal,
-				 unsigned,
+    krb5_error_code (*hdb_close)(krb5_context, struct HDB*);
+    /**
+     * Free an entry after use.
+     */
+    void	    (*hdb_free)(krb5_context, struct HDB*, hdb_entry_ex*);
+    /**
+     * Fetch an entry from the backend
+     *
+     * Fetch an entry from the backend, flags are what type of entry
+     * should be fetch: client, server, krbtgt.
+     */
+    krb5_error_code (*hdb_fetch)(krb5_context, struct HDB*,
+				 krb5_const_principal, unsigned,
 				 hdb_entry_ex*);
-    krb5_error_code (*hdb_store)(krb5_context,
-				 struct HDB*,
-				 unsigned,
-				 hdb_entry_ex*);
-    krb5_error_code (*hdb_remove)(krb5_context,
-				  struct HDB*,
+    /**
+     * Store an entry to database
+     */
+    krb5_error_code (*hdb_store)(krb5_context, struct HDB*,
+				 unsigned, hdb_entry_ex*);
+    /**
+     * Remove an entry from the database.
+     */
+    krb5_error_code (*hdb_remove)(krb5_context, struct HDB*,
 				  krb5_const_principal);
-    krb5_error_code (*hdb_firstkey)(krb5_context,
-				    struct HDB*,
-				    unsigned,
-				    hdb_entry_ex*);
-    krb5_error_code (*hdb_nextkey)(krb5_context,
-				   struct HDB*,
-				   unsigned,
-				   hdb_entry_ex*);
-    krb5_error_code (*hdb_lock)(krb5_context,
-				struct HDB*,
-				int operation);
-    krb5_error_code (*hdb_unlock)(krb5_context,
-				  struct HDB*);
-    krb5_error_code (*hdb_rename)(krb5_context,
-				  struct HDB*,
-				  const char*);
+    /**
+     * As part of iteration, fetch one entry
+     */
+    krb5_error_code (*hdb_firstkey)(krb5_context, struct HDB*,
+				    unsigned, hdb_entry_ex*);
+    /**
+     * As part of iteration, fetch next entry
+     */
+    krb5_error_code (*hdb_nextkey)(krb5_context, struct HDB*, 
+				   unsigned, hdb_entry_ex*);
+    /**
+     * Lock database
+     *
+     * A lock can only be held by one consumers. Transaction can still
+     * happen on the database while the lock is held, so the entry is
+     * only useful for syncroning creation of the database and renaming of the database.
+     */
+    krb5_error_code (*hdb_lock)(krb5_context, struct HDB*, int);
+    /**
+     * Unlock database
+     */
+    krb5_error_code (*hdb_unlock)(krb5_context, struct HDB*);
+    /**
+     * Rename the data base.
+     */
+    krb5_error_code (*hdb_rename)(krb5_context, struct HDB*, const char*);
     /**
      * Get a encoded principal from database.
      *
@@ -135,18 +149,11 @@ typedef struct HDB{
      * principal key and return all data related to principal. The
      * encoded entry is of type hdb_entry or hdb_entry_alias.
      */
-    krb5_error_code (*hdb__get)(krb5_context,
-				struct HDB*,
-				krb5_data,
-				krb5_data*);
-    krb5_error_code (*hdb__put)(krb5_context,
-				struct HDB*,
-				int,
-				krb5_data,
-				krb5_data);
-    krb5_error_code (*hdb__del)(krb5_context,
-				struct HDB*,
-				krb5_data);
+    krb5_error_code (*hdb__get)(krb5_context, struct HDB*,
+				krb5_data, krb5_data*);
+    krb5_error_code (*hdb__put)(krb5_context, struct HDB*, int,
+				krb5_data, krb5_data);
+    krb5_error_code (*hdb__del)(krb5_context, struct HDB*, krb5_data);
     /**
      * Destroy the handle to the database.
      *
@@ -155,8 +162,7 @@ typedef struct HDB{
      * logical reverse of hdb_create() function that is the entry
      * point for the module.
      */
-    krb5_error_code (*hdb_destroy)(krb5_context,
-				   struct HDB*);
+    krb5_error_code (*hdb_destroy)(krb5_context, struct HDB*);
 }HDB;
 
 #define HDB_INTERFACE_VERSION	4