Added missing comments in eurephiadb_driver.h

1 files changed, 289 insertions, 8 deletions

diff --git a/database/eurephiadb_driver.h b/database/eurephiadb_driver.h
index 88522be..d74c3e6 100644
--- a/database/eurephiadb_driver.h
+++ b/database/eurephiadb_driver.h
@@ -346,7 +346,6 @@ int (*eDBdestroy_session) (eurephiaCTX *ctx, eurephiaSESSION *session);
  * @param val   Value to be stored
  *
  * @return Returns 1 on success, otherwise 0
- *
  * @see SESSVAL_NEW, SESSVAL_UPDATE, SESSVAL_DELETE
  */
 int (*eDBstore_session_value) (eurephiaCTX *ctx, eurephiaSESSION *skey, int mode,
@@ -449,6 +448,7 @@ int (*eDBadminConfigDelete) (eurephiaCTX *ctx, const char *key);
  * @param sortkeys String containing the sort order of the fields
  *
  * @return Returns an XML document on success with all users, otherwise NULL
+ * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
  */
 xmlDoc *(*eDBadminGetUserList) (eurephiaCTX *ctx, const char *sortkeys);
 
@@ -456,7 +456,7 @@ xmlDoc *(*eDBadminGetUserList) (eurephiaCTX *ctx, const char *sortkeys);
 /**
  * This function will search up a user, based on information given in a fieldMapping structure.
  * It will return an XML document containing the user information requested, controlled by the
- * getInfo flag. These flags are defined in eurephiadb_driver.h
+ * infoType flag. These flags are defined in eurephiadb_driver.h
  *
  * @version API version level 2
  * @param ctx eurephiaCTX
@@ -478,8 +478,7 @@ xmlDoc *(*eDBadminGetUserList) (eurephiaCTX *ctx, const char *sortkeys);
  *
  * @return Returns an XML document containing the requested user information on success, otherwise
  *         NULL is returned.
- *
- * @see eurephiaXML_CreateDoc()
+ * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
  * @see USERINFO_user, USERINFO_certs, USERINFO_lastlog, USERINFO_attempts, USERINFO_blacklist
  */
 xmlDoc *(*eDBadminGetUserInfo) (eurephiaCTX *ctx, int infoType, xmlDoc *srch);
@@ -510,7 +509,6 @@ xmlDoc *(*eDBadminGetUserInfo) (eurephiaCTX *ctx, int infoType, xmlDoc *srch);
  * the eurephia_pwd_crypt() function.
  *
  * @return Returns the user ID (uid) of the new user account on success, otherwise -1 is returned.
- *
  * @see eurephiaXML_CreateDoc(), eurephia_pwd_crypt()
  */
 int (*eDBadminAddUser) (eurephiaCTX *ctx, xmlDoc *userinfo);
@@ -540,7 +538,6 @@ int (*eDBadminAddUser) (eurephiaCTX *ctx, xmlDoc *userinfo);
  *          argument to the function.
  *
  * @return Returns 1 on success, otherwise 0.
- *
  * @see eurephiaXML_CreateDoc()
  */
 int (*eDBadminUpdateUser) (eurephiaCTX *ctx, const int uid, xmlDoc *userinfo);
@@ -564,25 +561,309 @@ int (*eDBadminUpdateUser) (eurephiaCTX *ctx, const int uid, xmlDoc *userinfo);
  *          as a separate parameter, as a security feature
  *
  * @return Returns 1 on success, otherwise 0.
- *
  * @see eurephiaXML_CreateDoc()
  */
 int (*eDBadminDeleteUser) (eurephiaCTX *ctx, const int uid, xmlDoc *userinfo);
 
+
+/**
+ * Retrieves a list of all registered certificates.
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param sortkeys String containing the sort order of the fields
+ *
+ * @return Returns an XML document on success with all certificates, otherwise NULL
+ *
+ * @see eurephiaXML_getRoot()
+ */
 xmlDoc *(*eDBadminGetCertificateList) (eurephiaCTX *ctx, const char *sortkeys);
+
+
+/**
+ * Get information about a specific certificate
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param srch XML document describing the search criteria
+ * @param sortkeys String containing the sort order of the fields
+ *
+ * Skeleton of an XML search document
+ * @code
+ *    <eurephia format="1">
+ *      <certificate_info>
+ *        <fieldMapping table="certificates">
+ *            <{field name}>{field value}</{field name}>
+ *            ...
+ *            <{field name}>{field value}</{field name}>
+ *        </fieldMapping>
+ *      </certificate_info>
+ *    </eurephia>
+ * @endcode
+ *
+ * @return Returns an XML document containing the requested certificate information on success, otherwise
+ *         NULL is returned.
+ *
+ * Skeleton of a result document
+ * @code
+ * <eurephia format="1">
+ *    <certificates certificates={number of found certs}">
+ *        <certificate certid="{int}" depth="{int}" registered="{date+time}">
+ *            <digest>{SHA1 digest of cert}</digest>
+ *            <common_name>{(CN) common name of cert}</common_name>
+ *            <organisation>{(O) organisation name of cert}</organisation>
+ *            <email>{(emailAddr) e-mail address found in cert}</email>
+ *        </certificate>
+ *    </certificates>
+ * </eurephia>
+ * @endcode
+ *
+ * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
+ */
 xmlDoc *(*eDBadminGetCertificateInfo) (eurephiaCTX *ctx, xmlDoc *searchkey, const char *sortkeys);
+
+
+/**
+ * Register a certificate in the database
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param certinfo_xml XML document with the certificate information.
+ *
+ * Skeleton of an XML document needed for registering a new certificate
+ * @code
+ * <eurephia format="1">
+ *      <register_certificate>
+ *          <fieldMapping table="certificates">
+ *              <depth>{cert.depth}</depth>
+ *              <digest>{SHA1 digest}</digest>
+ *              <common_name>{common_name}</common_name>
+ *              <organisation>{org.}</organisation>
+ *              <email>{email addr}</email>
+ *          </fieldMapping>
+ *      </register_certificate>
+ * </eurephia>
+ * @endcode
+ *
+ * @return The function returns certid of the newly registered certificate on success, otherwise -1
+ * @see eurephiaXML_CreateDoc()
+ */
 int (*eDBadminAddCertificate) (eurephiaCTX *ctx, xmlDoc *certinfo_xml);
+
+
+/**
+ * Delete a certificate from the database
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param certinfo_xml XML document with the certificate information to be deleted
+ *
+ * Skeleton of an XML document to delete certificates.  Not all fields in the
+ * fieldMapping tag is needed, to delete more than one certificate in one operation.
+ * @code
+ * <eurephia format="1">
+ *      <delete_certificate>
+ *          <fieldMapping table="certificates">
+ *              <digest>{SHA1 digest}</digest>
+ *              <common_name>{common_name}</common_name>
+ *              <organisation>{org.}</organisation>
+ *              <email>{email addr}</email>
+ *          </fieldMapping>
+ *      </register_certificate>
+ * </eurephia>
+ * @endcode
+ *
+ * @return Returns 1 on success, otherwise 0.
+ * @see eurephiaXML_CreateDoc()
+ */
 int (*eDBadminDeleteCertificate) (eurephiaCTX *ctx, xmlDoc *certinfo_xml);
 
+
+/**
+ * Retrieve, add, modify or delete user/certificate links
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param usrcrt_xml XML document containing operation information
+ *
+ * Skeleton of needed XML document
+ * @code
+ *    <eurephia format="1">
+ *        <usercerts mode="{search|register|remove|update}" [uicid="{uicid}"]>
+ *            <fieldMapping table="usercerts">
+ *               <{field name}>{search value}</{field name}>
+ *            </fieldMapping>
+ *            [<sortfields>{field name}[, {field name},...]</sortfields>] <!-- Only for mode='search' -->
+ *        </usercerts
+ *    </eurephia>
+ * @endcode
+ *
+ * In search mode, it can be several field name tags to narrow the search.
+ * If mode is 'update' the 'uicid' attribute must be present in the usercerts tag.
+ *
+ * @return Returns a valid eurephia XML document on success.  If errors happened, either an XML document
+ *         with an error message will be returned or NULL.
+ * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
+ */
 xmlDoc *(*eDBadminUserCertsLink) (eurephiaCTX *ctx, xmlDoc *usrcrt_xml);
 
+
+/**
+ * Retrieve a list over all users granted access to the administration utilities
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param srch_xml XML document specifying the search query.
+ *
+ * Search XML document skeleton:
+ * @code
+ *    <eurephia format="1">
+ *        <admin_access>
+ *            <fieldMapping table="eurephia_adminaccess">
+ *               <{search field}>{search value}</{search field}>
+ *            </fieldMapping>
+ *        </admin_access>
+ *    </eurephia>
+ * @endcode
+ * Valid field names are: uid, interface, access
+ * It can be several search field tags to narrow the search even more.
+ *
+ * @return Returns a valid XML document with the result on success, otherwise NULL.
+ * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
+ */
 xmlDoc *(*eDBadminGetAdminAccess) (eurephiaCTX *ctx, xmlDoc *srch_xml);
+
+
+/**
+ * Add or delete access to the administration utilities
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param grant_xml XML document with the operation and information.
+ *
+ * XML format skeleton for grant_xml
+ * @code
+ * <eurephia format="1">
+ *      <edit_admin_access mode="{grant|revoke}">
+ *          <fieldMapping table="eurephia_adminaccess">
+ *              <uid>{user id}</uid>
+ *              <interface>{C|W}</uid>
+ *              <accesslevel>{access level string}</accesslevel>
+ *          </fieldMapping>
+ *      </edit_admin_access>
+ * </eurephia>
+ * @endcode
+ * To grant access, all fields are needed.  For bulk revokes, some fields can be skipped
+ *
+ * @return Returns 1 on success, otherwise 0 or -1
+ * @see eurephiaXML_CreateDoc()
+ */
 int (*eDBadminEditAdminAccess) (eurephiaCTX *ctx, xmlDoc *grant_xml);
 
-xmlDoc *(*eDBadminFirewallProfiles) (eurephiaCTX *ctx, xmlDoc *srch);
 
+/**
+ * Query or modify the firewall access profiles.
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param xmlqry XML document with the operation and information.
+ *
+ * The XML format skeleton
+ * @code
+ *    <eurephia format="1">
+ *        <firewall_profiles mode="{search|add|delete}">
+ *            <fieldMapping table="fwprofiles">
+ *               <{field name}>{search value}</{field name}>
+ *            </fieldMapping>
+ *        </firewall_profiles>
+ *    </eurephia>
+ * @endcode
+ * It can be several field name tags to narrow the search even more.
+ * For the add mode, the fw_profile field name tag must be present.
+ *
+ * @return Returns a valid XML document with the result on success, otherwise either
+ *         NULL or an XML error document is returned.
+ * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
+ */
+xmlDoc *(*eDBadminFirewallProfiles) (eurephiaCTX *ctx, xmlDoc *xmlqry);
+
+
+/**
+ * Retrieve the eurephia lastlog
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param srch XML document specifying the search query
+ * @param sortkeys String containing the sort order of the fields
+ *
+ * The XML format skeleton
+ * @code
+ *    <eurephia format="1">
+ *        <lastlog_query>
+ *            <fieldMapping table="lastlog">
+ *               <{search field}>{search value}</{search field}>
+ *            </fieldMapping>
+ *        </lastlog_query>
+ *    </eurephia>
+ * @endcode
+ * Valid field names are: uid, certid, ip, vpnip, status, login, logout, id, username, macaddr, uicid
+ *
+ * @return Returns a valid XML document on success, otherwise NULL
+ * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
+ */
 xmlDoc *(*eDBadminGetLastlog) (eurephiaCTX *ctx, xmlDoc *srch, const char *sortkeys);
+
+
+/**
+ * Query or modify the attempts log.
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param qryxml document specifying the operation
+ *
+ * The XML format skeleton
+ * @code
+ *    <eurephia format="1">
+ *        <attemptslog mode="{search|reset|delete}">
+ *            <fieldMapping table="attempts">
+ *               <{field name}>{field value}</{field field}>
+ *            </fieldMapping>
+ *        </attemptslog>
+ *    </eurephia>
+ * @endcode
+ * Valid fields are: username, ip, digest, attempts, registered, lastattempt, id
+ *
+ * @return Returns a valid XML document on success, otherwise NULL or an XML document
+ *         with an error message.
+ * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
+ */
 xmlDoc *(*eDBadminAttemptsLog) (eurephiaCTX *ctx, xmlDoc *qryxml);
+
+
+/**
+ * Query or modify the attempts log.
+ *
+ * @version API version level 2
+ * @param ctx eurephiaCTX
+ * @param qryxml document specifying the operation
+ *
+ * The XML format skeleton
+ * @code
+ *    <eurephia format="1">
+ *        <blacklist mode="{list|add|delete}">
+ *            <fieldMapping table="blacklist">
+ *               <{field name}>{field value}</{field field}>
+ *            </fieldMapping>
+ *        </blacklist>
+ *    </eurephia>
+ * @endcode
+ * For listing and delete mode it be several field tags to limit the search even more.
+ * For add mode only username, IP address or certificate digest can be given.
+ *
+ * @return Returns a valid XML document on success, otherwise NULL or an XML document
+ *         with an error message.
+ * @see eurephiaXML_CreateDoc(), eurephiaXML_getRoot()
+ */
 xmlDoc *(*eDBadminBlacklist) (eurephiaCTX *ctx, xmlDoc *qryxml);
 #endif /* HAVE_LIBXML2 */