From d9dcf9e5754ba3dadb7a6e75b2056863f21b84b4 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 29 Apr 2015 07:49:04 +0000 Subject: [PATCH] -doxygen, updating template to reflect extended API --- src/datacache/plugin_datacache_sqlite.c | 97 +++++++++++++++-------- src/datacache/plugin_datacache_template.c | 62 ++++++++++----- src/include/gnunet_datacache_plugin.h | 2 +- 3 files changed, 108 insertions(+), 53 deletions(-) diff --git a/src/datacache/plugin_datacache_sqlite.c b/src/datacache/plugin_datacache_sqlite.c index 90b33d877..fe6daf4dd 100644 --- a/src/datacache/plugin_datacache_sqlite.c +++ b/src/datacache/plugin_datacache_sqlite.c @@ -67,22 +67,37 @@ struct Plugin /** - * Log an error message at log-level 'level' that indicates - * a failure of the command 'cmd' on file 'filename' - * with the message given by strerror(errno). + * Log an error message at log-level @a level that indicates + * a failure of the command @a cmd with the error from the database @a db + * + * @param db database handle + * @param level log level + * @param cmd failed command */ #define LOG_SQLITE(db, level, cmd) do { LOG (level, _("`%s' failed at %s:%d with error: %s\n"), cmd, __FILE__, __LINE__, sqlite3_errmsg(db)); } while(0) +/** + * Execute SQL statement. + * + * @param db database handle + * @param cmd SQL command to execute + */ #define SQLITE3_EXEC(db, cmd) do { emsg = NULL; if (SQLITE_OK != sqlite3_exec(db, cmd, NULL, NULL, &emsg)) { LOG (GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, _("`%s' failed at %s:%d with error: %s\n"), "sqlite3_exec", __FILE__, __LINE__, emsg); sqlite3_free(emsg); } } while(0) /** * @brief Prepare a SQL statement + * + * @param dbh database handle + * @param zsql SQL statement text + * @param[out] ppStmt set to the prepared statement + * @return 0 on success */ static int -sq_prepare (sqlite3 * dbh, const char *zSql, /* SQL statement, UTF-8 encoded */ - sqlite3_stmt ** ppStmt) +sq_prepare (sqlite3 *dbh, + const char *zSql, /* SQL statement, UTF-8 encoded */ + sqlite3_stmt **ppStmt) { /* OUT: Statement handle */ char *dummy; @@ -94,9 +109,9 @@ sq_prepare (sqlite3 * dbh, const char *zSql, /* SQL statement, UTF-8 encoded /** * Store an item in the datastore. * - * @param cls closure (our "struct Plugin") + * @param cls closure (our `struct Plugin`) * @param key key to store data under - * @param size number of bytes in data + * @param size number of bytes in @a data * @param data data to store * @param type type of the value * @param discard_time when to discard the value in any case @@ -107,7 +122,8 @@ sq_prepare (sqlite3 * dbh, const char *zSql, /* SQL statement, UTF-8 encoded static ssize_t sqlite_plugin_put (void *cls, const struct GNUNET_HashCode *key, - size_t size, const char *data, + size_t size, + const char *data, enum GNUNET_BLOCK_Type type, struct GNUNET_TIME_Absolute discard_time, unsigned int path_info_len, @@ -118,8 +134,9 @@ sqlite_plugin_put (void *cls, int64_t dval; LOG (GNUNET_ERROR_TYPE_DEBUG, - "Processing `%s' of %u bytes with key `%4s' and expiration %s\n", - "PUT", (unsigned int) size, GNUNET_h2s (key), + "Processing PUT of %u bytes with key `%4s' and expiration %s\n", + (unsigned int) size, + GNUNET_h2s (key), GNUNET_STRINGS_relative_time_to_string (GNUNET_TIME_absolute_get_remaining (discard_time), GNUNET_YES)); dval = (int64_t) discard_time.abs_value_us; if (dval < 0) @@ -129,7 +146,8 @@ sqlite_plugin_put (void *cls, "INSERT INTO ds090 (type, expire, key, value, path) VALUES (?, ?, ?, ?, ?)", &stmt) != SQLITE_OK) { - LOG_SQLITE (plugin->dbh, GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, + LOG_SQLITE (plugin->dbh, + GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, "sq_prepare"); return -1; } @@ -147,21 +165,24 @@ sqlite_plugin_put (void *cls, path_info_len * sizeof (struct GNUNET_PeerIdentity), SQLITE_TRANSIENT))) { - LOG_SQLITE (plugin->dbh, GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, + LOG_SQLITE (plugin->dbh, + GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, "sqlite3_bind_xxx"); sqlite3_finalize (stmt); return -1; } if (SQLITE_DONE != sqlite3_step (stmt)) { - LOG_SQLITE (plugin->dbh, GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, + LOG_SQLITE (plugin->dbh, + GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, "sqlite3_step"); sqlite3_finalize (stmt); return -1; } plugin->num_items++; if (SQLITE_OK != sqlite3_finalize (stmt)) - LOG_SQLITE (plugin->dbh, GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, + LOG_SQLITE (plugin->dbh, + GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, "sqlite3_finalize"); return size + OVERHEAD; } @@ -171,16 +192,18 @@ sqlite_plugin_put (void *cls, * Iterate over the results for a particular key * in the datastore. * - * @param cls closure (our "struct Plugin") + * @param cls closure (our `struct Plugin`) * @param key * @param type entries of which type are relevant? * @param iter maybe NULL (to just count) - * @param iter_cls closure for iter + * @param iter_cls closure for @a iter * @return the number of results found */ static unsigned int -sqlite_plugin_get (void *cls, const struct GNUNET_HashCode * key, - enum GNUNET_BLOCK_Type type, GNUNET_DATACACHE_Iterator iter, +sqlite_plugin_get (void *cls, + const struct GNUNET_HashCode *key, + enum GNUNET_BLOCK_Type type, + GNUNET_DATACACHE_Iterator iter, void *iter_cls) { struct Plugin *plugin = cls; @@ -198,14 +221,16 @@ sqlite_plugin_get (void *cls, const struct GNUNET_HashCode * key, const struct GNUNET_PeerIdentity *path; now = GNUNET_TIME_absolute_get (); - LOG (GNUNET_ERROR_TYPE_DEBUG, "Processing `%s' for key `%4s'\n", "GET", + LOG (GNUNET_ERROR_TYPE_DEBUG, + "Processing GET for key `%4s'\n", GNUNET_h2s (key)); if (sq_prepare (plugin->dbh, "SELECT count(*) FROM ds090 WHERE key=? AND type=? AND expire >= ?", &stmt) != SQLITE_OK) { - LOG_SQLITE (plugin->dbh, GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, + LOG_SQLITE (plugin->dbh, + GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, "sq_prepare"); return 0; } @@ -217,7 +242,8 @@ sqlite_plugin_get (void *cls, const struct GNUNET_HashCode * key, (SQLITE_OK != sqlite3_bind_int (stmt, 2, type)) || (SQLITE_OK != sqlite3_bind_int64 (stmt, 3, now.abs_value_us))) { - LOG_SQLITE (plugin->dbh, GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, + LOG_SQLITE (plugin->dbh, + GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, "sqlite3_bind_xxx"); sqlite3_finalize (stmt); return 0; @@ -229,7 +255,7 @@ sqlite_plugin_get (void *cls, const struct GNUNET_HashCode * key, "sqlite_step"); sqlite3_finalize (stmt); LOG (GNUNET_ERROR_TYPE_DEBUG, - "No content found when processing `%s' for key `%4s'\n", "GET", + "No content found when processing GET for key `%4s'\n", GNUNET_h2s (key)); return 0; } @@ -239,7 +265,7 @@ sqlite_plugin_get (void *cls, const struct GNUNET_HashCode * key, { if (0 == total) LOG (GNUNET_ERROR_TYPE_DEBUG, - "No content found when processing `%s' for key `%4s'\n", "GET", + "No content found when processing GET for key `%4s'\n", GNUNET_h2s (key)); return total; } @@ -254,17 +280,21 @@ sqlite_plugin_get (void *cls, const struct GNUNET_HashCode * key, off); if (sq_prepare (plugin->dbh, scratch, &stmt) != SQLITE_OK) { - LOG_SQLITE (plugin->dbh, GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, + LOG_SQLITE (plugin->dbh, + GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, "sq_prepare"); return cnt; } if ((SQLITE_OK != - sqlite3_bind_blob (stmt, 1, key, sizeof (struct GNUNET_HashCode), + sqlite3_bind_blob (stmt, 1, + key, + sizeof (struct GNUNET_HashCode), SQLITE_TRANSIENT)) || (SQLITE_OK != sqlite3_bind_int (stmt, 2, type)) || (SQLITE_OK != sqlite3_bind_int64 (stmt, 3, now.abs_value_us))) { - LOG_SQLITE (plugin->dbh, GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, + LOG_SQLITE (plugin->dbh, + GNUNET_ERROR_TYPE_ERROR | GNUNET_ERROR_TYPE_BULK, "sqlite3_bind_xxx"); sqlite3_finalize (stmt); return cnt; @@ -290,8 +320,9 @@ sqlite_plugin_get (void *cls, const struct GNUNET_HashCode * key, exp = GNUNET_TIME_UNIT_FOREVER_ABS; cnt++; LOG (GNUNET_ERROR_TYPE_DEBUG, - "Found %u-byte result when processing `%s' for key `%4s'\n", - (unsigned int) size, "GET", GNUNET_h2s (key)); + "Found %u-byte result when processing GET for key `%4s'\n", + (unsigned int) size, + GNUNET_h2s (key)); if (GNUNET_OK != iter (iter_cls, key, size, dat, type, exp, psize, path)) { sqlite3_finalize (stmt); @@ -307,8 +338,8 @@ sqlite_plugin_get (void *cls, const struct GNUNET_HashCode * key, * Delete the entry with the lowest expiration value * from the datacache right now. * - * @param cls closure (our "struct Plugin") - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @param cls closure (our `struct Plugin`) + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ static int sqlite_plugin_del (void *cls) @@ -383,8 +414,8 @@ sqlite_plugin_del (void *cls) /** * Entry point for the plugin. * - * @param cls closure (the "struct GNUNET_DATACACHE_PluginEnvironmnet") - * @return the plugin's closure (our "struct Plugin") + * @param cls closure (the `struct GNUNET_DATACACHE_PluginEnvironmnet`) + * @return the plugin's closure (our `struct Plugin`) */ void * libgnunet_plugin_datacache_sqlite_init (void *cls) @@ -461,7 +492,7 @@ libgnunet_plugin_datacache_sqlite_init (void *cls) /** * Exit point from the plugin. * - * @param cls closure (our "struct Plugin") + * @param cls closure (our `struct Plugin`) * @return NULL */ void * diff --git a/src/datacache/plugin_datacache_template.c b/src/datacache/plugin_datacache_template.c index ff0119e69..86e0675c1 100644 --- a/src/datacache/plugin_datacache_template.c +++ b/src/datacache/plugin_datacache_template.c @@ -1,6 +1,6 @@ /* This file is part of GNUnet - Copyright (C) 2006, 2009 Christian Grothoff (and other contributing authors) + Copyright (C) 2006, 2009, 2015 Christian Grothoff (and other contributing authors) GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -43,19 +43,22 @@ struct Plugin /** * Store an item in the datastore. * - * @param cls closure (our "struct Plugin") - * @param key key to store data under - * @param size number of bytes in data + * @param cls closure (our `struct Plugin`) + * @param key key to store @a data under + * @param size number of bytes in @a data * @param data data to store * @param type type of the value * @param discard_time when to discard the value in any case - * @param path_info_len number of entries in 'path_info' + * @param path_info_len number of entries in @a path_info * @param path_info a path through the network * @return 0 if duplicate, -1 on error, number of bytes used otherwise */ static ssize_t -template_plugin_put (void *cls, const struct GNUNET_HashCode * key, size_t size, - const char *data, enum GNUNET_BLOCK_Type type, +template_plugin_put (void *cls, + const struct GNUNET_HashCode *key, + size_t size, + const char *data, + enum GNUNET_BLOCK_Type type, struct GNUNET_TIME_Absolute discard_time, unsigned int path_info_len, const struct GNUNET_PeerIdentity *path_info) @@ -69,17 +72,19 @@ template_plugin_put (void *cls, const struct GNUNET_HashCode * key, size_t size, * Iterate over the results for a particular key * in the datastore. * - * @param cls closure (our "struct Plugin") + * @param cls closure (our `struct Plugin`) * @param key * @param type entries of which type are relevant? * @param iter maybe NULL (to just count) - * @param iter_cls closure for iter + * @param iter_cls closure for @a iter * @return the number of results found */ static unsigned int -template_plugin_get (void *cls, const struct GNUNET_HashCode * key, +template_plugin_get (void *cls, + const struct GNUNET_HashCode *key, enum GNUNET_BLOCK_Type type, - GNUNET_DATACACHE_Iterator iter, void *iter_cls) + GNUNET_DATACACHE_Iterator iter, + void *iter_cls) { GNUNET_break (0); return 0; @@ -90,8 +95,8 @@ template_plugin_get (void *cls, const struct GNUNET_HashCode * key, * Delete the entry with the lowest expiration value * from the datacache right now. * - * @param cls closure (our "struct Plugin") - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @param cls closure (our `struct Plugin`) + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ static int template_plugin_del (void *cls) @@ -101,11 +106,29 @@ template_plugin_del (void *cls) } +/** + * Return a random value from the datastore. + * + * @param cls closure (internal context for the plugin) + * @param iter maybe NULL (to just count) + * @param iter_cls closure for @a iter + * @return the number of results found (zero or one) + */ +static unsigned int +template_get_random (void *cls, + GNUNET_DATACACHE_Iterator iter, + void *iter_cls) +{ + GNUNET_break (0); + return 0; +} + + /** * Entry point for the plugin. * - * @param cls closure (the "struct GNUNET_DATACACHE_PluginEnvironmnet") - * @return the plugin's closure (our "struct Plugin") + * @param cls closure (the `struct GNUNET_DATACACHE_PluginEnvironmnet`) + * @return the plugin's closure (our `struct Plugin`) */ void * libgnunet_plugin_datacache_template_init (void *cls) @@ -121,8 +144,10 @@ libgnunet_plugin_datacache_template_init (void *cls) api->get = &template_plugin_get; api->put = &template_plugin_put; api->del = &template_plugin_del; - GNUNET_log_from (GNUNET_ERROR_TYPE_INFO, "template", - _("Template datacache running\n")); + api->get_random = &template_plugin_get_random; + GNUNET_log_from (GNUNET_ERROR_TYPE_INFO, + "template", + "Template datacache running\n"); return api; } @@ -130,7 +155,7 @@ libgnunet_plugin_datacache_template_init (void *cls) /** * Exit point from the plugin. * - * @param cls closure (our "struct Plugin") + * @param cls closure (our `struct Plugin`) * @return NULL */ void * @@ -145,5 +170,4 @@ libgnunet_plugin_datacache_template_done (void *cls) } - /* end of plugin_datacache_template.c */ diff --git a/src/include/gnunet_datacache_plugin.h b/src/include/gnunet_datacache_plugin.h index 34cf8fecc..0810a41d9 100644 --- a/src/include/gnunet_datacache_plugin.h +++ b/src/include/gnunet_datacache_plugin.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet - Copyright (C) 2006, 2009 Christian Grothoff (and other contributing authors) + Copyright (C) 2006, 2009, 2015 Christian Grothoff (and other contributing authors) GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published -- 2.25.1