gnunet_namecache_service.h (5150B)
1 /* 2 This file is part of GNUnet 3 Copyright (C) 2012, 2013, 2016 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 * API that can be used to store naming information on a GNUnet node. 29 * 30 * @defgroup namecache Name Cache service 31 * Store naming information on a GNUnet node. 32 * 33 * Naming information can either be records for which this peer/user is 34 * authoritative, or blocks which are cached, encrypted naming data from other 35 * peers. 36 * 37 * @see [Documentation](https://gnunet.org/namecache-subsystem) 38 * 39 * @{ 40 */ 41 #ifndef GNUNET_NAMECACHE_SERVICE_H 42 #define GNUNET_NAMECACHE_SERVICE_H 43 44 45 #include "gnunet_util_lib.h" 46 #include "gnunet_block_lib.h" 47 #include "gnunet_namestore_service.h" 48 49 #ifdef __cplusplus 50 extern "C" 51 { 52 #if 0 /* keep Emacsens' auto-indent happy */ 53 } 54 #endif 55 #endif 56 57 58 /** 59 * Entry in the queue. 60 */ 61 struct GNUNET_NAMECACHE_QueueEntry; 62 63 /** 64 * Handle to the namecache service. 65 */ 66 struct GNUNET_NAMECACHE_Handle; 67 68 /** 69 * Maximum size of a value that can be stored in the namecache. 70 */ 71 #define GNUNET_NAMECACHE_MAX_VALUE_SIZE (63 * 1024) 72 73 74 /** 75 * Connect to the namecache service. 76 * 77 * @param cfg configuration to use 78 * @return handle to use to access the service 79 */ 80 struct GNUNET_NAMECACHE_Handle * 81 GNUNET_NAMECACHE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); 82 83 84 /** 85 * Disconnect from the namecache service (and free associated 86 * resources). Must not be called from within operation callbacks of 87 * the API. 88 * 89 * @param h handle to the namecache 90 */ 91 void 92 GNUNET_NAMECACHE_disconnect (struct GNUNET_NAMECACHE_Handle *h); 93 94 95 /** 96 * Continuation called to notify client about result of the 97 * operation. 98 * 99 * @param cls closure 100 * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate) 101 * #GNUNET_NO if content was already there or not found 102 * #GNUNET_YES (or other positive value) on success 103 * @param emsg NULL on success, otherwise an error message 104 */ 105 typedef void 106 (*GNUNET_NAMECACHE_ContinuationWithStatus) (void *cls, 107 int32_t success, 108 const char *emsg); 109 110 111 /** 112 * Store an item in the namecache. If the item is already present, 113 * it is replaced with the new record. 114 * 115 * @param h handle to the namecache 116 * @param block block to store 117 * @param cont continuation to call when done 118 * @param cont_cls closure for @a cont 119 * @return handle to abort the request, NULL on error 120 */ 121 struct GNUNET_NAMECACHE_QueueEntry * 122 GNUNET_NAMECACHE_block_cache (struct GNUNET_NAMECACHE_Handle *h, 123 const struct GNUNET_GNSRECORD_Block *block, 124 GNUNET_NAMECACHE_ContinuationWithStatus cont, 125 void *cont_cls); 126 127 128 /** 129 * Process a record that was stored in the namecache. 130 * 131 * @param cls closure 132 * @param block block that was stored in the namecache 133 */ 134 typedef void 135 (*GNUNET_NAMECACHE_BlockProcessor) (void *cls, 136 const struct GNUNET_GNSRECORD_Block *block); 137 138 139 /** 140 * Get a result for a particular key from the namecache. The processor 141 * will only be called once. 142 * 143 * @param h handle to the namecache 144 * @param derived_hash hash of zone key combined with name to lookup 145 * then at the end once with NULL 146 * @param proc function to call on the matching block, or with 147 * NULL if there is no matching block 148 * @param proc_cls closure for @a proc 149 * @return a handle that can be used to cancel, NULL on error 150 */ 151 struct GNUNET_NAMECACHE_QueueEntry * 152 GNUNET_NAMECACHE_lookup_block (struct GNUNET_NAMECACHE_Handle *h, 153 const struct GNUNET_HashCode *derived_hash, 154 GNUNET_NAMECACHE_BlockProcessor proc, 155 void *proc_cls); 156 157 158 /** 159 * Cancel a namecache operation. The final callback from the 160 * operation must not have been done yet. Must be called on any 161 * namecache operation that has not yet completed prior to calling 162 * #GNUNET_NAMECACHE_disconnect. 163 * 164 * @param qe operation to cancel 165 */ 166 void 167 GNUNET_NAMECACHE_cancel (struct GNUNET_NAMECACHE_QueueEntry *qe); 168 169 170 #if 0 /* keep Emacsens' auto-indent happy */ 171 { 172 #endif 173 #ifdef __cplusplus 174 } 175 #endif 176 177 #endif 178 179 /** @} */ /* end of group */ 180 181 /** @} */ /* end of group addition */