gnunet_namestore_plugin.h (9432B)
1 /* 2 This file is part of GNUnet 3 Copyright (C) 2012, 2013, 2018 GNUnet e.V. 4 5 GNUnet is free software: you can redistribute it and/or modify it 6 under the terms of the GNU Affero General Public License as published 7 by the Free Software Foundation, either version 3 of the License, 8 or (at your option) any later version. 9 10 GNUnet is distributed in the hope that it will be useful, but 11 WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Affero General Public License for more details. 14 15 You should have received a copy of the GNU Affero General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 /** 22 * @addtogroup GNS 23 * @{ 24 * 25 * @author Christian Grothoff 26 * 27 * @file 28 * Plugin API for the namestore database backend 29 * 30 * @defgroup namestore-plugin Name Store service plugin API 31 * Plugin API for the namestore database backend 32 * @{ 33 */ 34 #ifndef GNUNET_NAMESTORE_PLUGIN_H 35 #define GNUNET_NAMESTORE_PLUGIN_H 36 37 38 #include "gnunet_util_lib.h" 39 #include "gnunet_namestore_service.h" 40 41 #ifdef __cplusplus 42 extern "C" 43 { 44 #if 0 /* keep Emacsens' auto-indent happy */ 45 } 46 #endif 47 #endif 48 49 50 /** 51 * Function called for each matching record. 52 * 53 * @param cls closure 54 * @param serial unique serial number of the record, MUST NOT BE ZERO, 55 * and must be monotonically increasing while iterating 56 * @param editor_hint content of the editor field when record was read (may be NULL) 57 * @param zone_key private key of the zone 58 * @param label name that is being mapped (at most 255 characters long) 59 * @param rd_count number of entries in @a rd array 60 * @param rd array of records with data to store 61 */ 62 typedef void 63 (*GNUNET_NAMESTORE_RecordIterator) (void *cls, 64 uint64_t serial, 65 const char *editor_hint, 66 const struct 67 GNUNET_CRYPTO_PrivateKey *private_key, 68 const char *label, 69 unsigned int rd_count, 70 const struct GNUNET_GNSRECORD_Data *rd); 71 72 73 /** 74 * @brief struct returned by the initialization function of the plugin 75 */ 76 struct GNUNET_NAMESTORE_PluginFunctions 77 { 78 /** 79 * Closure to pass to all plugin functions. 80 */ 81 void *cls; 82 83 /** 84 * Store a record in the datastore for which we are the authority. 85 * Removes any existing record in the same zone with the same name. 86 * 87 * @param cls closure (internal context for the plugin) 88 * @param zone private key of the zone 89 * @param label name of the record in the zone 90 * @param rd_count number of entries in @a rd array, 0 to delete all records 91 * @param rd array of records with data to store 92 * @return #GNUNET_OK on success, else #GNUNET_SYSERR 93 */ 94 enum GNUNET_GenericReturnValue 95 (*store_records)(void *cls, 96 const struct GNUNET_CRYPTO_PrivateKey *zone, 97 const char *label, 98 unsigned int rd_count, 99 const struct GNUNET_GNSRECORD_Data *rd); 100 101 /** 102 * Lookup records in the datastore for which we are the authority. 103 * 104 * @param cls closure (internal context for the plugin) 105 * @param zone private key of the zone 106 * @param label name of the record in the zone 107 * @param iter function to call with the result 108 * @param iter_cls closure for @a iter 109 * @return #GNUNET_OK on success, #GNUNET_NO for no results, else #GNUNET_SYSERR 110 */ 111 enum GNUNET_GenericReturnValue 112 (*lookup_records)(void *cls, 113 const struct GNUNET_CRYPTO_PrivateKey *zone, 114 const char *label, 115 GNUNET_NAMESTORE_RecordIterator iter, 116 void *iter_cls); 117 118 119 /** 120 * Iterate over the results for a particular zone in the 121 * datastore. Will return at most @a limit results to the iterator. 122 * 123 * @param cls closure (internal context for the plugin) 124 * @param zone private key of the zone, NULL for all zones 125 * @param serial serial (to exclude) in the list of matching records; 126 * 0 means to exclude nothing; results must be returned using 127 * the minimum possible sequence number first (ordered by serial) 128 * @param limit maximum number of results to return to @a iter 129 * @param iter function to call with the result 130 * @param iter_cls closure for @a iter 131 * @return #GNUNET_OK on success, #GNUNET_NO if there were no more results, #GNUNET_SYSERR on error 132 */ 133 enum GNUNET_GenericReturnValue 134 (*iterate_records)(void *cls, 135 const struct GNUNET_CRYPTO_PrivateKey *zone, 136 uint64_t serial, 137 uint64_t limit, 138 GNUNET_NAMESTORE_RecordIterator iter, 139 void *iter_cls); 140 141 142 /** 143 * Look for an existing PKEY delegation record for a given public key. 144 * Returns at most one result to the iterator. 145 * 146 * @param cls closure (internal context for the plugin) 147 * @param zone private key of the zone to look up in, never NULL 148 * @param value_zone public key of the target zone (value), never NULL 149 * @param iter function to call with the result 150 * @param iter_cls closure for @a iter 151 * @return #GNUNET_OK on success, #GNUNET_NO if there were no results, #GNUNET_SYSERR on error 152 */ 153 enum GNUNET_GenericReturnValue 154 (*zone_to_name)(void *cls, 155 const struct GNUNET_CRYPTO_PrivateKey *zone, 156 const struct GNUNET_CRYPTO_PublicKey *value_zone, 157 GNUNET_NAMESTORE_RecordIterator iter, 158 void *iter_cls); 159 160 /** Transaction-based API draft **/ 161 162 /** 163 * Edit records in the namestore. 164 * This modifies the editor hint, an advisory lock entry. 165 * The record iterator will be called with the old editor hint (if any). 166 * 167 * @param cls closure (internal context for the plugin) 168 * @param zone private key of the zone 169 * @param editor_hint the new value for the advisory lock field 170 * @param label name of the record in the zone 171 * @param iter function to call with the result 172 * @param iter_cls closure for @a iter 173 * @return #GNUNET_OK on success, #GNUNET_NO for no results, else #GNUNET_SYSERR 174 */ 175 enum GNUNET_GenericReturnValue 176 (*edit_records)(void *cls, 177 const char *editor_hint, 178 const struct GNUNET_CRYPTO_PrivateKey *zone, 179 const char *label, 180 GNUNET_NAMESTORE_RecordIterator iter, 181 void *iter_cls); 182 183 /** 184 * This clears the editor hint, unless it does not match the 185 * given editor hint, in which case this is a NOP. 186 * If a replacement hint is given, it hint is not cleared, but 187 * set to the replacement. 188 * 189 * @param cls closure (internal context for the plugin) 190 * @param zone private key of the zone 191 * @param editor_hint the new value for the advisory lock field 192 * @param editor_hint_replacement an optional value to use instead of a clear 193 * @param label name of the record in the zone 194 * @param iter function to call with the result 195 * @param iter_cls closure for @a iter 196 * @return #GNUNET_OK on success, #GNUNET_NO for no results, else #GNUNET_SYSERR 197 */ 198 enum GNUNET_GenericReturnValue 199 (*clear_editor_hint)(void *cls, 200 const char *editor_hint, 201 const char *editor_hint_replacement, 202 const struct GNUNET_CRYPTO_PrivateKey *zone, 203 const char *label); 204 205 /** 206 * Tell plugin that a set of procedures are coming that 207 * are ideally handled within a single TX (BEGIN/COMMIT). 208 * This may be implemented as a NOP, but can speed up 209 * store calls in some cases (e.g. SQL databases) 210 * 211 * @param cls closure (internal context for the plugin) 212 * @return #GNUNET_OK on success, else fails with #GNUNET_SYSERR 213 */ 214 enum GNUNET_GenericReturnValue 215 (*begin_tx)(void *cls); 216 217 /** 218 * Tell plugin the we finished what we started with 219 * #begin_tx 220 * 221 * @param cls closure (internal context for the plugin) 222 * @return #GNUNET_OK on success, else fails with #GNUNET_SYSERR 223 */ 224 enum GNUNET_GenericReturnValue 225 (*commit_tx)(void *cls); 226 227 /** 228 * Tell plugin to rollback what we started with 229 * #begin_tx 230 * This may be a NOP (and thus NOT roll anything back!) 231 * 232 * @param cls closure (internal context for the plugin) 233 * @return #GNUNET_OK on success, else fails with #GNUNET_SYSERR 234 */ 235 enum GNUNET_GenericReturnValue 236 (*rollback_tx)(void *cls); 237 238 /** 239 * Setup the database. 240 * 241 * @param cls closure (internal context for the plugin) 242 * @return #GNUNET_OK on success, else fails with #GNUNET_SYSERR 243 */ 244 enum GNUNET_GenericReturnValue 245 (*create_tables)(void *cls); 246 247 248 /** 249 * Drop existing tables. 250 * DANGEROUS: All existing data in the database will be lost! 251 * 252 * @param cls closure (internal context for the plugin) 253 * @return #GNUNET_OK on success, else fails with #GNUNET_SYSERR 254 */ 255 enum GNUNET_GenericReturnValue 256 (*drop_tables)(void *cls); 257 }; 258 259 260 #if 0 /* keep Emacsens' auto-indent happy */ 261 { 262 #endif 263 #ifdef __cplusplus 264 } 265 #endif 266 267 #endif 268 269 /** @} */ /* end of group */ 270 271 /** @} */ /* end of group addition */