gnunet_namestore_plugin.h (9630B)
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_BlindablePrivateKey * 68 private_key, 69 const char *label, 70 unsigned int rd_count, 71 const struct GNUNET_GNSRECORD_Data *rd); 72 73 74 /** 75 * @brief struct returned by the initialization function of the plugin 76 */ 77 struct GNUNET_NAMESTORE_PluginFunctions 78 { 79 /** 80 * Closure to pass to all plugin functions. 81 */ 82 void *cls; 83 84 /** 85 * Store a record in the datastore for which we are the authority. 86 * Removes any existing record in the same zone with the same name. 87 * 88 * @param cls closure (internal context for the plugin) 89 * @param zone private key of the zone 90 * @param label name of the record in the zone 91 * @param rd_count number of entries in @a rd array, 0 to delete all records 92 * @param rd array of records with data to store 93 * @return #GNUNET_OK on success, else #GNUNET_SYSERR 94 */ 95 enum GNUNET_GenericReturnValue 96 (*store_records)(void *cls, 97 const struct GNUNET_CRYPTO_BlindablePrivateKey *zone, 98 const char *label, 99 unsigned int rd_count, 100 const struct GNUNET_GNSRECORD_Data *rd); 101 102 /** 103 * Lookup records in the datastore for which we are the authority. 104 * 105 * @param cls closure (internal context for the plugin) 106 * @param zone private key of the zone 107 * @param label name of the record in the zone 108 * @param iter function to call with the result 109 * @param iter_cls closure for @a iter 110 * @return #GNUNET_OK on success, #GNUNET_NO for no results, else #GNUNET_SYSERR 111 */ 112 enum GNUNET_GenericReturnValue 113 (*lookup_records)(void *cls, 114 const struct GNUNET_CRYPTO_BlindablePrivateKey *zone, 115 const char *label, 116 GNUNET_NAMESTORE_RecordIterator iter, 117 void *iter_cls); 118 119 120 /** 121 * Iterate over the results for a particular zone in the 122 * datastore. Will return at most @a limit results to the iterator. 123 * 124 * @param cls closure (internal context for the plugin) 125 * @param zone private key of the zone, NULL for all zones 126 * @param serial serial (to exclude) in the list of matching records; 127 * 0 means to exclude nothing; results must be returned using 128 * the minimum possible sequence number first (ordered by serial) 129 * @param limit maximum number of results to return to @a iter 130 * @param iter function to call with the result 131 * @param iter_cls closure for @a iter 132 * @return #GNUNET_OK on success, #GNUNET_NO if there were no more results, #GNUNET_SYSERR on error 133 */ 134 enum GNUNET_GenericReturnValue 135 (*iterate_records)(void *cls, 136 const struct GNUNET_CRYPTO_BlindablePrivateKey *zone, 137 uint64_t serial, 138 uint64_t limit, 139 GNUNET_NAMESTORE_RecordIterator iter, 140 void *iter_cls); 141 142 143 /** 144 * Look for an existing PKEY delegation record for a given public key. 145 * Returns at most one result to the iterator. 146 * 147 * @param cls closure (internal context for the plugin) 148 * @param zone private key of the zone to look up in, never NULL 149 * @param value_zone public key of the target zone (value), never NULL 150 * @param iter function to call with the result 151 * @param iter_cls closure for @a iter 152 * @return #GNUNET_OK on success, #GNUNET_NO if there were no results, #GNUNET_SYSERR on error 153 */ 154 enum GNUNET_GenericReturnValue 155 (*zone_to_name)(void *cls, 156 const struct GNUNET_CRYPTO_BlindablePrivateKey *zone, 157 const struct GNUNET_CRYPTO_BlindablePublicKey *value_zone, 158 GNUNET_NAMESTORE_RecordIterator iter, 159 void *iter_cls); 160 161 /** Transaction-based API draft **/ 162 163 /** 164 * Edit records in the namestore. 165 * This modifies the editor hint, an advisory lock entry. 166 * The record iterator will be called with the old editor hint (if any). 167 * 168 * @param cls closure (internal context for the plugin) 169 * @param zone private key of the zone 170 * @param editor_hint the new value for the advisory lock field 171 * @param label name of the record in the zone 172 * @param iter function to call with the result 173 * @param iter_cls closure for @a iter 174 * @return #GNUNET_OK on success, #GNUNET_NO for no results, else #GNUNET_SYSERR 175 */ 176 enum GNUNET_GenericReturnValue 177 (*edit_records)(void *cls, 178 const char *editor_hint, 179 const struct GNUNET_CRYPTO_BlindablePrivateKey *zone, 180 const char *label, 181 GNUNET_NAMESTORE_RecordIterator iter, 182 void *iter_cls); 183 184 /** 185 * This clears the editor hint, unless it does not match the 186 * given editor hint, in which case this is a NOP. 187 * If a replacement hint is given, it hint is not cleared, but 188 * set to the replacement. 189 * 190 * @param cls closure (internal context for the plugin) 191 * @param zone private key of the zone 192 * @param editor_hint the new value for the advisory lock field 193 * @param editor_hint_replacement an optional value to use instead of a clear 194 * @param label name of the record in the zone 195 * @param iter function to call with the result 196 * @param iter_cls closure for @a iter 197 * @return #GNUNET_OK on success, #GNUNET_NO for no results, else #GNUNET_SYSERR 198 */ 199 enum GNUNET_GenericReturnValue 200 (*clear_editor_hint)(void *cls, 201 const char *editor_hint, 202 const char *editor_hint_replacement, 203 const struct GNUNET_CRYPTO_BlindablePrivateKey *zone, 204 const char *label); 205 206 /** 207 * Tell plugin that a set of procedures are coming that 208 * are ideally handled within a single TX (BEGIN/COMMIT). 209 * This may be implemented as a NOP, but can speed up 210 * store calls in some cases (e.g. SQL databases) 211 * 212 * @param cls closure (internal context for the plugin) 213 * @return #GNUNET_OK on success, else fails with #GNUNET_SYSERR 214 */ 215 enum GNUNET_GenericReturnValue 216 (*begin_tx)(void *cls); 217 218 /** 219 * Tell plugin the we finished what we started with 220 * #begin_tx 221 * 222 * @param cls closure (internal context for the plugin) 223 * @return #GNUNET_OK on success, else fails with #GNUNET_SYSERR 224 */ 225 enum GNUNET_GenericReturnValue 226 (*commit_tx)(void *cls); 227 228 /** 229 * Tell plugin to rollback what we started with 230 * #begin_tx 231 * This may be a NOP (and thus NOT roll anything back!) 232 * 233 * @param cls closure (internal context for the plugin) 234 * @return #GNUNET_OK on success, else fails with #GNUNET_SYSERR 235 */ 236 enum GNUNET_GenericReturnValue 237 (*rollback_tx)(void *cls); 238 239 /** 240 * Setup the database. 241 * 242 * @param cls closure (internal context for the plugin) 243 * @return #GNUNET_OK on success, else fails with #GNUNET_SYSERR 244 */ 245 enum GNUNET_GenericReturnValue 246 (*create_tables)(void *cls); 247 248 249 /** 250 * Drop existing tables. 251 * DANGEROUS: All existing data in the database will be lost! 252 * 253 * @param cls closure (internal context for the plugin) 254 * @return #GNUNET_OK on success, else fails with #GNUNET_SYSERR 255 */ 256 enum GNUNET_GenericReturnValue 257 (*drop_tables)(void *cls); 258 }; 259 260 261 #if 0 /* keep Emacsens' auto-indent happy */ 262 { 263 #endif 264 #ifdef __cplusplus 265 } 266 #endif 267 268 #endif 269 270 /** @} */ /* end of group */ 271 272 /** @} */ /* end of group addition */