namestore.rst (5868B)
1 2 .. index:: 3 double: subsystem; NAMESTORE 4 5 .. _NAMESTORE-Subsystem-Dev: 6 7 NAMESTORE 8 ========= 9 10 To interact with NAMESTORE clients first connect to the NAMESTORE 11 service using the ``GNUNET_NAMESTORE_connect`` passing a configuration 12 handle. As a result they obtain a NAMESTORE handle, they can use for 13 operations, or NULL is returned if the connection failed. 14 15 To disconnect from NAMESTORE, clients use 16 ``GNUNET_NAMESTORE_disconnect`` and specify the handle to disconnect. 17 18 NAMESTORE internally uses the private key to refer to zones. These 19 private keys can be obtained from the IDENTITY subsystem. Here *egos* 20 *can be used to refer to zones or the default ego assigned to the GNS 21 subsystem can be used to obtained the master zone's private key.* 22 23 .. _Editing-Zone-Information: 24 25 Editing Zone Information 26 ^^^^^^^^^^^^^^^^^^^^^^^^ 27 28 NAMESTORE provides functions to lookup records stored under a label in a 29 zone and to store records under a label in a zone. 30 31 To store (and delete) records, the client uses the 32 ``GNUNET_NAMESTORE_records_store`` function and has to provide namestore 33 handle to use, the private key of the zone, the label to store the 34 records under, the records and number of records plus an callback 35 function. After the operation is performed NAMESTORE will call the 36 provided callback function with the result GNUNET_SYSERR on failure 37 (including timeout/queue drop/failure to validate), GNUNET_NO if content 38 was already there or not found GNUNET_YES (or other positive value) on 39 success plus an additional error message. 40 41 In addition, ``GNUNET_NAMESTORE_records_store2`` can be used to store multiple 42 record sets using a single API call. This allows the caller to import 43 a large number of (label, records) tuples in a single database transaction. 44 This is useful for large zone imports. 45 46 Records are deleted by using the store command with 0 records to store. 47 It is important to note, that records are not merged when records exist 48 with the label. So a client has first to retrieve records, merge with 49 existing records and then store the result. 50 51 To perform a lookup operation, the client uses the 52 ``GNUNET_NAMESTORE_records_lookup`` function. Here it has to pass the 53 namestore handle, the private key of the zone and the label. It also has 54 to provide a callback function which will be called with the result of 55 the lookup operation: the zone for the records, the label, and the 56 records including the number of records included. 57 58 A special operation is used to set the preferred nickname for a zone. 59 This nickname is stored with the zone and is automatically merged with 60 all labels and records stored in a zone. Here the client uses the 61 ``GNUNET_NAMESTORE_set_nick`` function and passes the private key of the 62 zone, the nickname as string plus a the callback with the result of the 63 operation. 64 65 .. _Transactional-Namestore-API: 66 67 Transactional operations 68 ^^^^^^^^^^^^^^^^^^^^^^^^ 69 70 All API calls by default are mapped to implicit single transactions in the 71 database backends. 72 This happends automatically, as most databases support implicit transactions 73 including the databases supported by NAMESTORE. 74 75 However, implicit transactions have two drawbacks: 76 77 1. When storing or deleting a lot of records individual transactions cause 78 a significant overhead in the database. 79 2. Storage and deletion of records my multiple clients concurrently can lead 80 to inconsistencies. 81 82 This is why NAMESTORE supports explicit transactions in order to efficiently 83 handle large amounds of zone data as well as keep then NAMESTORE consistent 84 when the client thinks this is necessary. 85 86 When the client wants to start a transaction, ``GNUNET_NAMESTORE_transaction_begin`` 87 is called. 88 After this call, ``GNUNET_NAMESTORE_records_lookup`` or ``GNUNET_NAMESTORE_records_store(2)`` 89 can be called successively. 90 The operations will only be commited to the database (and monitors such as ZONEMASTER 91 notified of the changes) when ``GNUNET_NAMESTORE_transaction_commit`` is used 92 to finalize the transaction. 93 Alternatively, the transaction can be aborted using ``GNUNET_NAMESTORE_transaction_rollback``. 94 Should the client disconnect after calling ``GNUNET_NAMESTORE_transaction_begin`` 95 any running transaction will automatically be rolled-back. 96 97 98 99 .. _Iterating-Zone-Information: 100 101 Iterating Zone Information 102 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 103 104 A client can iterate over all information in a zone or all zones managed 105 by NAMESTORE. Here a client uses one of the 106 ``GNUNET_NAMESTORE_zone_iteration_start(2)`` functions and passes the 107 namestore handle, the zone to iterate over and a callback function to 108 call with the result. To iterate over all the zones, it is possible to 109 pass NULL for the zone. A ``GNUNET_NAMESTORE_ZoneIterator`` handle is 110 returned to be used to continue iteration. 111 112 NAMESTORE calls the callback for every result and expects the client to 113 call ``GNUNET_NAMESTORE_zone_iterator_next`` to continue to iterate or 114 ``GNUNET_NAMESTORE_zone_iterator_stop`` to interrupt the iteration. When 115 NAMESTORE reached the last item it will call the callback with a NULL 116 value to indicate. 117 118 .. _Monitoring-Zone-Information: 119 120 Monitoring Zone Information 121 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 122 123 Clients can also monitor zones to be notified about changes. Here the 124 clients uses one of the ``GNUNET_NAMESTORE_zone_monitor_start(2)`` functions and 125 passes the private key of the zone and and a callback function to call 126 with updates for a zone. The client can specify to obtain zone 127 information first by iterating over the zone and specify a 128 synchronization callback to be called when the client and the namestore 129 are synced. 130 131 On an update, NAMESTORE will call the callback with the private key of 132 the zone, the label and the records and their number. 133 134 To stop monitoring, the client calls 135 ``GNUNET_NAMESTORE_zone_monitor_stop`` and passes the handle obtained 136 from the function to start the monitoring.