first batch of license fixes (boring)
[oweals/gnunet.git] / src / include / gnunet_namestore_service.h
1 /*
2      This file is part of GNUnet
3      Copyright (C) 2012, 2013, 2018 GNUnet e.V.
4
5      GNUnet is free software: you can redistribute it and/or modify it
6      under the terms of the GNU 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
16 /**
17  * @author Christian Grothoff
18  *
19  * @file
20  * API that can be used to store naming information on a GNUnet node;
21  *
22  * @defgroup namestore  Name Store service
23  * Store naming information on a GNUnet node.
24  *
25  * Naming information can either be records for which this peer/user is
26  * authoritative, or blocks which are cached, encrypted naming data from other
27  * peers.
28  *
29  * @see [Documentation](https://gnunet.org/namestore-subsystem)
30  *
31  * @{
32  */
33 #ifndef GNUNET_NAMESTORE_SERVICE_H
34 #define GNUNET_NAMESTORE_SERVICE_H
35
36 #include "gnunet_util_lib.h"
37 #include "gnunet_block_lib.h"
38 #include "gnunet_gnsrecord_lib.h"
39
40 #ifdef __cplusplus
41 extern "C"
42 {
43 #if 0                           /* keep Emacsens' auto-indent happy */
44 }
45 #endif
46 #endif
47
48
49 /**
50  * Entry in the queue.
51  */
52 struct GNUNET_NAMESTORE_QueueEntry;
53
54 /**
55  * Handle to the namestore service.
56  */
57 struct GNUNET_NAMESTORE_Handle;
58
59 /**
60  * Handle to the namestore zone iterator.
61  */
62 struct GNUNET_NAMESTORE_ZoneIterator;
63
64
65 /**
66  * Connect to the namestore service.
67  *
68  * @param cfg configuration to use
69  * @return handle to use to access the service
70  */
71 struct GNUNET_NAMESTORE_Handle *
72 GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
73
74
75 /**
76  * Disconnect from the namestore service (and free associated
77  * resources).  Must not be called from within operation callbacks of
78  * the API.
79  *
80  * @param h handle to the namestore
81  */
82 void
83 GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h);
84
85
86 /**
87  * Continuation called to notify client about result of the
88  * operation.
89  *
90  * @param cls closure
91  * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
92  *                #GNUNET_NO if content was already there or not found
93  *                #GNUNET_YES (or other positive value) on success
94  * @param emsg NULL on success, otherwise an error message
95  */
96 typedef void
97 (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
98                                             int32_t success,
99                                             const char *emsg);
100
101
102 /**
103  * Store an item in the namestore.  If the item is already present,
104  * it is replaced with the new record.  Use an empty array to
105  * remove all records under the given name.
106  *
107  * The continuation is called after the value has been stored in the
108  * database. Monitors may be notified asynchronously (basically with
109  * a buffer). However, if any monitor is consistently too slow to
110  * keep up with the changes, calling @a cont will be delayed until the
111  * monitors do keep up.
112  *
113  * @param h handle to the namestore
114  * @param pkey private key of the zone
115  * @param label name that is being mapped
116  * @param rd_count number of records in the 'rd' array
117  * @param rd array of records with data to store
118  * @param cont continuation to call when done
119  * @param cont_cls closure for @a cont
120  * @return handle to abort the request
121  */
122 struct GNUNET_NAMESTORE_QueueEntry *
123 GNUNET_NAMESTORE_records_store (struct GNUNET_NAMESTORE_Handle *h,
124                                 const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
125                                 const char *label,
126                                 unsigned int rd_count,
127                                 const struct GNUNET_GNSRECORD_Data *rd,
128                                 GNUNET_NAMESTORE_ContinuationWithStatus cont,
129                                 void *cont_cls);
130
131
132 /**
133  * Process a record that was stored in the namestore.
134  *
135  * @param cls closure
136  * @param zone private key of the zone
137  * @param label label of the records
138  * @param rd_count number of entries in @a rd array, 0 if label was deleted
139  * @param rd array of records with data to store
140  */
141 typedef void
142 (*GNUNET_NAMESTORE_RecordMonitor) (void *cls,
143                                    const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
144                                    const char *label,
145                                    unsigned int rd_count,
146                                    const struct GNUNET_GNSRECORD_Data *rd);
147
148
149 /**
150  * Set the desired nick name for a zone
151  *
152  * @param h handle to the namestore
153  * @param pkey private key of the zone
154  * @param nick the nick name to set
155  * @param cont continuation to call when done
156  * @param cont_cls closure for @a cont
157  * @return handle to abort the request
158  */
159 struct GNUNET_NAMESTORE_QueueEntry *
160 GNUNET_NAMESTORE_set_nick (struct GNUNET_NAMESTORE_Handle *h,
161                            const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
162                            const char *nick,
163                            GNUNET_NAMESTORE_ContinuationWithStatus cont,
164                            void *cont_cls);
165
166
167 /**
168  * Lookup an item in the namestore.
169  *
170  * @param h handle to the namestore
171  * @param pkey private key of the zone
172  * @param label name that is being mapped
173  * @param error_cb function to call on error (i.e. disconnect)
174  *        the handle is afterwards invalid
175  * @param error_cb_cls closure for @a error_cb
176  * @param rm function to call with the result (with 0 records if we don't have that label);
177  *        the handle is afterwards invalid
178  * @param rm_cls closure for @a rm
179  * @return handle to abort the request
180  */
181 struct GNUNET_NAMESTORE_QueueEntry *
182 GNUNET_NAMESTORE_records_lookup (struct GNUNET_NAMESTORE_Handle *h,
183                                  const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
184                                  const char *label,
185                                  GNUNET_SCHEDULER_TaskCallback error_cb,
186                                  void *error_cb_cls,
187                                  GNUNET_NAMESTORE_RecordMonitor rm,
188                                  void *rm_cls);
189
190
191 /**
192  * Look for an existing PKEY delegation record for a given public key.
193  * Returns at most one result to the processor.
194  *
195  * @param h handle to the namestore
196  * @param zone private key of the zone to look up in, never NULL
197  * @param value_zone public key of the target zone (value), never NULL
198  * @param error_cb function to call on error (i.e. disconnect)
199  *        the handle is afterwards invalid
200  * @param error_cb_cls closure for @a error_cb
201  * @param proc function to call on the matching records, or with
202  *        NULL (rd_count == 0) if there are no matching records;
203  *        the handle is afterwards invalid
204  * @param proc_cls closure for @a proc
205  * @return a handle that can be used to
206  *         cancel
207  */
208 struct GNUNET_NAMESTORE_QueueEntry *
209 GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h,
210                                const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
211                                const struct GNUNET_CRYPTO_EcdsaPublicKey *value_zone,
212                                GNUNET_SCHEDULER_TaskCallback error_cb,
213                                void *error_cb_cls,
214                                GNUNET_NAMESTORE_RecordMonitor proc,
215                                void *proc_cls);
216
217
218 /**
219  * Cancel a namestore operation.  The final callback from the
220  * operation must not have been done yet.  Must be called on any
221  * namestore operation that has not yet completed prior to calling
222  * #GNUNET_NAMESTORE_disconnect.
223  *
224  * @param qe operation to cancel
225  */
226 void
227 GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
228
229
230 /**
231  * Starts a new zone iteration (used to periodically PUT all of our
232  * records into our DHT). This MUST lock the `struct GNUNET_NAMESTORE_Handle`
233  * for any other calls than #GNUNET_NAMESTORE_zone_iterator_next() and
234  * #GNUNET_NAMESTORE_zone_iteration_stop. @a proc will be called once
235  * immediately, and then again after
236  * #GNUNET_NAMESTORE_zone_iterator_next() is invoked.
237  *
238  * On error (disconnect), @a error_cb will be invoked.
239  * On normal completion, @a finish_cb proc will be
240  * invoked.
241  *
242  * @param h handle to the namestore
243  * @param zone zone to access, NULL for all zones
244  * @param error_cb function to call on error (i.e. disconnect),
245  *        the handle is afterwards invalid
246  * @param error_cb_cls closure for @a error_cb
247  * @param proc function to call on each name from the zone; it
248  *        will be called repeatedly with a value (if available)
249  * @param proc_cls closure for @a proc
250  * @param finish_cb function to call on completion
251  *        the handle is afterwards invalid
252  * @param finish_cb_cls closure for @a finish_cb
253  * @return an iterator handle to use for iteration
254  */
255 struct GNUNET_NAMESTORE_ZoneIterator *
256 GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h,
257                                        const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
258                                        GNUNET_SCHEDULER_TaskCallback error_cb,
259                                        void *error_cb_cls,
260                                        GNUNET_NAMESTORE_RecordMonitor proc,
261                                        void *proc_cls,
262                                        GNUNET_SCHEDULER_TaskCallback finish_cb,
263                                        void *finish_cb_cls);
264
265
266 /**
267  * Calls the record processor specified in #GNUNET_NAMESTORE_zone_iteration_start
268  * for the next record.
269  *
270  * @param it the iterator
271  * @param limit number of records to return to the iterator in one shot
272  *         (before #GNUNET_NAMESTORE_zone_iterator_next is to be called again)
273  */
274 void
275 GNUNET_NAMESTORE_zone_iterator_next (struct GNUNET_NAMESTORE_ZoneIterator *it,
276                                      uint64_t limit);
277
278
279 /**
280  * Stops iteration and releases the namestore handle for further calls.  Must
281  * be called on any iteration that has not yet completed prior to calling
282  * #GNUNET_NAMESTORE_disconnect.
283  *
284  * @param it the iterator
285  */
286 void
287 GNUNET_NAMESTORE_zone_iteration_stop (struct GNUNET_NAMESTORE_ZoneIterator *it);
288
289
290 /**
291  * Handle for a monitoring activity.
292  */
293 struct GNUNET_NAMESTORE_ZoneMonitor;
294
295
296 /**
297  * Begin monitoring a zone for changes.  Will first call the @a
298  * monitor function on all existing records in the selected zone(s) if
299  * @a iterate_first is #GNUNET_YES.  In any case, we will then call @a
300  * sync_cb, and then afterwards call the @a monitor whenever a record
301  * changes.  If the namestore disconnects, the @a error_cb function is
302  * called with a disconnect event. Once the connection is
303  * re-established, the process begins from the start (depending on @a
304  * iterate_first, we will again first do all existing records, then @a
305  * sync, then updates).
306  *
307  * @param cfg configuration to use to connect to namestore
308  * @param zone zone to monitor, NULL for all zones
309  * @param iterate_first #GNUNET_YES to first iterate over all existing records,
310  *                      #GNUNET_NO to only return changes that happen from now on
311  * @param error_cb function to call on error (i.e. disconnect); note that
312  *         unlike the other error callbacks in this API, a call to this
313  *         function does NOT destroy the monitor handle, it merely signals
314  *         that monitoring is down. You need to still explicitly call
315  *         #GNUNET_NAMESTORE_zone_monitor_stop().
316  * @param error_cb_cls closure for @a error_cb
317  * @param monitor function to call on zone changes, with an initial limit of 1
318  * @param monitor_cls closure for @a monitor
319  * @param sync_cb function called when we're in sync with the namestore
320  * @param sync_cb_cls closure for @a sync_cb
321  * @return handle to stop monitoring
322  */
323 struct GNUNET_NAMESTORE_ZoneMonitor *
324 GNUNET_NAMESTORE_zone_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
325                                      const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
326                                      int iterate_first,
327                                      GNUNET_SCHEDULER_TaskCallback error_cb,
328                                      void *error_cb_cls,
329                                      GNUNET_NAMESTORE_RecordMonitor monitor,
330                                      void *monitor_cls,
331                                      GNUNET_SCHEDULER_TaskCallback sync_cb,
332                                      void *sync_cb_cls);
333
334
335 /**
336  * Calls the monitor processor specified in #GNUNET_NAMESTORE_zone_monitor_start
337  * for the next record(s).  This function is used to allow clients that merely
338  * monitor the NAMESTORE to still throttle namestore operations, so we can be
339  * sure that the monitors can keep up.
340  *
341  * Note that #GNUNET_NAMESTORE_records_store() only waits for this
342  * call if the previous limit set by the client was already reached.
343  * Thus, by using a @a limit greater than 1, monitors basically enable
344  * a queue of notifications to be processed asynchronously with some
345  * delay.  Note that even with a limit of 1 the
346  * #GNUNET_NAMESTORE_records_store() function will run asynchronously
347  * and the continuation may be invoked before the monitors completed
348  * (or even started) processing the notification.  Thus, monitors will
349  * only closely track the current state of the namestore, but not
350  * be involved in the transactions.
351  *
352  * @param zm the monitor
353  * @param limit number of records to return to the iterator in one shot
354  *        (before #GNUNET_NAMESTORE_zone_monitor_next is to be called again)
355  */
356 void
357 GNUNET_NAMESTORE_zone_monitor_next (struct GNUNET_NAMESTORE_ZoneMonitor *zm,
358                                     uint64_t limit);
359
360
361 /**
362  * Stop monitoring a zone for changes.
363  *
364  * @param zm handle to the monitor activity to stop
365  */
366 void
367 GNUNET_NAMESTORE_zone_monitor_stop (struct GNUNET_NAMESTORE_ZoneMonitor *zm);
368
369
370 #if 0                           /* keep Emacsens' auto-indent happy */
371 {
372 #endif
373 #ifdef __cplusplus
374 }
375 #endif
376
377 #endif
378
379 /** @} */  /* end of group */