src/include/gnunet_namestore_service.h

   1 /*
   2      This file is part of GNUnet
   3      (C) 2012 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 2, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_namestore_service.h
  23  * @brief API that can be used to store naming information on a GNUnet node;
  24  * @author Christian Grothoff
  25  *
  26  * Other functions we might want:
  27  * - enumerate all known zones
  28  * - convenience function to gather record and the full affilliated stree
  29  *   in one shot
  30  */
  31
  32 #ifndef GNUNET_NAMESTORE_SERVICE_H
  33 #define GNUNET_NAMESTORE_SERVICE_H
  34
  35 #include "gnunet_util_lib.h"
  36 #include "gnunet_block_lib.h"
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46 /**
  47  * Entry in the queue.
  48  */
  49 struct GNUNET_NAMESTORE_QueueEntry;
  50
  51 /**
  52  * Handle to the namestore service.
  53  */
  54 struct GNUNET_NAMESTORE_Handle;
  55
  56 /**
  57  * Handle to the namestore zone iterator.
  58  */
  59 struct GNUNET_NAMESTORE_ZoneIterator;
  60
  61 /**
  62  * Maximum size of a value that can be stored in the namestore.
  63  */
  64 #define GNUNET_NAMESTORE_MAX_VALUE_SIZE (63 * 1024)
  65
  66 /**
  67  * Connect to the namestore service.
  68  *
  69  * @param cfg configuration to use
  70  * @return handle to use to access the service
  71  */
  72 struct GNUNET_NAMESTORE_Handle *
  73 GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
  74
  75
  76 /**
  77  * Disconnect from the namestore service (and free associated
  78  * resources).
  79  *
  80  * @param h handle to the namestore
  81  * @param drop set to GNUNET_YES to delete all data in namestore (!)
  82  */
  83 void
  84 GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop);
  85
  86
  87 /**
  88  * Continuation called to notify client about result of the
  89  * operation.
  90  *
  91  * @param cls closure
  92  * @param success GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
  93  *                GNUNET_NO if content was already there
  94  *                GNUNET_YES (or other positive value) on success
  95  * @param emsg NULL on success, otherwise an error message
  96  */
  97 typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
  98                                                          int32_t success,
  99                                                          const char *emsg);
 100
 101
 102 /**
 103  * Flags that can be set for a record.
 104  */
 105 enum GNUNET_NAMESTORE_RecordFlags
 106 {
 107
 108   /**
 109    * No special options.
 110    */
 111   GNUNET_NAMESTORE_RF_NONE = 0,
 112
 113   /**
 114    * This peer is the authority for this record; it must thus
 115    * not be deleted (other records can be deleted if we run
 116    * out of space).
 117    */
 118   GNUNET_NAMESTORE_RF_AUTHORITY = 1,
 119
 120   /**
 121    * This is a private record of this peer and it should
 122    * thus not be handed out to other peers.
 123    */
 124   GNUNET_NAMESTORE_RF_PRIVATE = 2
 125
 126 };
 127
 128
 129 /**
 130  * Get the hash of a record
 131  *
 132  * @param zone hash of the public key of the zone
 133  * @param name name that is being mapped (at most 255 characters long)
 134  * @param record_type type of the record (A, AAAA, PKEY, etc.)
 135  * @param expiration expiration time for the content
 136  * @param flags flags for the content
 137  * @param data_size number of bytes in data
 138  * @param data value, semantics depend on 'record_type' (see RFCs for DNS and
 139  *             GNS specification for GNS extensions)
 140  * @param record_hash hash of the record (set)
 141  */
 142 void
 143 GNUNET_NAMESTORE_record_hash (struct GNUNET_NAMESTORE_Handle *h,
 144                               const GNUNET_HashCode *zone,
 145                               const char *name,
 146                               uint32_t record_type,
 147                               struct GNUNET_TIME_Absolute expiration,
 148                               enum GNUNET_NAMESTORE_RecordFlags flags,
 149                               size_t data_size,
 150                               const void *data,
 151                               GNUNET_HashCode *record_hash);
 152
 153
 154 /**
 155  * Store an item in the namestore.  If the item is already present,
 156  * the expiration time is updated to the max of the existing time and
 157  * the new time.
 158  *
 159  * @param h handle to the namestore
 160  * @param zone hash of the public key of the zone
 161  * @param name name that is being mapped (at most 255 characters long)
 162  * @param record_type type of the record (A, AAAA, PKEY, etc.)
 163  * @param expiration expiration time for the content
 164  * @param flags flags for the content
 165  * @param data_size number of bytes in data
 166  * @param data value, semantics depend on 'record_type' (see RFCs for DNS and
 167  *             GNS specification for GNS extensions)
 168  * @param cont continuation to call when done
 169  * @param cont_cls closure for cont
 170  * @return handle to abort the request
 171  */
 172 struct GNUNET_NAMESTORE_QueueEntry *
 173 GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h,
 174                              const GNUNET_HashCode *zone,
 175                              const char *name,
 176                              uint32_t record_type,
 177                              struct GNUNET_TIME_Absolute expiration,
 178                              enum GNUNET_NAMESTORE_RecordFlags flags,
 179                              size_t data_size,
 180                              const void *data,
 181                              GNUNET_NAMESTORE_ContinuationWithStatus cont,
 182                              void *cont_cls);
 183
 184 /**
 185  * Store a signature for 'name' in the namestore.
 186  * Used by non-authorities to store signatures for cached name records.
 187  *
 188  * @param h handle to the namestore
 189  * @param zone hash of the public key of the zone
 190  * @param name name that is being mapped (at most 255 characters long)
 191  * @param sig the signature
 192  * @param cont continuation to call when done
 193  * @param cont_cls closure for cont
 194  * @return handle to abort the request
 195  */
 196 struct GNUNET_NAMESTORE_QueueEntry *
 197 GNUNET_NAMESTORE_signature_put (struct GNUNET_NAMESTORE_Handle *h,
 198                                 const GNUNET_HashCode *zone,
 199                                 const char *name,
 200                                 struct GNUNET_CRYPTO_RsaSignature sig,
 201                                 GNUNET_NAMESTORE_ContinuationWithStatus cont,
 202                                 void *cont_cls);
 203
 204
 205 /**
 206  * Explicitly remove some content from the database.  The
 207  * "cont"inuation will be called with status "GNUNET_OK" if content
 208  * was removed, "GNUNET_NO" if no matching entry was found and
 209  * "GNUNET_SYSERR" on all other types of errors.
 210  *
 211  * @param h handle to the namestore
 212  * @param zone hash of the public key of the zone
 213  * @param name name that is being mapped (at most 255 characters long)
 214  * @param record_type type of the record (A, AAAA, PKEY, etc.)
 215  * @param size number of bytes in data
 216  * @param data content stored
 217  * @param cont continuation to call when done
 218  * @param cont_cls closure for cont
 219  * @return handle to abort the request
 220  */
 221 struct GNUNET_NAMESTORE_QueueEntry *
 222 GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h,
 223                                 const GNUNET_HashCode *zone,
 224                                 const char *name,
 225                                 uint32_t record_type,
 226                                 size_t size,
 227                                 const void *data,
 228                                 GNUNET_NAMESTORE_ContinuationWithStatus cont,
 229                                 void *cont_cls);
 230
 231
 232 /**
 233  * Process a record that was stored in the namestore.
 234  *
 235  * @param cls closure
 236  * @param zone hash of the public key of the zone
 237  * @param name name that is being mapped (at most 255 characters long)
 238  * @param record_type type of the record (A, AAAA, PKEY, etc.)
 239  * @param expiration expiration time for the content
 240  * @param flags flags for the content
 241  * @param size number of bytes in data
 242  * @param data content stored
 243  */
 244 typedef void (*GNUNET_NAMESTORE_RecordProcessor) (void *cls,
 245                                                  const GNUNET_HashCode *zone,
 246                                                  const char *name,
 247                                                  uint32_t record_type,
 248                                                  struct GNUNET_TIME_Absolute expiration,
 249                                                  enum GNUNET_NAMESTORE_RecordFlags flags,
 250                                                  size_t size, const void *data);
 251
 252 /**
 253  * Process a signature for a given name
 254  *
 255  * @param cls closure
 256  * @param zone hash of the public key of the zone
 257  * @param name name of the records that were signed
 258  * @param sig the signature
 259  */
 260 typedef void (*GNUNET_NAMESTORE_SignatureProcessor) (void *cls,
 261                                          const GNUNET_HashCode *zone,
 262                                          const char *name,
 263                                          struct GNUNET_CRYPTO_RsaSignature sig);
 264
 265
 266
 267 /**
 268  * Get a result for a particular key from the namestore.  The processor
 269  * will only be called once.
 270  *
 271  * @param h handle to the namestore
 272  * @param zone zone to look up a record from
 273  * @param name name to look up
 274  * @param record_type desired record type
 275  * @param proc function to call on each matching value;
 276  *        will be called once with a NULL value at the end
 277  * @param proc_cls closure for proc
 278  * @return a handle that can be used to
 279  *         cancel
 280  */
 281 struct GNUNET_NAMESTORE_QueueEntry *
 282 GNUNET_NAMESTORE_lookup_record (struct GNUNET_NAMESTORE_Handle *h,
 283                               const GNUNET_HashCode *zone,
 284                               const char *name,
 285                               uint32_t record_type,
 286                               GNUNET_NAMESTORE_RecordProcessor proc, void *proc_cls);
 287
 288
 289 /**
 290  * Obtain latest/current signature of a zone's name.  The processor
 291  * will only be called once.
 292  *
 293  * @param h handle to the namestore
 294  * @param zone zone to look up a signature from
 295  * @param the common name of the records the signature is for
 296  * @param proc function to call on each matching value;
 297  *        will be called once with a NULL value at the end
 298  * @param proc_cls closure for proc
 299  * @return a handle that can be used to
 300  *         cancel
 301  */
 302 struct GNUNET_NAMESTORE_QueueEntry *
 303 GNUNET_NAMESTORE_lookup_signature (struct GNUNET_NAMESTORE_Handle *h,
 304                                    const GNUNET_HashCode *zone,
 305            const char* name,
 306                                    GNUNET_NAMESTORE_SignatureProcessor proc, void *proc_cls);
 307
 308
 309 /**
 310  * Get all records of a zone.
 311  *
 312  * @param h handle to the namestore
 313  * @param zone zone to access
 314  * @param proc function to call on a random value; it
 315  *        will be called repeatedly with a value (if available)
 316  *        and always once at the end with a zone and name of NULL.
 317  * @param proc_cls closure for proc
 318  * @return a handle that can be used to
 319  *         cancel
 320  */
 321 struct GNUNET_NAMESTORE_QueueEntry *
 322 GNUNET_NAMESTORE_zone_transfer (struct GNUNET_NAMESTORE_Handle *h,
 323                                 const GNUNET_HashCode *zone,
 324                                 GNUNET_NAMESTORE_RecordProcessor proc,
 325                                 void *proc_cls);
 326
 327
 328 /**
 329  * Starts a new zone iteration. This MUST lock the GNUNET_NAMESTORE_Handle
 330  * for any other calls than
 331  * GNUNET_NAMESTORE_zone_iterator_next
 332  * and
 333  * GNUNET_NAMESTORE_zone_iteration_stop
 334  *
 335  * @param h handle to the namestore
 336  * @param zone zone to access
 337  * @param proc function to call on a random value; it
 338  *        will be called repeatedly with a value (if available)
 339  *        and always once at the end with a zone and name of NULL.
 340  * @param proc_cls closure for proc
 341  * @return an iterator handle to use for iteration
 342  */
 343 struct GNUNET_NAMESTORE_ZoneIterator *
 344 GNUNET_NAMESTORE_zone_iteration_start(struct GNUNET_NAMESTORE_Handle *h,
 345                                       const GNUNET_HashCode *zone,
 346                                       GNUNET_NAMESTORE_RecordProcessor proc,
 347                                       void *proc_cls);
 348
 349 /**
 350  * Calls the record processor specified in GNUNET_NAMESTORE_zone_iteration_start
 351  * for the next record.
 352  *
 353  * @param it the iterator
 354  * @return 0 if no more records are available to iterate
 355  */
 356 int
 357 GNUNET_NAMESTORE_zone_iterator_next(struct GNUNET_NAMESTORE_ZoneIterator *it);
 358
 359 /**
 360  * Stops iteration and releases the namestore handle for further calls.
 361  *
 362  * @param it the iterator
 363  */
 364 void
 365 GNUNET_NAMESTORE_zone_iteration_stop(struct GNUNET_NAMESTORE_ZoneIterator *it);
 366
 367
 368 /**
 369  * Cancel a namestore operation.  The final callback from the
 370  * operation must not have been done yet.
 371  *
 372  * @param qe operation to cancel
 373  */
 374 void
 375 GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
 376
 377
 378 #if 0                           /* keep Emacsens' auto-indent happy */
 379 {
 380 #endif
 381 #ifdef __cplusplus
 382 }
 383 #endif
 384
 385 /* end of gnunet_namestore_service.h */
 386 #endif