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 */
49 struct GNUNET_NAMESTORE_QueueEntry;
52 * Handle to the namestore service.
54 struct GNUNET_NAMESTORE_Handle;
57 * Handle to the namestore zone iterator.
59 struct GNUNET_NAMESTORE_ZoneIterator;
62 * Maximum size of a value that can be stored in the namestore.
64 #define GNUNET_NAMESTORE_MAX_VALUE_SIZE (63 * 1024)
67 * Connect to the namestore service.
69 * @param cfg configuration to use
70 * @return handle to use to access the service
72 struct GNUNET_NAMESTORE_Handle *
73 GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
77 * Disconnect from the namestore service (and free associated
80 * @param h handle to the namestore
81 * @param drop set to GNUNET_YES to delete all data in namestore (!)
84 GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop);
88 * Continuation called to notify client about result of the
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
97 typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
103 * Flags that can be set for a record.
105 enum GNUNET_NAMESTORE_RecordFlags
109 * No special options.
111 GNUNET_NAMESTORE_RF_NONE = 0,
114 * This peer is the authority for this record; it must thus
115 * not be deleted (other records can be deleted if we run
118 GNUNET_NAMESTORE_RF_AUTHORITY = 1,
121 * This is a private record of this peer and it should
122 * thus not be handed out to other peers.
124 GNUNET_NAMESTORE_RF_PRIVATE = 2
130 * Get the hash of a record
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)
143 GNUNET_NAMESTORE_record_hash (struct GNUNET_NAMESTORE_Handle *h,
144 const GNUNET_HashCode *zone,
146 uint32_t record_type,
147 struct GNUNET_TIME_Absolute expiration,
148 enum GNUNET_NAMESTORE_RecordFlags flags,
151 GNUNET_HashCode *record_hash);
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
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
172 struct GNUNET_NAMESTORE_QueueEntry *
173 GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h,
174 const GNUNET_HashCode *zone,
176 uint32_t record_type,
177 struct GNUNET_TIME_Absolute expiration,
178 enum GNUNET_NAMESTORE_RecordFlags flags,
181 GNUNET_NAMESTORE_ContinuationWithStatus cont,
185 * Store a signature for 'name' in the namestore.
186 * Used by non-authorities to store signatures for cached name records.
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
196 struct GNUNET_NAMESTORE_QueueEntry *
197 GNUNET_NAMESTORE_signature_put (struct GNUNET_NAMESTORE_Handle *h,
198 const GNUNET_HashCode *zone,
200 struct GNUNET_CRYPTO_RsaSignature sig,
201 GNUNET_NAMESTORE_ContinuationWithStatus cont,
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.
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
221 struct GNUNET_NAMESTORE_QueueEntry *
222 GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h,
223 const GNUNET_HashCode *zone,
225 uint32_t record_type,
228 GNUNET_NAMESTORE_ContinuationWithStatus cont,
233 * Process a record that was stored in the namestore.
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
244 typedef void (*GNUNET_NAMESTORE_RecordProcessor) (void *cls,
245 const GNUNET_HashCode *zone,
247 uint32_t record_type,
248 struct GNUNET_TIME_Absolute expiration,
249 enum GNUNET_NAMESTORE_RecordFlags flags,
250 size_t size, const void *data);
253 * Process a signature for a given name
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
260 typedef void (*GNUNET_NAMESTORE_SignatureProcessor) (void *cls,
261 const GNUNET_HashCode *zone,
263 struct GNUNET_CRYPTO_RsaSignature sig);
268 * Get a result for a particular key from the namestore. The processor
269 * will only be called once.
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
281 struct GNUNET_NAMESTORE_QueueEntry *
282 GNUNET_NAMESTORE_lookup_record (struct GNUNET_NAMESTORE_Handle *h,
283 const GNUNET_HashCode *zone,
285 uint32_t record_type,
286 GNUNET_NAMESTORE_RecordProcessor proc, void *proc_cls);
290 * Obtain latest/current signature of a zone's name. The processor
291 * will only be called once.
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
302 struct GNUNET_NAMESTORE_QueueEntry *
303 GNUNET_NAMESTORE_lookup_signature (struct GNUNET_NAMESTORE_Handle *h,
304 const GNUNET_HashCode *zone,
306 GNUNET_NAMESTORE_SignatureProcessor proc, void *proc_cls);
310 * Get all records of a zone.
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
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,
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
333 * GNUNET_NAMESTORE_zone_iteration_stop
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
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,
350 * Calls the record processor specified in GNUNET_NAMESTORE_zone_iteration_start
351 * for the next record.
353 * @param it the iterator
354 * @return 0 if no more records are available to iterate
357 GNUNET_NAMESTORE_zone_iterator_next(struct GNUNET_NAMESTORE_ZoneIterator *it);
360 * Stops iteration and releases the namestore handle for further calls.
362 * @param it the iterator
365 GNUNET_NAMESTORE_zone_iteration_stop(struct GNUNET_NAMESTORE_ZoneIterator *it);
369 * Cancel a namestore operation. The final callback from the
370 * operation must not have been done yet.
372 * @param qe operation to cancel
375 GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
378 #if 0 /* keep Emacsens' auto-indent happy */
385 /* end of gnunet_namestore_service.h */