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