aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_namestore_service.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_namestore_service.h')
-rw-r--r--src/include/gnunet_namestore_service.h398
1 files changed, 286 insertions, 112 deletions
diff --git a/src/include/gnunet_namestore_service.h b/src/include/gnunet_namestore_service.h
index 86572803f..0f9be8b10 100644
--- a/src/include/gnunet_namestore_service.h
+++ b/src/include/gnunet_namestore_service.h
@@ -19,6 +19,9 @@
19 */ 19 */
20 20
21/** 21/**
22 * @addtogroup GNS
23 * @{
24 *
22 * @author Christian Grothoff 25 * @author Christian Grothoff
23 * 26 *
24 * @file 27 * @file
@@ -38,10 +41,10 @@
38#ifndef GNUNET_NAMESTORE_SERVICE_H 41#ifndef GNUNET_NAMESTORE_SERVICE_H
39#define GNUNET_NAMESTORE_SERVICE_H 42#define GNUNET_NAMESTORE_SERVICE_H
40 43
44
45#include "gnunet_error_codes.h"
41#include "gnunet_util_lib.h" 46#include "gnunet_util_lib.h"
42#include "gnunet_block_lib.h"
43#include "gnunet_gnsrecord_lib.h" 47#include "gnunet_gnsrecord_lib.h"
44#include "gnunet_identity_service.h"
45 48
46#ifdef __cplusplus 49#ifdef __cplusplus
47extern "C" 50extern "C"
@@ -67,6 +70,28 @@ struct GNUNET_NAMESTORE_Handle;
67 */ 70 */
68struct GNUNET_NAMESTORE_ZoneIterator; 71struct GNUNET_NAMESTORE_ZoneIterator;
69 72
73/**
74 * Transaction control types.
75 * They roughly correspond to DB transaction controls
76 */
77enum GNUNET_NAMESTORE_TxControl
78{
79 GNUNET_NAMESTORE_TX_BEGIN = 0,
80 GNUNET_NAMESTORE_TX_COMMIT = 1,
81 GNUNET_NAMESTORE_TX_ROLLBACK = 2,
82};
83
84/**
85 * A struct for record bulk import.
86 * The fields are arrays pointing to individual GNS records and names.
87 */
88struct GNUNET_NAMESTORE_RecordInfo
89{
90 const char *a_label;
91 unsigned int a_rd_count;
92 struct GNUNET_GNSRECORD_Data *a_rd;
93};
94
70 95
71/** 96/**
72 * Connect to the namestore service. 97 * Connect to the namestore service.
@@ -97,12 +122,11 @@ GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h);
97 * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate) 122 * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
98 * #GNUNET_NO if content was already there or not found 123 * #GNUNET_NO if content was already there or not found
99 * #GNUNET_YES (or other positive value) on success 124 * #GNUNET_YES (or other positive value) on success
100 * @param emsg NULL on success, otherwise an error message 125 * @param ec the #GNUNET_ErrorCode, #GNUNET_EC_NONE on success.
101 */ 126 */
102typedef void 127typedef void
103(*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls, 128(*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
104 int32_t success, 129 enum GNUNET_ErrorCode ec);
105 const char *emsg);
106 130
107 131
108/** 132/**
@@ -116,6 +140,9 @@ typedef void
116 * keep up with the changes, calling @a cont will be delayed until the 140 * keep up with the changes, calling @a cont will be delayed until the
117 * monitors do keep up. 141 * monitors do keep up.
118 * 142 *
143 * This always overwrites the record set and unsets any advisory
144 * lock inrrespective of the currently set editor hint/advisory lock value.
145 *
119 * @param h handle to the namestore 146 * @param h handle to the namestore
120 * @param pkey private key of the zone 147 * @param pkey private key of the zone
121 * @param label name that is being mapped 148 * @param label name that is being mapped
@@ -126,13 +153,50 @@ typedef void
126 * @return handle to abort the request 153 * @return handle to abort the request
127 */ 154 */
128struct GNUNET_NAMESTORE_QueueEntry * 155struct GNUNET_NAMESTORE_QueueEntry *
129GNUNET_NAMESTORE_records_store (struct GNUNET_NAMESTORE_Handle *h, 156GNUNET_NAMESTORE_record_set_store (struct GNUNET_NAMESTORE_Handle *h,
130 const struct GNUNET_IDENTITY_PrivateKey *pkey, 157 const struct GNUNET_CRYPTO_PrivateKey *pkey,
131 const char *label, 158 const char *label,
132 unsigned int rd_count, 159 unsigned int rd_count,
133 const struct GNUNET_GNSRECORD_Data *rd, 160 const struct GNUNET_GNSRECORD_Data *rd,
134 GNUNET_NAMESTORE_ContinuationWithStatus cont, 161 GNUNET_NAMESTORE_ContinuationWithStatus cont,
135 void *cont_cls); 162 void *cont_cls);
163
164/**
165 * Store one or more record sets in the namestore. If any item is already present,
166 * it is replaced with the new record. Use an empty array to
167 * remove all records under the given name.
168 *
169 * The continuation is called after the records have been stored in the
170 * database. They may not yet have been commited. Monitors may be notified
171 * asynchronously (basically with a buffer when commited).
172 * However, if any monitor is consistently too slow to
173 * keep up with the changes, calling @a cont will be delayed until the
174 * monitors do keep up.
175 * Uncommited store requests within a transaction (GNUNET_NAMESTORE_transaction_begin)
176 * cause @a cont to be called immediately before the commit and before
177 * notification of monitors.
178 *
179 * This always overwrites the record set and unsets any advisory
180 * lock inrrespective of the currently set editor hint/advisory lock value.
181 *
182 * @param h handle to the namestore
183 * @param pkey private key of the zone
184 * @param rd_set_count the number of record sets
185 * @param record_info the records to add containing @a rd_set_count records
186 * @param cont continuation to call when done
187 * @param rds_sent set to how many record sets could actually be sent
188 * @param cont_cls closure for @a cont
189 * @return handle to abort the request
190 */
191struct GNUNET_NAMESTORE_QueueEntry *
192GNUNET_NAMESTORE_records_store (
193 struct GNUNET_NAMESTORE_Handle *h,
194 const struct GNUNET_CRYPTO_PrivateKey *pkey,
195 unsigned int rd_set_count,
196 const struct GNUNET_NAMESTORE_RecordInfo *record_info,
197 unsigned int *rds_sent,
198 GNUNET_NAMESTORE_ContinuationWithStatus cont,
199 void *cont_cls);
136 200
137/** 201/**
138 * Store an item in the namestore. If the item is already present, 202 * Store an item in the namestore. If the item is already present,
@@ -156,16 +220,14 @@ GNUNET_NAMESTORE_records_store (struct GNUNET_NAMESTORE_Handle *h,
156 * @return handle to abort the request 220 * @return handle to abort the request
157 */ 221 */
158struct GNUNET_NAMESTORE_QueueEntry * 222struct GNUNET_NAMESTORE_QueueEntry *
159GNUNET_NAMESTORE_records_store_ (struct GNUNET_NAMESTORE_Handle *h, 223GNUNET_NAMESTORE_record_set_store_ (struct GNUNET_NAMESTORE_Handle *h,
160 const struct GNUNET_IDENTITY_PrivateKey *pkey, 224 const struct GNUNET_CRYPTO_PrivateKey *pkey,
161 const char *label, 225 const char *label,
162 unsigned int rd_count, 226 unsigned int rd_count,
163 const struct GNUNET_GNSRECORD_Data *rd, 227 const struct GNUNET_GNSRECORD_Data *rd,
164 int is_zonemaster, 228 int is_zonemaster,
165 GNUNET_NAMESTORE_ContinuationWithStatus cont, 229 GNUNET_NAMESTORE_ContinuationWithStatus cont,
166 void *cont_cls); 230 void *cont_cls);
167
168
169 231
170 232
171/** 233/**
@@ -180,10 +242,48 @@ GNUNET_NAMESTORE_records_store_ (struct GNUNET_NAMESTORE_Handle *h,
180typedef void 242typedef void
181(*GNUNET_NAMESTORE_RecordMonitor) (void *cls, 243(*GNUNET_NAMESTORE_RecordMonitor) (void *cls,
182 const struct 244 const struct
183 GNUNET_IDENTITY_PrivateKey *zone, 245 GNUNET_CRYPTO_PrivateKey *zone,
184 const char *label, 246 const char *label,
185 unsigned int rd_count, 247 unsigned int rd_count,
186 const struct GNUNET_GNSRECORD_Data *rd); 248 const struct GNUNET_GNSRECORD_Data *rd);
249/**
250 * Process a record that was stored in the namestore.
251 *
252 * @param cls closure
253 * @param ec the error code. #GNUNET_EC_NONE on success.
254 * @param rd_count number of entries in @a rd array, 0 if label was deleted
255 * @param rd array of records with data to store
256 * @param editor_hint the advisory lock value that was replaced. NULL of not advisory lock
257 was set or if lock was equal to provided editor hint.
258 */
259typedef void
260(*GNUNET_NAMESTORE_EditRecordSetBeginCallback) (void *cls,
261 enum GNUNET_ErrorCode ec,
262 unsigned int rd_count,
263 const struct
264 GNUNET_GNSRECORD_Data *rd,
265 const char *editor_hint);
266
267/**
268 * Process a record set that was stored in the namestore.
269 * The record set expiration value takes existing TOMBSTONE records
270 * into account even if those are not returned.
271 *
272 * @param cls closure
273 * @param zone private key of the zone
274 * @param label label of the records
275 * @param rd_count number of entries in @a rd array, 0 if label was deleted
276 * @param rd array of records with data to store
277 * @param expiry the expiration of this record set.
278 */
279typedef void
280(*GNUNET_NAMESTORE_RecordSetMonitor) (void *cls,
281 const struct
282 GNUNET_CRYPTO_PrivateKey *zone,
283 const char *label,
284 unsigned int rd_count,
285 const struct GNUNET_GNSRECORD_Data *rd,
286 struct GNUNET_TIME_Absolute expiry);
187 287
188 288
189/** 289/**
@@ -203,13 +303,39 @@ typedef void
203struct GNUNET_NAMESTORE_QueueEntry * 303struct GNUNET_NAMESTORE_QueueEntry *
204GNUNET_NAMESTORE_records_lookup (struct GNUNET_NAMESTORE_Handle *h, 304GNUNET_NAMESTORE_records_lookup (struct GNUNET_NAMESTORE_Handle *h,
205 const struct 305 const struct
206 GNUNET_IDENTITY_PrivateKey *pkey, 306 GNUNET_CRYPTO_PrivateKey *pkey,
207 const char *label, 307 const char *label,
208 GNUNET_SCHEDULER_TaskCallback error_cb, 308 GNUNET_SCHEDULER_TaskCallback error_cb,
209 void *error_cb_cls, 309 void *error_cb_cls,
210 GNUNET_NAMESTORE_RecordMonitor rm, 310 GNUNET_NAMESTORE_RecordMonitor rm,
211 void *rm_cls); 311 void *rm_cls);
212 312
313/**
314 * Lookup an item in the namestore with GNSRECORD filter.
315 *
316 * @param h handle to the namestore
317 * @param pkey private key of the zone
318 * @param label name that is being mapped
319 * @param error_cb function to call on error (i.e. disconnect)
320 * the handle is afterwards invalid
321 * @param error_cb_cls closure for @a error_cb
322 * @param rm function to call with the result (with 0 records if we don't have that label);
323 * the handle is afterwards invalid
324 * @param rm_cls closure for @a rm
325 * @param filter the record set filter to use
326 * @return handle to abort the request
327 */
328struct GNUNET_NAMESTORE_QueueEntry *
329GNUNET_NAMESTORE_records_lookup2 (struct GNUNET_NAMESTORE_Handle *h,
330 const struct
331 GNUNET_CRYPTO_PrivateKey *pkey,
332 const char *label,
333 GNUNET_SCHEDULER_TaskCallback error_cb,
334 void *error_cb_cls,
335 GNUNET_NAMESTORE_RecordMonitor rm,
336 void *rm_cls,
337 enum GNUNET_GNSRECORD_Filter filter);
338
213 339
214/** 340/**
215 * Look for an existing PKEY delegation record for a given public key. 341 * Look for an existing PKEY delegation record for a given public key.
@@ -230,9 +356,9 @@ GNUNET_NAMESTORE_records_lookup (struct GNUNET_NAMESTORE_Handle *h,
230 */ 356 */
231struct GNUNET_NAMESTORE_QueueEntry * 357struct GNUNET_NAMESTORE_QueueEntry *
232GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h, 358GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h,
233 const struct GNUNET_IDENTITY_PrivateKey *zone, 359 const struct GNUNET_CRYPTO_PrivateKey *zone,
234 const struct 360 const struct
235 GNUNET_IDENTITY_PublicKey *value_zone, 361 GNUNET_CRYPTO_PublicKey *value_zone,
236 GNUNET_SCHEDULER_TaskCallback error_cb, 362 GNUNET_SCHEDULER_TaskCallback error_cb,
237 void *error_cb_cls, 363 void *error_cb_cls,
238 GNUNET_NAMESTORE_RecordMonitor proc, 364 GNUNET_NAMESTORE_RecordMonitor proc,
@@ -252,6 +378,9 @@ GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
252 378
253 379
254/** 380/**
381 * @deprecated since 0.16.7 will be replaced in 0.18
382 * @see GNUNET_NAMESTORE_zone_iteration_start2()
383 *
255 * Starts a new zone iteration (used to periodically PUT all of our 384 * Starts a new zone iteration (used to periodically PUT all of our
256 * records into our DHT). This MUST lock the `struct GNUNET_NAMESTORE_Handle` 385 * records into our DHT). This MUST lock the `struct GNUNET_NAMESTORE_Handle`
257 * for any other calls than #GNUNET_NAMESTORE_zone_iterator_next() and 386 * for any other calls than #GNUNET_NAMESTORE_zone_iterator_next() and
@@ -279,7 +408,7 @@ GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
279struct GNUNET_NAMESTORE_ZoneIterator * 408struct GNUNET_NAMESTORE_ZoneIterator *
280GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h, 409GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h,
281 const struct 410 const struct
282 GNUNET_IDENTITY_PrivateKey *zone, 411 GNUNET_CRYPTO_PrivateKey *zone,
283 GNUNET_SCHEDULER_TaskCallback error_cb, 412 GNUNET_SCHEDULER_TaskCallback error_cb,
284 void *error_cb_cls, 413 void *error_cb_cls,
285 GNUNET_NAMESTORE_RecordMonitor proc, 414 GNUNET_NAMESTORE_RecordMonitor proc,
@@ -287,6 +416,44 @@ GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h,
287 GNUNET_SCHEDULER_TaskCallback finish_cb, 416 GNUNET_SCHEDULER_TaskCallback finish_cb,
288 void *finish_cb_cls); 417 void *finish_cb_cls);
289 418
419/**
420 * Starts a new zone iteration (used to periodically PUT all of our
421 * records into our DHT). This MUST lock the `struct GNUNET_NAMESTORE_Handle`
422 * for any other calls than #GNUNET_NAMESTORE_zone_iterator_next() and
423 * #GNUNET_NAMESTORE_zone_iteration_stop. @a proc will be called once
424 * immediately, and then again after
425 * #GNUNET_NAMESTORE_zone_iterator_next() is invoked.
426 *
427 * On error (disconnect), @a error_cb will be invoked.
428 * On normal completion, @a finish_cb proc will be
429 * invoked.
430 *
431 * @param h handle to the namestore
432 * @param zone zone to access, NULL for all zones
433 * @param error_cb function to call on error (i.e. disconnect),
434 * the handle is afterwards invalid
435 * @param error_cb_cls closure for @a error_cb
436 * @param proc function to call on each name from the zone; it
437 * will be called repeatedly with a value (if available)
438 * @param proc_cls closure for @a proc
439 * @param finish_cb function to call on completion
440 * the handle is afterwards invalid
441 * @param finish_cb_cls closure for @a finish_cb
442 * @param filter the record set filter to use
443 * @return an iterator handle to use for iteration
444 */
445struct GNUNET_NAMESTORE_ZoneIterator *
446GNUNET_NAMESTORE_zone_iteration_start2 (struct GNUNET_NAMESTORE_Handle *h,
447 const struct
448 GNUNET_CRYPTO_PrivateKey *zone,
449 GNUNET_SCHEDULER_TaskCallback error_cb,
450 void *error_cb_cls,
451 GNUNET_NAMESTORE_RecordSetMonitor proc,
452 void *proc_cls,
453 GNUNET_SCHEDULER_TaskCallback finish_cb,
454 void *finish_cb_cls,
455 enum GNUNET_GNSRECORD_Filter filter);
456
290 457
291/** 458/**
292 * Calls the record processor specified in #GNUNET_NAMESTORE_zone_iteration_start 459 * Calls the record processor specified in #GNUNET_NAMESTORE_zone_iteration_start
@@ -319,6 +486,9 @@ struct GNUNET_NAMESTORE_ZoneMonitor;
319 486
320 487
321/** 488/**
489 * @deprecated since 0.16.7 will be replaced in 0.18
490 * @see GNUNET_NAMESTORE_zone_monitor_start2()
491 *
322 * Begin monitoring a zone for changes. Will first call the @a 492 * Begin monitoring a zone for changes. Will first call the @a
323 * monitor function on all existing records in the selected zone(s) if 493 * monitor function on all existing records in the selected zone(s) if
324 * @a iterate_first is #GNUNET_YES. In any case, we will then call @a 494 * @a iterate_first is #GNUNET_YES. In any case, we will then call @a
@@ -348,7 +518,7 @@ struct GNUNET_NAMESTORE_ZoneMonitor;
348struct GNUNET_NAMESTORE_ZoneMonitor * 518struct GNUNET_NAMESTORE_ZoneMonitor *
349GNUNET_NAMESTORE_zone_monitor_start ( 519GNUNET_NAMESTORE_zone_monitor_start (
350 const struct GNUNET_CONFIGURATION_Handle *cfg, 520 const struct GNUNET_CONFIGURATION_Handle *cfg,
351 const struct GNUNET_IDENTITY_PrivateKey *zone, 521 const struct GNUNET_CRYPTO_PrivateKey *zone,
352 int iterate_first, 522 int iterate_first,
353 GNUNET_SCHEDULER_TaskCallback error_cb, 523 GNUNET_SCHEDULER_TaskCallback error_cb,
354 void *error_cb_cls, 524 void *error_cb_cls,
@@ -357,6 +527,47 @@ GNUNET_NAMESTORE_zone_monitor_start (
357 GNUNET_SCHEDULER_TaskCallback sync_cb, 527 GNUNET_SCHEDULER_TaskCallback sync_cb,
358 void *sync_cb_cls); 528 void *sync_cb_cls);
359 529
530/**
531 * Begin monitoring a zone for changes. Will first call the @a
532 * monitor function on all existing records in the selected zone(s) if
533 * @a iterate_first is #GNUNET_YES. In any case, we will then call @a
534 * sync_cb, and then afterwards call the @a monitor whenever a record
535 * changes. If the namestore disconnects, the @a error_cb function is
536 * called with a disconnect event. Once the connection is
537 * re-established, the process begins from the start (depending on @a
538 * iterate_first, we will again first do all existing records, then @a
539 * sync, then updates).
540 *
541 * @param cfg configuration to use to connect to namestore
542 * @param zone zone to monitor, NULL for all zones
543 * @param iterate_first #GNUNET_YES to first iterate over all existing records,
544 * #GNUNET_NO to only return changes that happen from now on
545 * @param error_cb function to call on error (i.e. disconnect); note that
546 * unlike the other error callbacks in this API, a call to this
547 * function does NOT destroy the monitor handle, it merely signals
548 * that monitoring is down. You need to still explicitly call
549 * #GNUNET_NAMESTORE_zone_monitor_stop().
550 * @param error_cb_cls closure for @a error_cb
551 * @param monitor function to call on zone changes, with an initial limit of 1
552 * @param monitor_cls closure for @a monitor
553 * @param sync_cb function called when we're in sync with the namestore
554 * @param sync_cb_cls closure for @a sync_cb
555 * @param filter the record set filter to use
556 * @return handle to stop monitoring
557 */
558struct GNUNET_NAMESTORE_ZoneMonitor *
559GNUNET_NAMESTORE_zone_monitor_start2 (
560 const struct GNUNET_CONFIGURATION_Handle *cfg,
561 const struct GNUNET_CRYPTO_PrivateKey *zone,
562 int iterate_first,
563 GNUNET_SCHEDULER_TaskCallback error_cb,
564 void *error_cb_cls,
565 GNUNET_NAMESTORE_RecordSetMonitor monitor,
566 void *monitor_cls,
567 GNUNET_SCHEDULER_TaskCallback sync_cb,
568 void *sync_cb_cls,
569 enum GNUNET_GNSRECORD_Filter filter);
570
360 571
361/** 572/**
362 * Calls the monitor processor specified in #GNUNET_NAMESTORE_zone_monitor_start 573 * Calls the monitor processor specified in #GNUNET_NAMESTORE_zone_monitor_start
@@ -398,101 +609,62 @@ GNUNET_NAMESTORE_zone_monitor_stop (struct GNUNET_NAMESTORE_ZoneMonitor *zm);
398 */ 609 */
399 610
400/** 611/**
401 * Begin a namestore transaction. 612 * This function is used to initiate the editing
402 * 613 * of a record set under #label.
403 * @param h handle to the namestore 614 * It will set the editor hint of the record set to #editor_hint.
404 * @param error_cb function to call on error (i.e. disconnect or unable to get lock) 615 * The editor hint serves as an advisory lock that is used in
405 * the handle is afterwards invalid 616 * #GNUNET_NAMESTORE_EdtirRecordSetBeginCallback if #editor_hint
406 * @param error_cb_cls closure for @a error_cb 617 * differs from the currently set advisory lock in the database.
407 * @return handle to abort the request
408 */
409struct GNUNET_NAMESTORE_QueueEntry *
410GNUNET_NAMESTORE_transaction_begin (struct GNUNET_NAMESTORE_Handle *h,
411 GNUNET_SCHEDULER_TaskCallback error_cb,
412 void *error_cb_cls);
413
414/**
415 * Begin rollback all actions in a transaction.
416 * Reverts all actions performed since #GNUNET_NAMESTORE_transaction_begin
417 *
418 * @param h handle to the namestore
419 * @param error_cb function to call on error (i.e. disconnect or unable to get lock)
420 * the handle is afterwards invalid
421 * @param error_cb_cls closure for @a error_cb
422 * @return handle to abort the request
423 */
424struct GNUNET_NAMESTORE_QueueEntry *
425GNUNET_NAMESTORE_transaction_abort (struct GNUNET_NAMESTORE_Handle *h,
426 GNUNET_SCHEDULER_TaskCallback error_cb,
427 void *error_cb_cls);
428/**
429 * Commit a namestore transaction.
430 * Saves all actions performed since #GNUNET_NAMESTORE_transaction_begin
431 *
432 * @param h handle to the namestore
433 * @param error_cb function to call on error (i.e. disconnect or unable to get lock)
434 * the handle is afterwards invalid
435 * @param error_cb_cls closure for @a error_cb
436 * @return handle to abort the request
437 */
438struct GNUNET_NAMESTORE_QueueEntry *
439GNUNET_NAMESTORE_transaction_commit (struct GNUNET_NAMESTORE_Handle *h,
440 GNUNET_SCHEDULER_TaskCallback error_cb,
441 void *error_cb_cls);
442
443/**
444 * Lookup an item in the namestore.
445 * 618 *
446 * @param h handle to the namestore 619 * @param h handle to the namestore
447 * @param pkey private key of the zone 620 * @param pkey the private key of the zone to edit
448 * @param label name that is being mapped 621 * @param label the label of the record set to edit
449 * @param error_cb function to call on error (i.e. disconnect) 622 * @param editor_hint the editor hint to set as advisory lock
450 * the handle is afterwards invalid 623 * @param error_cb the error callback
451 * @param error_cb_cls closure for @a error_cb 624 * @param error_cb_cls closure to #error_cb
452 * @param rm function to call with the result (with 0 records if we don't have that label); 625 * @param edit_cb the #GNUNET_NAMESTORE_EditRecordSetBeginCallback
453 * the handle is afterwards invalid 626 * @param edit_cb_cls closure to #edit_cb
454 * @param rm_cls closure for @a rm 627 * @return handle to the operation
455 * @return handle to abort the request
456 */ 628 */
457struct GNUNET_NAMESTORE_QueueEntry * 629struct GNUNET_NAMESTORE_QueueEntry *
458GNUNET_NAMESTORE_records_select (struct GNUNET_NAMESTORE_Handle *h, 630GNUNET_NAMESTORE_record_set_edit_begin (struct GNUNET_NAMESTORE_Handle *h,
459 const struct 631 const struct
460 GNUNET_IDENTITY_PrivateKey *pkey, 632 GNUNET_CRYPTO_PrivateKey *pkey,
461 const char *label, 633 const char *label,
462 GNUNET_SCHEDULER_TaskCallback error_cb, 634 const char *editor_hint,
463 void *error_cb_cls, 635 GNUNET_NAMESTORE_EditRecordSetBeginCallback
464 GNUNET_NAMESTORE_RecordMonitor rm, 636 edit_cb,
465 void *rm_cls); 637 void *edit_cb_cls);
466
467 638
468/** 639/**
469 * Creates, deletes or updates an item in the namestore. 640 * If the current advisory lock is set to the provided editor hint,
470 * If the item is already present, it is replaced with the new record set. 641 * this API cancels the editing of a record set and unsets the advisory lock in database.
471 * Use an empty array to remove all records under the given name. 642 * Optionally, a new editor hint can be provided: For example,
643 * the value that was returned in in the callback to
644 * #GNUNET_NAMESTORE_record_set_edit_begin.
472 * 645 *
473 * The continuation is called after the value has been stored in the 646 * If provided editor hint does not match the current advisory lock,
474 * database. Monitors may be notified asynchronously (basically with 647 * this function is not doing anything (NOP).
475 * a buffer). However, if any monitor is consistently too slow to
476 * keep up with the changes, calling @a cont will be delayed until the
477 * monitors do keep up.
478 * 648 *
479 * @param h handle to the namestore 649 * @param h handle to the namestore
480 * @param pkey private key of the zone 650 * @param pkey the private key of the zone to edit
481 * @param label name that is being mapped 651 * @param label the label of the record set to edit
482 * @param rd_count number of records in the 'rd' array 652 * @param editor_hint the editor hint to set as advisory lock
483 * @param rd array of records with data to store 653 * @param editor_hint_replacement the editor hint to set as advisory lock instead of clearing it
484 * @param cont continuation to call when done 654 * @param finished_cb the callback called when cancelled
485 * @param cont_cls closure for @a cont 655 * @param finished_cb_cls closure to #finished_cb
486 * @return handle to abort the request 656 * @return handle to the operation
487 */ 657 */
488struct GNUNET_NAMESTORE_QueueEntry * 658struct GNUNET_NAMESTORE_QueueEntry *
489GNUNET_NAMESTORE_records_replace (struct GNUNET_NAMESTORE_Handle *h, 659GNUNET_NAMESTORE_record_set_edit_cancel (struct GNUNET_NAMESTORE_Handle *h,
490 const struct GNUNET_IDENTITY_PrivateKey *pkey, 660 const struct
491 const char *label, 661 GNUNET_CRYPTO_PrivateKey *pkey,
492 unsigned int rd_count, 662 const char *label,
493 const struct GNUNET_GNSRECORD_Data *rd, 663 const char *editor_hint,
494 GNUNET_NAMESTORE_ContinuationWithStatus cont, 664 const char *editor_hint_replacement,
495 void *cont_cls); 665 GNUNET_NAMESTORE_ContinuationWithStatus
666 finished_cb,
667 void *finished_cls);
496 668
497#if 0 /* keep Emacsens' auto-indent happy */ 669#if 0 /* keep Emacsens' auto-indent happy */
498{ 670{
@@ -504,3 +676,5 @@ GNUNET_NAMESTORE_records_replace (struct GNUNET_NAMESTORE_Handle *h,
504#endif 676#endif
505 677
506/** @} */ /* end of group */ 678/** @} */ /* end of group */
679
680/** @} */ /* end of group addition */