peerstore.rst (2279B)
1 2 .. index:: 3 double: subsystem; PEERSTORE 4 5 .. _PEERSTORE-Subsystem-Dev: 6 7 PEERSTORE 8 ========= 9 10 libgnunetpeerstore 11 ------------------ 12 13 libgnunetpeerstore is the library containing the PEERSTORE API. 14 Subsystems wishing to communicate with the PEERSTORE service use this 15 API to open a connection to PEERSTORE. This is done by calling 16 ``GNUNET_PEERSTORE_connect`` which returns a handle to the newly created 17 connection. This handle has to be used with any further calls to the 18 API. 19 20 To store a new record, the function ``GNUNET_PEERSTORE_store`` is to be 21 used which requires the record fields and a continuation function that 22 will be called by the API after the STORE request is sent to the 23 PEERSTORE service. Note that calling the continuation function does not 24 mean that the record is successfully stored, only that the STORE request 25 has been successfully sent to the PEERSTORE service. 26 ``GNUNET_PEERSTORE_store_cancel`` can be called to cancel the STORE 27 request only before the continuation function has been called. 28 29 To iterate over stored records, the function 30 ``GNUNET_PEERSTORE_iterate`` is to be used. *peerid* and *key* can be 31 set to NULL. An iterator callback function will be called with each 32 matching record found and a NULL record at the end to signal the end of 33 result set. ``GNUNET_PEERSTORE_iterate_cancel`` can be used to cancel 34 the ITERATE request before the iterator callback is called with a NULL 35 record. 36 37 To be notified with new values stored under a (subsystem, peerid, key) 38 combination, the function ``GNUNET_PEERSTORE_watch`` is to be used. This 39 will register the watcher with the PEERSTORE service, any new records 40 matching the given combination will trigger the callback function passed 41 to ``GNUNET_PEERSTORE_watch``. This continues until 42 ``GNUNET_PEERSTORE_watch_cancel`` is called or the connection to the 43 service is destroyed. 44 45 After the connection is no longer needed, the function 46 ``GNUNET_PEERSTORE_disconnect`` can be called to disconnect from the 47 PEERSTORE service. Any pending ITERATE or WATCH requests will be 48 destroyed. If the ``sync_first`` flag is set to ``GNUNET_YES``, the API 49 will delay the disconnection until all pending STORE requests are sent 50 to the PEERSTORE service, otherwise, the pending STORE requests will be 51 destroyed as well. 52 53