From 76e216dd61168b2e75435ff67f26fe02bdc93187 Mon Sep 17 00:00:00 2001 From: David Sommerseth Date: Fri, 11 Sep 2009 22:44:29 +0200 Subject: Added doxygen comments on the last missing files --- database/sqlite/administration/attempts.c | 37 ++++++++++++++++- database/sqlite/administration/blacklist.c | 36 +++++++++++++++- database/sqlite/administration/firewalladmin.c | 57 ++++++++++++++++++-------- database/sqlite/administration/usercerts.c | 56 ++++++++++++++++++------- 4 files changed, 153 insertions(+), 33 deletions(-) (limited to 'database') diff --git a/database/sqlite/administration/attempts.c b/database/sqlite/administration/attempts.c index 8518e28..e1e5d19 100644 --- a/database/sqlite/administration/attempts.c +++ b/database/sqlite/administration/attempts.c @@ -1,6 +1,6 @@ /* attempts.c -- Functions for processing openvpn_attempts records * - * GPLv2 only - Copyright (C) 2008, 2009 + * GPLv2 only - Copyright (C) 2009 * David Sommerseth * * This program is free software; you can redistribute it and/or @@ -19,6 +19,15 @@ * */ +/** + * @file sqlite/administration/attempts.c + * @author David Sommerseth + * @date 2009-04-09 + * + * @brief Functions for processing attempts entries in the database + * + */ + #include #include #include @@ -47,6 +56,14 @@ #include "../sqlite.h" +/** + * Internal function. Retrieves a list of all registered entries in the attempts table + * + * @param ctx eurephiaCTX + * @param fmap eDBfieldMap containing the search query + * + * @return Returns a valid eurephia XML document on success, otherwise NULL + */ xmlDoc *attempts_list(eurephiaCTX *ctx, eDBfieldMap *fmap) { dbresult *res = NULL; xmlDoc *doc = NULL; @@ -105,6 +122,15 @@ xmlDoc *attempts_list(eurephiaCTX *ctx, eDBfieldMap *fmap) { } + +/** + * Internal function. Resets the attempts counter for one or more entries in the database + * + * @param ctx eurephiaCTX + * @param fmap eDBfieldMap defining which records to reset the attempts counter on + * + * @return Returns a valid eurephia XML document on success, otherwise NULL + */ xmlDoc *attempts_reset(eurephiaCTX *ctx, eDBfieldMap *fmap) { dbresult *res = NULL; xmlDoc *ret = NULL; @@ -131,6 +157,15 @@ xmlDoc *attempts_reset(eurephiaCTX *ctx, eDBfieldMap *fmap) { return ret; } + +/** + * Internal function. Deletes an entry from the attempts log + * + * @param ctx eurephiaCTX + * @param fmap eDBfieldMap containing the entry/entries to delete + * + * @return Returns a valid eurephia XML document on success, otherwise NULL + */ xmlDoc *attempts_delete(eurephiaCTX *ctx, eDBfieldMap *fmap) { dbresult *res = NULL; xmlDoc *ret = NULL; diff --git a/database/sqlite/administration/blacklist.c b/database/sqlite/administration/blacklist.c index 7719ccc..12130c3 100644 --- a/database/sqlite/administration/blacklist.c +++ b/database/sqlite/administration/blacklist.c @@ -1,6 +1,6 @@ /* blacklist.c -- Functions for processing openvpn_blacklist records * - * GPLv2 only - Copyright (C) 2008, 2009 + * GPLv2 only - Copyright (C) 2009 * David Sommerseth * * This program is free software; you can redistribute it and/or @@ -19,6 +19,15 @@ * */ +/** + * @file sqlite/administration/blacklist.c + * @author David Sommerseth + * @date 2009-05-09 + * + * @brief Functions for administering the blacklist table + * + */ + #include #include #include @@ -47,6 +56,14 @@ #include "../sqlite.h" +/** + * Internal function. Retrieves a list of all registered entries in the blacklist table + * + * @param ctx eurephiaCTX + * @param fmap eDBfieldMap containing the search query + * + * @return Returns a valid eurephia XML document on success, otherwise NULL + */ xmlDoc *blacklist_list(eurephiaCTX *ctx, eDBfieldMap *fmap) { dbresult *res = NULL; xmlDoc *doc = NULL; @@ -104,6 +121,14 @@ xmlDoc *blacklist_list(eurephiaCTX *ctx, eDBfieldMap *fmap) { } +/** + * Internal function. Registers a new entry in the blacklist. + * + * @param ctx eurephiaCTX + * @param fmap eDBfieldMap containing the entry to be registered + * + * @return Returns an eurephia ResultMsg XML document, with success message or an error message + */ xmlDoc *blacklist_add(eurephiaCTX *ctx, eDBfieldMap *fmap) { dbresult *res = NULL; xmlDoc *ret = NULL; @@ -127,6 +152,15 @@ xmlDoc *blacklist_add(eurephiaCTX *ctx, eDBfieldMap *fmap) { return ret; } + +/** + * Internal function. Deletes an entry from the blacklist + * + * @param ctx eurephiaCTX + * @param fmap eDBfieldMap containing the entry to be deleted + * + * @return Returns an eurephia ResultMsg XML document, with success message or an error message + */ xmlDoc *blacklist_delete(eurephiaCTX *ctx, eDBfieldMap *fmap) { dbresult *res = NULL; xmlDoc *ret = NULL; diff --git a/database/sqlite/administration/firewalladmin.c b/database/sqlite/administration/firewalladmin.c index 0e8e91a..378f265 100644 --- a/database/sqlite/administration/firewalladmin.c +++ b/database/sqlite/administration/firewalladmin.c @@ -19,6 +19,15 @@ * */ +/** + * @file sqlite/administration/firewalladmin.c + * @author David Sommerseth + * @date 2009-03-28 + * + * @brief Functions for managing firewall profiles + * + */ + #include #include #include @@ -52,6 +61,14 @@ void xmlReplaceChars(xmlChar *str, char s, char r); +/** + * Internal function. Queries the database for a list of user-certificate links + * + * @param ctx eurephiaCTX + * @param fmap eDBfieldMap containing the search criteria + * + * @return Returns a valid eurephia XML document on success, otherwise NULL + */ xmlDoc *fwadmin_search(eurephiaCTX *ctx, eDBfieldMap *fmap) { dbresult *res = NULL; xmlDoc *doc = NULL; @@ -82,7 +99,7 @@ xmlDoc *fwadmin_search(eurephiaCTX *ctx, eDBfieldMap *fmap) { NULL, fmap, "accessprofile, uid, c.certid"); if( res == NULL ) { eurephia_log(ctx, LOG_ERROR, 0, "Error querying the database for firewall profiles"); - return 0; + return NULL; } eurephiaXML_CreateDoc(ctx, 1, "firewall_profiles", &doc, &root_n); @@ -135,6 +152,14 @@ xmlDoc *fwadmin_search(eurephiaCTX *ctx, eDBfieldMap *fmap) { } +/** + * Internal function. Registers a new firewall profile + * + * @param ctx eurephiaCTX + * @param fmap eDBfieldMap containing information about the new profile + * + * @return Returns an eurephia ResultMsg XML document, with success message or an error message + */ xmlDoc *fwadmin_add(eurephiaCTX *ctx, eDBfieldMap *fmap) { dbresult *res = NULL; xmlDoc *ret = NULL; @@ -158,6 +183,14 @@ xmlDoc *fwadmin_add(eurephiaCTX *ctx, eDBfieldMap *fmap) { } +/** + * Internal function. Deletes firewall profile(s) from the database + * + * @param ctx eurephiaCTX + * @param fmap eDBfieldMap containing information about the profile(s) to be deleted + * + * @return Returns an eurephia ResultMsg XML document, with success message or an error message + */ xmlDoc *fwadmin_delete(eurephiaCTX *ctx, eDBfieldMap *fmap) { dbresult *res = NULL; xmlDoc *ret = NULL; @@ -212,26 +245,17 @@ xmlDoc *fwadmin_delete(eurephiaCTX *ctx, eDBfieldMap *fmap) { } -// The search XML document format is: -// -// -// -// <{field name}>{search value} -// -// -// -// -// It can be several field name tags to limit the search even more. -// For the add mode, the fw_profile field name tag must be present. -// -xmlDoc *eDBadminFirewallProfiles(eurephiaCTX *ctx, xmlDoc *srch) { +/** + * @copydoc eDBadminFirewallProfiles() + */ +xmlDoc *eDBadminFirewallProfiles(eurephiaCTX *ctx, xmlDoc *xmlqry) { eDBfieldMap *fmap = NULL; char *mode = NULL; xmlDoc *resxml = NULL; xmlNode *root_n = NULL, *fieldmap_n = NULL; DEBUG(ctx, 20, "Function call: eDBadminFirewallProfiles(ctx, {xmlDoc})"); - assert( (ctx != NULL) && (srch != NULL) ); + assert( (ctx != NULL) && (xmlqry != NULL) ); if( (ctx->context_type != ECTX_ADMIN_CONSOLE) && (ctx->context_type != ECTX_ADMIN_WEB) ) { eurephia_log(ctx, LOG_CRITICAL, 0, @@ -239,7 +263,7 @@ xmlDoc *eDBadminFirewallProfiles(eurephiaCTX *ctx, xmlDoc *srch) { return NULL; } - root_n = eurephiaXML_getRoot(ctx, srch, "firewall_profiles", 1); + root_n = eurephiaXML_getRoot(ctx, xmlqry, "firewall_profiles", 1); if( root_n == NULL ) { eurephia_log(ctx, LOG_CRITICAL, 0, "Invalid XML input."); return NULL; @@ -269,4 +293,3 @@ xmlDoc *eDBadminFirewallProfiles(eurephiaCTX *ctx, xmlDoc *srch) { eDBfreeMapping(fmap); return resxml; } - diff --git a/database/sqlite/administration/usercerts.c b/database/sqlite/administration/usercerts.c index 6dd091c..408891f 100644 --- a/database/sqlite/administration/usercerts.c +++ b/database/sqlite/administration/usercerts.c @@ -1,4 +1,4 @@ -/* usercerts.c -- Admin functions - user-certitificate table +/* usercerts.c -- Admin functions - user-certificate table * * GPLv2 only - Copyright (C) 2008, 2009 * David Sommerseth @@ -19,6 +19,15 @@ * */ +/** + * @file sqlite/administration/usercerts.c + * @author David Sommerseth + * @date 2009-08-29 + * + * @brief Functions for working with the openvpn_usercerts table + * + */ + #include #include #include @@ -50,6 +59,16 @@ void xmlReplaceChars(xmlChar *str, char s, char r); + +/** + * Internal function. Queries the database for a list of user-certificate links + * + * @param ctx eurephiaCTX + * @param where_m eDBfieldMap containing the search criteria + * @param sortkeys String containing the sort order of the data + * + * @return Returns a valid eurephia XML document on success, otherwise NULL + */ xmlDoc *usercerts_search(eurephiaCTX *ctx, eDBfieldMap *where_m, const char *sortkeys) { xmlDoc *list_xml = NULL; xmlNode *link_root_n = NULL, *link_n = NULL, *tmp_n = NULL; @@ -126,6 +145,15 @@ xmlDoc *usercerts_search(eurephiaCTX *ctx, eDBfieldMap *where_m, const char *sor } +/** + * Internal function. Adds or deletes a user-certificate link + * + * @param ctx eurephiaCTX + * @param mode String containing the operation mode. Must be "register" or "remove" + * @param usrcrt_m eDBfieldMap containing information about the link to add or remove + * + * @return Returns an eurephia ResultMsg XML document, with success message or an error message + */ xmlDoc *usercerts_add_del(eurephiaCTX *ctx, const char *mode, eDBfieldMap *usrcrt_m) { xmlDoc *res = NULL; dbresult *dbres = NULL; @@ -168,6 +196,16 @@ xmlDoc *usercerts_add_del(eurephiaCTX *ctx, const char *mode, eDBfieldMap *usrcr } +/** + * Internal function. Updates a user-certs link in the database + * + * @param ctx eurephiaCTX + * @param uicid String containing the numeric record ID (uicid field) of the record to be updated + * @param usrcrt_m eDBfieldMap containing the new information for the record. Only the fields being + * changed needs to be set. + * + * @return Returns an eurephia ResultMsg XML document, with success message or an error message + */ xmlDoc *usercerts_update(eurephiaCTX *ctx, const char *uicid, eDBfieldMap *usrcrt_m) { xmlNode *where_n = NULL; eDBfieldMap *where_m = NULL; @@ -215,19 +253,9 @@ xmlDoc *usercerts_update(eurephiaCTX *ctx, const char *uicid, eDBfieldMap *usrcr } -// The XML document format: -// -// -// -// <{field name}>{search value} -// -// [{field name}[, {field name},...]] -// -// -// It can be several field name tags to limit the search even more. -// If mode is 'update' the 'uicid' attribute must be present in the usercerts tag. -// +/** + * @copydoc eDBadminUserCertsLink() + */ xmlDoc *eDBadminUserCertsLink(eurephiaCTX *ctx, xmlDoc *usrcrt_xml) { xmlNode *usrcrt_n = NULL, *tmp_n = NULL; xmlDoc *resxml = NULL; -- cgit