gnunet_datacache_plugin.h (5021B)
1 /* 2 This file is part of GNUnet 3 Copyright (C) 2006, 2009, 2015, 2022 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 dht_libs DHT and support libraries 23 * @{ 24 * 25 * @author Christian Grothoff 26 * 27 * @file 28 * API for database backends for the datacache 29 * 30 * @defgroup datacache-plugin Data Cache plugin API 31 * API for database backends for the datacache 32 * @{ 33 */ 34 #ifndef PLUGIN_DATACACHE_H 35 #define PLUGIN_DATACACHE_H 36 37 38 #include "gnunet_datacache_lib.h" 39 40 #ifdef __cplusplus 41 extern "C" 42 { 43 #if 0 /* keep Emacsens' auto-indent happy */ 44 } 45 #endif 46 #endif 47 48 49 /** 50 * Function called by plugins to notify the datacache 51 * about content deletions. 52 * 53 * @param cls closure 54 * @param key key of the content that was deleted 55 * @param size number of bytes that were made available 56 */ 57 typedef void 58 (*GNUNET_DATACACHE_DeleteNotifyCallback) (void *cls, 59 const struct GNUNET_HashCode *key, 60 size_t size); 61 62 63 /** 64 * The datastore service will pass a pointer to a struct 65 * of this type as the first and only argument to the 66 * entry point of each datastore plugin. 67 */ 68 struct GNUNET_DATACACHE_PluginEnvironment 69 { 70 /** 71 * Configuration to use. 72 */ 73 const struct GNUNET_CONFIGURATION_Handle *cfg; 74 75 /** 76 * Configuration section to use. 77 */ 78 const char *section; 79 80 /** 81 * Closure to use for callbacks. 82 */ 83 void *cls; 84 85 /** 86 * Function to call whenever the plugin needs to 87 * discard content that it was asked to store. 88 */ 89 GNUNET_DATACACHE_DeleteNotifyCallback delete_notify; 90 91 /** 92 * How much space are we allowed to use? 93 */ 94 unsigned long long quota; 95 }; 96 97 98 /** 99 * @brief struct returned by the initialization function of the plugin 100 */ 101 struct GNUNET_DATACACHE_PluginFunctions 102 { 103 /** 104 * Closure to pass to all plugin functions. 105 */ 106 void *cls; 107 108 /** 109 * Store an item in the datastore. 110 * 111 * @param cls closure (internal context for the plugin) 112 * @param xor_distance how close is @a key to our PID? 113 * @param block data to store 114 * @return 0 if duplicate, -1 on error, number of bytes used otherwise 115 */ 116 ssize_t 117 (*put) (void *cls, 118 uint32_t xor_distance, 119 const struct GNUNET_DATACACHE_Block *block); 120 121 122 /** 123 * Iterate over the results for a particular key 124 * in the datastore. 125 * 126 * @param cls closure (internal context for the plugin) 127 * @param key key to look for 128 * @param type entries of which type are relevant? 129 * @param iter maybe NULL (to just count) 130 * @param iter_cls closure for @a iter 131 * @return the number of results found 132 */ 133 unsigned int 134 (*get) (void *cls, 135 const struct GNUNET_HashCode *key, 136 enum GNUNET_BLOCK_Type type, 137 GNUNET_DATACACHE_Iterator iter, 138 void *iter_cls); 139 140 141 /** 142 * Delete the entry with the lowest expiration value 143 * from the datacache right now. 144 * 145 * @param cls closure (internal context for the plugin) 146 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 147 */ 148 enum GNUNET_GenericReturnValue 149 (*del)(void *cls); 150 151 152 /** 153 * Iterate over the results that are "close" to a particular key in the 154 * datacache. "close" is defined as returning the @a num_results that are 155 * numerically closest and larger than @a key and also @a num_results that 156 * are numerically lower than @a key. Thus, the maximum number of results 157 * returned is actually twice @a num_results. 158 * 159 * @param cls closure (internal context for the plugin) 160 * @param key area of the keyspace to look into 161 * @param type desired block type for the replies 162 * @param num_results half the number of results that should be returned to @a iter 163 * @param iter maybe NULL (to just count) 164 * @param iter_cls closure for @a iter 165 * @return the number of results found 166 */ 167 unsigned int 168 (*get_closest) (void *cls, 169 const struct GNUNET_HashCode *key, 170 enum GNUNET_BLOCK_Type type, 171 unsigned int num_results, 172 GNUNET_DATACACHE_Iterator iter, 173 void *iter_cls); 174 }; 175 176 177 #if 0 /* keep Emacsens' auto-indent happy */ 178 { 179 #endif 180 #ifdef __cplusplus 181 } 182 #endif 183 184 #endif 185 186 /** @} */ /* end of group */ 187 188 /** @} */ /* end of group addition */