2 This file is part of GNUnet
3 (C) 2012 Christian Grothoff (and other contributing authors)
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.
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.
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.
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
26 * Other functions we might want:
27 * - enumerate all known zones
28 * - convenience function to gather record and the full affilliated stree
32 #ifndef GNUNET_NAMESTORE_SERVICE_H
33 #define GNUNET_NAMESTORE_SERVICE_H
35 #include "gnunet_util_lib.h"
36 #include "gnunet_block_lib.h"
41 #if 0 /* keep Emacsens' auto-indent happy */
47 * Record type for GNS zone transfer ("PKEY").
49 #define GNUNET_GNS_TYPE_PKEY 65536
54 struct GNUNET_NAMESTORE_QueueEntry;
57 * Handle to the namestore service.
59 struct GNUNET_NAMESTORE_Handle;
62 * Handle to the namestore zone iterator.
64 struct GNUNET_NAMESTORE_ZoneIterator;
67 * Maximum size of a value that can be stored in the namestore.
69 #define GNUNET_NAMESTORE_MAX_VALUE_SIZE (63 * 1024)
72 * Connect to the namestore service.
74 * @param cfg configuration to use
75 * @return handle to use to access the service
77 struct GNUNET_NAMESTORE_Handle *
78 GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
82 * Disconnect from the namestore service (and free associated
85 * @param h handle to the namestore
86 * @param drop set to GNUNET_YES to delete all data in namestore (!)
89 GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop);
93 * Continuation called to notify client about result of the
97 * @param success GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
98 * GNUNET_NO if content was already there
99 * GNUNET_YES (or other positive value) on success
100 * @param emsg NULL on success, otherwise an error message
102 typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
108 * Flags that can be set for a record.
110 enum GNUNET_NAMESTORE_RecordFlags
114 * No special options.
116 GNUNET_NAMESTORE_RF_NONE = 0,
119 * This peer is the authority for this record; it must thus
120 * not be deleted (other records can be deleted if we run
123 GNUNET_NAMESTORE_RF_AUTHORITY = 1,
126 * This is a private record of this peer and it should
127 * thus not be handed out to other peers.
129 GNUNET_NAMESTORE_RF_PRIVATE = 2
137 struct GNUNET_NAMESTORE_RecordData
141 * Binary value stored in the DNS record.
146 * Expiration time for the DNS record.
148 struct GNUNET_TIME_Absolute expiration;
151 * Number of bytes in 'data'.
156 * Type of the GNS/DNS record.
158 uint32_t record_type;
161 * Flags for the record.
163 enum GNUNET_NAMESTORE_RecordFlags flags;
168 * Store an item in the namestore. If the item is already present,
169 * the expiration time is updated to the max of the existing time and
170 * the new time. This API is used when we cache signatures from other
173 * @param h handle to the namestore
174 * @param zone_key public key of the zone
175 * @param name name that is being mapped (at most 255 characters long)
176 * @param expire when does the corresponding block in the DHT expire (until
177 * when should we never do a DHT lookup for the same name again)?
178 * @param rd_count number of entries in 'rd' array
179 * @param rd array of records with data to store
180 * @param signature signature for all the records in the zone under the given name
181 * @param cont continuation to call when done
182 * @param cont_cls closure for cont
183 * @return handle to abort the request
185 struct GNUNET_NAMESTORE_QueueEntry *
186 GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h,
187 const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key,
189 struct GNUNET_TIME_Absolute expire,
190 unsigned int rd_count,
191 const struct GNUNET_NAMESTORE_RecordData *rd,
192 const struct GNUNET_CRYPTO_RsaSignature *signature,
193 GNUNET_NAMESTORE_ContinuationWithStatus cont,
198 * Check if a signature is valid. This API is used by the GNS Block
199 * to validate signatures received from the network.
201 * @param public_key public key of the zone
202 * @param name name that is being mapped (at most 255 characters long)
203 * @param rd_count number of entries in 'rd' array
204 * @param rd array of records with data to store
205 * @param signature signature for all the records in the zone under the given name
206 * @return GNUNET_OK if the signature is valid
209 GNUNET_NAMESTORE_verify_signature (const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *public_key,
211 unsigned int rd_count,
212 const struct GNUNET_NAMESTORE_RecordData *rd,
213 const struct GNUNET_CRYPTO_RsaSignature *signature);
217 * Store an item in the namestore. If the item is already present,
218 * the expiration time is updated to the max of the existing time and
219 * the new time. This API is used by the authority of a zone.
221 * @param h handle to the namestore
222 * @param pkey private key of the zone
223 * @param name name that is being mapped (at most 255 characters long)
224 * @param rd record data to store
225 * @param cont continuation to call when done
226 * @param cont_cls closure for cont
227 * @return handle to abort the request
229 struct GNUNET_NAMESTORE_QueueEntry *
230 GNUNET_NAMESTORE_record_create (struct GNUNET_NAMESTORE_Handle *h,
231 const struct GNUNET_CRYPTO_RsaPrivateKey *pkey,
233 const struct GNUNET_NAMESTORE_RecordData *rd,
234 GNUNET_NAMESTORE_ContinuationWithStatus cont,
239 * Explicitly remove some content from the database. The
240 * "cont"inuation will be called with status "GNUNET_OK" if content
241 * was removed, "GNUNET_NO" if no matching entry was found and
242 * "GNUNET_SYSERR" on all other types of errors.
243 * This API is used by the authority of a zone.
245 * @param h handle to the namestore
246 * @param pkey private key of the zone
247 * @param name name that is being mapped (at most 255 characters long)
248 * @param rd record data
249 * @param cont continuation to call when done
250 * @param cont_cls closure for cont
251 * @return handle to abort the request
253 struct GNUNET_NAMESTORE_QueueEntry *
254 GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h,
255 const struct GNUNET_CRYPTO_RsaPrivateKey *pkey,
257 const struct GNUNET_NAMESTORE_RecordData *rd,
258 GNUNET_NAMESTORE_ContinuationWithStatus cont,
263 * Process a record that was stored in the namestore.
266 * @param zone_key public key of the zone
267 * @param expire when does the corresponding block in the DHT expire (until
268 * when should we never do a DHT lookup for the same name again)?;
269 * GNUNET_TIME_UNIT_ZERO_ABS if there are no records of any type in the namestore,
270 * or the expiration time of the block in the namestore (even if there are zero
271 * records matching the desired record type)
272 * @param name name that is being mapped (at most 255 characters long)
273 * @param rd_count number of entries in 'rd' array
274 * @param rd array of records with data to store
275 * @param signature signature of the record block, NULL if signature is unavailable (i.e.
276 * because the user queried for a particular record type only)
278 typedef void (*GNUNET_NAMESTORE_RecordProcessor) (void *cls,
279 const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key,
280 struct GNUNET_TIME_Absolute expire,
283 const struct GNUNET_NAMESTORE_RecordData *rd,
284 const struct GNUNET_CRYPTO_RsaSignature *signature);
288 * Get a result for a particular key from the namestore. The processor
289 * will only be called once.
291 * @param h handle to the namestore
292 * @param zone zone to look up a record from
293 * @param name name to look up
294 * @param record_type desired record type, 0 for all
295 * @param proc function to call on the matching records, or with
296 * NULL (rd_count == 0) if there are no matching records
297 * @param proc_cls closure for proc
298 * @return a handle that can be used to
301 struct GNUNET_NAMESTORE_QueueEntry *
302 GNUNET_NAMESTORE_lookup_record (struct GNUNET_NAMESTORE_Handle *h,
303 const GNUNET_HashCode *zone,
305 uint32_t record_type,
306 GNUNET_NAMESTORE_RecordProcessor proc, void *proc_cls);
310 * Starts a new zone iteration (used to periodically PUT all of our
311 * records into our DHT). This MUST lock the GNUNET_NAMESTORE_Handle
312 * for any other calls than GNUNET_NAMESTORE_zone_iterator_next and
313 * GNUNET_NAMESTORE_zone_iteration_stop. "proc" will be called once
314 * immediately, and then again after
315 * "GNUNET_NAMESTORE_zone_iterator_next" is invoked.
317 * @param h handle to the namestore
318 * @param zone zone to access, NULL for all zones
319 * @param must_have_flags flags that must be set for the record to be returned
320 * @param must_not_have_flags flags that must NOT be set for the record to be returned
321 * @param proc function to call on each name from the zone; it
322 * will be called repeatedly with a value (if available)
323 * and always once at the end with a name of NULL.
324 * @param proc_cls closure for proc
325 * @return an iterator handle to use for iteration
327 struct GNUNET_NAMESTORE_ZoneIterator *
328 GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h,
329 const GNUNET_HashCode *zone,
330 enum GNUNET_NAMESTORE_RecordFlags must_have_flags,
331 enum GNUNET_NAMESTORE_RecordFlags must_not_have_flags,
332 GNUNET_NAMESTORE_RecordProcessor proc,
337 * Calls the record processor specified in GNUNET_NAMESTORE_zone_iteration_start
338 * for the next record.
340 * @param it the iterator
343 GNUNET_NAMESTORE_zone_iterator_next (struct GNUNET_NAMESTORE_ZoneIterator *it);
347 * Stops iteration and releases the namestore handle for further calls.
349 * @param it the iterator
352 GNUNET_NAMESTORE_zone_iteration_stop (struct GNUNET_NAMESTORE_ZoneIterator *it);
356 * Cancel a namestore operation. The final callback from the
357 * operation must not have been done yet.
359 * @param qe operation to cancel
362 GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
366 /* convenience APIs for serializing / deserializing GNS records */
369 * Calculate how many bytes we will need to serialize the given
372 * @param rd_count number of records in the rd array
373 * @param rd array of GNUNET_NAMESTORE_RecordData with rd_count elements
375 * @return the required size to serialize
379 GNUNET_NAMESTORE_records_get_size (unsigned int rd_count,
380 const struct GNUNET_NAMESTORE_RecordData *rd);
383 * Serialize the given records to the given destination buffer.
385 * @param rd_cound number of records in the rd array
386 * @param rd array of GNUNET_NAMESTORE_RecordData with rd_count elements
387 * @param dest_size size of the destination array
388 * @param dest where to write the result
390 * @return the size of serialized records
393 GNUNET_NAMESTORE_records_serialize (unsigned int rd_count,
394 const struct GNUNET_NAMESTORE_RecordData *rd,
400 * Deserialize the given records to the given destination.
402 * @param len size of the serialized record data
403 * @param src the serialized record data
404 * @param rd_cound number of records in the rd array
405 * @param dest where to put the data
407 * @return GNUNET_OK on success, GNUNET_SYSERR on error
410 GNUNET_NAMESTORE_records_deserialize (size_t len,
412 unsigned int rd_count,
413 struct GNUNET_NAMESTORE_RecordData *dest);
416 #if 0 /* keep Emacsens' auto-indent happy */
423 /* end of gnunet_namestore_service.h */