diff options
author | Christian Grothoff <christian@grothoff.org> | 2016-07-09 14:29:34 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2016-07-09 14:29:34 +0000 |
commit | 03374cc39814fa4bfb8d96e1165c688c44d8342f (patch) | |
tree | ed772250c49b39d82b9708ec8df0ee3e07e366d1 /src/include/gnunet_namestore_service.h | |
parent | 0c13a1e6fb0baffd83d413f313742a5f2b420297 (diff) | |
download | gnunet-03374cc39814fa4bfb8d96e1165c688c44d8342f.tar.gz gnunet-03374cc39814fa4bfb8d96e1165c688c44d8342f.zip |
make namestore API less brittle/sublte to use
Diffstat (limited to 'src/include/gnunet_namestore_service.h')
-rw-r--r-- | src/include/gnunet_namestore_service.h | 82 |
1 files changed, 53 insertions, 29 deletions
diff --git a/src/include/gnunet_namestore_service.h b/src/include/gnunet_namestore_service.h index 1918ca1ff..0add8852a 100644 --- a/src/include/gnunet_namestore_service.h +++ b/src/include/gnunet_namestore_service.h | |||
@@ -133,8 +133,8 @@ GNUNET_NAMESTORE_records_store (struct GNUNET_NAMESTORE_Handle *h, | |||
133 | * Process a record that was stored in the namestore. | 133 | * Process a record that was stored in the namestore. |
134 | * | 134 | * |
135 | * @param cls closure | 135 | * @param cls closure |
136 | * @param zone private key of the zone; NULL on disconnect | 136 | * @param zone private key of the zone |
137 | * @param label label of the records; NULL on disconnect | 137 | * @param label label of the records |
138 | * @param rd_count number of entries in @a rd array, 0 if label was deleted | 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 | 139 | * @param rd array of records with data to store |
140 | */ | 140 | */ |
@@ -170,7 +170,11 @@ GNUNET_NAMESTORE_set_nick (struct GNUNET_NAMESTORE_Handle *h, | |||
170 | * @param h handle to the namestore | 170 | * @param h handle to the namestore |
171 | * @param pkey private key of the zone | 171 | * @param pkey private key of the zone |
172 | * @param label name that is being mapped | 172 | * @param label name that is being mapped |
173 | * @param rm function to call with the result (with 0 records if we don't have that label) | 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 | ||
174 | * @param rm_cls closure for @a rm | 178 | * @param rm_cls closure for @a rm |
175 | * @return handle to abort the request | 179 | * @return handle to abort the request |
176 | */ | 180 | */ |
@@ -178,6 +182,8 @@ struct GNUNET_NAMESTORE_QueueEntry * | |||
178 | GNUNET_NAMESTORE_records_lookup (struct GNUNET_NAMESTORE_Handle *h, | 182 | GNUNET_NAMESTORE_records_lookup (struct GNUNET_NAMESTORE_Handle *h, |
179 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey, | 183 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey, |
180 | const char *label, | 184 | const char *label, |
185 | GNUNET_SCHEDULER_TaskCallback error_cb, | ||
186 | void *error_cb_cls, | ||
181 | GNUNET_NAMESTORE_RecordMonitor rm, | 187 | GNUNET_NAMESTORE_RecordMonitor rm, |
182 | void *rm_cls); | 188 | void *rm_cls); |
183 | 189 | ||
@@ -189,8 +195,12 @@ GNUNET_NAMESTORE_records_lookup (struct GNUNET_NAMESTORE_Handle *h, | |||
189 | * @param h handle to the namestore | 195 | * @param h handle to the namestore |
190 | * @param zone public key of the zone to look up in, never NULL | 196 | * @param zone public key of the zone to look up in, never NULL |
191 | * @param value_zone public key of the target zone (value), 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 | ||
192 | * @param proc function to call on the matching records, or with | 201 | * @param proc function to call on the matching records, or with |
193 | * NULL (rd_count == 0) if there are no matching records | 202 | * NULL (rd_count == 0) if there are no matching records; |
203 | * the handle is afterwards invalid | ||
194 | * @param proc_cls closure for @a proc | 204 | * @param proc_cls closure for @a proc |
195 | * @return a handle that can be used to | 205 | * @return a handle that can be used to |
196 | * cancel | 206 | * cancel |
@@ -199,7 +209,10 @@ struct GNUNET_NAMESTORE_QueueEntry * | |||
199 | GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h, | 209 | GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h, |
200 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, | 210 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, |
201 | const struct GNUNET_CRYPTO_EcdsaPublicKey *value_zone, | 211 | const struct GNUNET_CRYPTO_EcdsaPublicKey *value_zone, |
202 | GNUNET_NAMESTORE_RecordMonitor proc, void *proc_cls); | 212 | GNUNET_SCHEDULER_TaskCallback error_cb, |
213 | void *error_cb_cls, | ||
214 | GNUNET_NAMESTORE_RecordMonitor proc, | ||
215 | void *proc_cls); | ||
203 | 216 | ||
204 | 217 | ||
205 | /** | 218 | /** |
@@ -216,25 +229,38 @@ GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe); | |||
216 | 229 | ||
217 | /** | 230 | /** |
218 | * Starts a new zone iteration (used to periodically PUT all of our | 231 | * Starts a new zone iteration (used to periodically PUT all of our |
219 | * records into our DHT). This MUST lock the struct GNUNET_NAMESTORE_Handle | 232 | * records into our DHT). This MUST lock the `struct GNUNET_NAMESTORE_Handle` |
220 | * for any other calls than #GNUNET_NAMESTORE_zone_iterator_next and | 233 | * for any other calls than #GNUNET_NAMESTORE_zone_iterator_next() and |
221 | * #GNUNET_NAMESTORE_zone_iteration_stop. @a proc will be called once | 234 | * #GNUNET_NAMESTORE_zone_iteration_stop. @a proc will be called once |
222 | * immediately, and then again after | 235 | * immediately, and then again after |
223 | * #GNUNET_NAMESTORE_zone_iterator_next is invoked. | 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. | ||
224 | * | 241 | * |
225 | * @param h handle to the namestore | 242 | * @param h handle to the namestore |
226 | * @param zone zone to access, NULL for all zones | 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 | ||
227 | * @param proc function to call on each name from the zone; it | 247 | * @param proc function to call on each name from the zone; it |
228 | * will be called repeatedly with a value (if available) | 248 | * will be called repeatedly with a value (if available) |
229 | * and always once at the end with a label of NULL. | ||
230 | * @param proc_cls closure for @a proc | 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 | ||
231 | * @return an iterator handle to use for iteration | 253 | * @return an iterator handle to use for iteration |
232 | */ | 254 | */ |
233 | struct GNUNET_NAMESTORE_ZoneIterator * | 255 | struct GNUNET_NAMESTORE_ZoneIterator * |
234 | GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h, | 256 | GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h, |
235 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, | 257 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, |
258 | GNUNET_SCHEDULER_TaskCallback error_cb, | ||
259 | void *error_cb_cls, | ||
236 | GNUNET_NAMESTORE_RecordMonitor proc, | 260 | GNUNET_NAMESTORE_RecordMonitor proc, |
237 | void *proc_cls); | 261 | void *proc_cls, |
262 | GNUNET_SCHEDULER_TaskCallback finish_cb, | ||
263 | void *finish_cb_cls); | ||
238 | 264 | ||
239 | 265 | ||
240 | /** | 266 | /** |
@@ -265,44 +291,42 @@ struct GNUNET_NAMESTORE_ZoneMonitor; | |||
265 | 291 | ||
266 | 292 | ||
267 | /** | 293 | /** |
268 | * Function called once the monitor has caught up with the current | ||
269 | * state of the database. Will be called AGAIN after each disconnect | ||
270 | * (record monitor called with 'NULL' for zone_key) once we're again | ||
271 | * in sync. | ||
272 | * | ||
273 | * @param cls closure | ||
274 | */ | ||
275 | typedef void | ||
276 | (*GNUNET_NAMESTORE_RecordsSynchronizedCallback)(void *cls); | ||
277 | |||
278 | |||
279 | /** | ||
280 | * Begin monitoring a zone for changes. Will first call the @a | 294 | * Begin monitoring a zone for changes. Will first call the @a |
281 | * monitor function on all existing records in the selected zone(s) if | 295 | * monitor function on all existing records in the selected zone(s) if |
282 | * @a iterate_first is #GNUNET_YES. In any case, we will then call @a | 296 | * @a iterate_first is #GNUNET_YES. In any case, we will then call @a |
283 | * sync_cb, and then afterwards call the @a monitor whenever a record | 297 | * sync_cb, and then afterwards call the @a monitor whenever a record |
284 | * changes. If the namestore disconnects, the @a monitor function is | 298 | * changes. If the namestore disconnects, the @a error_cb function is |
285 | * called with a disconnect event; if the connection is | 299 | * called with a disconnect event. Once the connection is |
286 | * re-established, the process begins from the start (depending on @a | 300 | * re-established, the process begins from the start (depending on @a |
287 | * iterate_first, we first do all existing records, then @a sync, then | 301 | * iterate_first, we will again first do all existing records, then @a |
288 | * updates). | 302 | * sync, then updates). |
289 | * | 303 | * |
290 | * @param cfg configuration to use to connect to namestore | 304 | * @param cfg configuration to use to connect to namestore |
291 | * @param zone zone to monitor, NULL for all zones | 305 | * @param zone zone to monitor, NULL for all zones |
292 | * @param iterate_first #GNUNET_YES to first iterate over all existing records, | 306 | * @param iterate_first #GNUNET_YES to first iterate over all existing records, |
293 | * #GNUNET_NO to only return changes that happen from now on | 307 | * #GNUNET_NO to only return changes that happen from now on |
308 | * @param error_cb function to call on error (i.e. disconnect); note that | ||
309 | * unlike the other error callbacks in this API, a call to this | ||
310 | * function does NOT destroy the monitor handle, it merely signals | ||
311 | * that monitoring is down. You need to still explicitly call | ||
312 | * #GNUNET_NAMESTORE_zone_monitor_stop(). | ||
313 | * @param error_cb_cls closure for @a error_cb | ||
294 | * @param monitor function to call on zone changes | 314 | * @param monitor function to call on zone changes |
315 | * @param monitor_cls closure for @a monitor | ||
295 | * @param sync_cb function called when we're in sync with the namestore | 316 | * @param sync_cb function called when we're in sync with the namestore |
296 | * @param cls closure for @a monitor and @a sync_cb | 317 | * @param sync_cb_cls closure for @a sync_cb |
297 | * @return handle to stop monitoring | 318 | * @return handle to stop monitoring |
298 | */ | 319 | */ |
299 | struct GNUNET_NAMESTORE_ZoneMonitor * | 320 | struct GNUNET_NAMESTORE_ZoneMonitor * |
300 | GNUNET_NAMESTORE_zone_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | 321 | GNUNET_NAMESTORE_zone_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg, |
301 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, | 322 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, |
302 | int iterate_first, | 323 | int iterate_first, |
324 | GNUNET_SCHEDULER_TaskCallback error_cb, | ||
325 | void *error_cb_cls, | ||
303 | GNUNET_NAMESTORE_RecordMonitor monitor, | 326 | GNUNET_NAMESTORE_RecordMonitor monitor, |
304 | GNUNET_NAMESTORE_RecordsSynchronizedCallback sync_cb, | 327 | void *monitor_cls, |
305 | void *cls); | 328 | GNUNET_SCHEDULER_TaskCallback sync_cb, |
329 | void *sync_cb_cls); | ||
306 | 330 | ||
307 | 331 | ||
308 | /** | 332 | /** |