src/include/gnunet_namecache_service.h

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