diff options
author | Christian Grothoff <christian@grothoff.org> | 2012-02-23 13:33:26 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2012-02-23 13:33:26 +0000 |
commit | b8ca2af15579933b2acca79908a19e08535abe26 (patch) | |
tree | 1945e8a115fc1801c8463b198043a19b40c4b93c /src/include/gnunet_namestore_plugin.h | |
parent | 27ee63d892f4cd54c785cd9b6082b4863b631284 (diff) | |
download | gnunet-b8ca2af15579933b2acca79908a19e08535abe26.tar.gz gnunet-b8ca2af15579933b2acca79908a19e08535abe26.zip |
-revised plugin API
Diffstat (limited to 'src/include/gnunet_namestore_plugin.h')
-rw-r--r-- | src/include/gnunet_namestore_plugin.h | 196 |
1 files changed, 46 insertions, 150 deletions
diff --git a/src/include/gnunet_namestore_plugin.h b/src/include/gnunet_namestore_plugin.h index 8ff2adf4a..5eb01684b 100644 --- a/src/include/gnunet_namestore_plugin.h +++ b/src/include/gnunet_namestore_plugin.h | |||
@@ -22,9 +22,6 @@ | |||
22 | * @file include/gnunet_namestore_plugin.h | 22 | * @file include/gnunet_namestore_plugin.h |
23 | * @brief plugin API for the namestore database backend | 23 | * @brief plugin API for the namestore database backend |
24 | * @author Christian Grothoff | 24 | * @author Christian Grothoff |
25 | * | ||
26 | * Other functions we might want: | ||
27 | * - enumerate all known zones | ||
28 | */ | 25 | */ |
29 | #ifndef GNUNET_NAMESTORE_PLUGIN_H | 26 | #ifndef GNUNET_NAMESTORE_PLUGIN_H |
30 | #define GNUNET_NAMESTORE_PLUGIN_H | 27 | #define GNUNET_NAMESTORE_PLUGIN_H |
@@ -46,62 +43,22 @@ extern "C" | |||
46 | * Function called by for each matching record. | 43 | * Function called by for each matching record. |
47 | * | 44 | * |
48 | * @param cls closure | 45 | * @param cls closure |
49 | * @param zone hash of the public key of the zone | 46 | * @param zone_key public key of the zone |
50 | * @param loc location of the signature for this record | 47 | * @param expire when does the corresponding block in the DHT expire (until |
48 | * when should we never do a DHT lookup for the same name again)? | ||
51 | * @param name name that is being mapped (at most 255 characters long) | 49 | * @param name name that is being mapped (at most 255 characters long) |
52 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | 50 | * @param rd_count number of entries in 'rd' array |
53 | * @param expiration expiration time for the content | 51 | * @param rd array of records with data to store |
54 | * @param flags flags for the content | 52 | * @param signature signature of the record block, NULL if signature is unavailable (i.e. |
55 | * @param data_size number of bytes in data | 53 | * because the user queried for a particular record type only) |
56 | * @param data value, semantics depend on 'record_type' (see RFCs for DNS and | ||
57 | * GNS specification for GNS extensions) | ||
58 | */ | 54 | */ |
59 | typedef void (*GNUNET_NAMESTORE_RecordIterator) (void *cls, | 55 | typedef void (*GNUNET_NAMESTORE_RecordIterator) (void *cls, |
60 | const GNUNET_HashCode *zone, | 56 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key, |
61 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | 57 | struct GNUNET_TIME_Absolute expire, |
62 | const char *name, | 58 | const char *name, |
63 | uint32_t record_type, | 59 | unsigned int rd_count, |
64 | struct GNUNET_TIME_Absolute expiration, | 60 | const struct GNUNET_NAMESTORE_RecordData *rd, |
65 | enum GNUNET_NAMESTORE_RecordFlags flags, | 61 | const struct GNUNET_CRYPTO_RsaSignature *signature); |
66 | size_t data_size, | ||
67 | const void *data); | ||
68 | |||
69 | |||
70 | /** | ||
71 | * Function called with the matching node. | ||
72 | * | ||
73 | * @param cls closure | ||
74 | * @param zone hash of public key of the zone | ||
75 | * @param loc location in the B-tree | ||
76 | * @param ploc parent's location in the B-tree (must have depth = loc.depth - 1), NULL for root | ||
77 | * @param num_entries number of entries at this node in the B-tree | ||
78 | * @param entries the 'num_entries' entries to store (hashes over the | ||
79 | * records) | ||
80 | */ | ||
81 | typedef void (*GNUNET_NAMESTORE_NodeCallback) (void *cls, | ||
82 | const GNUNET_HashCode *zone, | ||
83 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | ||
84 | const struct GNUNET_NAMESTORE_SignatureLocation *ploc, | ||
85 | unsigned int num_entries, | ||
86 | const GNUNET_HashCode *entries); | ||
87 | |||
88 | |||
89 | /** | ||
90 | * Function called with the matching signature. | ||
91 | * | ||
92 | * @param cls closure | ||
93 | * @param zone public key of the zone | ||
94 | * @param loc location of the root in the B-tree (depth, revision) | ||
95 | * @param top_sig signature signing the zone | ||
96 | * @param zone_time time the signature was created | ||
97 | * @param root_hash top level hash that is being signed | ||
98 | */ | ||
99 | typedef void (*GNUNET_NAMESTORE_SignatureCallback) (void *cls, | ||
100 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key, | ||
101 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | ||
102 | const struct GNUNET_CRYPTO_RsaSignature *top_sig, | ||
103 | struct GNUNET_TIME_Absolute zone_time, | ||
104 | const GNUNET_HashCode *root_hash); | ||
105 | 62 | ||
106 | 63 | ||
107 | /** | 64 | /** |
@@ -116,124 +73,63 @@ struct GNUNET_NAMESTORE_PluginFunctions | |||
116 | void *cls; | 73 | void *cls; |
117 | 74 | ||
118 | /** | 75 | /** |
119 | * Store a record in the datastore. | 76 | * Store a record in the datastore. Removes any existing record in the |
77 | * same zone with the same name. | ||
120 | * | 78 | * |
121 | * @param cls closure (internal context for the plugin) | 79 | * @param cls closure (internal context for the plugin) |
122 | * @param zone hash of the public key of the zone | 80 | * @param zone_key public key of the zone |
81 | * @param expire when does the corresponding block in the DHT expire (until | ||
82 | * when should we never do a DHT lookup for the same name again)? | ||
123 | * @param name name that is being mapped (at most 255 characters long) | 83 | * @param name name that is being mapped (at most 255 characters long) |
124 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | 84 | * @param rd_count number of entries in 'rd' array |
125 | * @param loc location of the signature for the record | 85 | * @param rd array of records with data to store |
126 | * @param expiration expiration time for the content | 86 | * @param signature signature of the record block, NULL if signature is unavailable (i.e. |
127 | * @param flags flags for the content | 87 | * because the user queried for a particular record type only) |
128 | * @param data_size number of bytes in data | ||
129 | * @param data value, semantics depend on 'record_type' (see RFCs for DNS and | ||
130 | * GNS specification for GNS extensions) | ||
131 | * @return GNUNET_OK on success | 88 | * @return GNUNET_OK on success |
132 | */ | 89 | */ |
133 | int (*put_record) (void *cls, | 90 | int (*put_records) (void *cls, |
134 | const GNUNET_HashCode *zone, | 91 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key, |
135 | const char *name, | 92 | struct GNUNET_TIME_Absolute expire, |
136 | uint32_t record_type, | 93 | const char *name, |
137 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | 94 | unsigned int rd_count, |
138 | struct GNUNET_TIME_Absolute expiration, | 95 | const struct GNUNET_NAMESTORE_RecordData *rd, |
139 | enum GNUNET_NAMESTORE_RecordFlags flags, | 96 | const struct GNUNET_CRYPTO_RsaSignature *signature); |
140 | size_t data_size, | ||
141 | const void *data); | ||
142 | 97 | ||
143 | 98 | ||
144 | /** | 99 | /** |
145 | * Store a Merkle tree node in the datastore. | 100 | * Removes any existing record in the given zone with the same name. |
146 | * | 101 | * |
147 | * @param cls closure (internal context for the plugin) | 102 | * @param cls closure (internal context for the plugin) |
148 | * @param zone hash of public key of the zone | 103 | * @param zone hash of the public key of the zone |
149 | * @param loc location in the B-tree | 104 | * @param name name that is being mapped (at most 255 characters long) |
150 | * @param ploc parent's location in the B-tree (must have depth = loc.depth + 1) and the | ||
151 | * revision must also match loc's revision; NULL for root | ||
152 | * @param num_entries number of entries at this node in the B-tree | ||
153 | * @param entries the 'num_entries' entries to store (hashes over the | ||
154 | * records) | ||
155 | * @return GNUNET_OK on success | 105 | * @return GNUNET_OK on success |
156 | */ | 106 | */ |
157 | int (*put_node) (void *cls, | 107 | int (*remove_records) (void *cls, |
158 | const GNUNET_HashCode *zone, | 108 | const GNUNET_HashCode *zone, |
159 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | 109 | const char *name); |
160 | const struct GNUNET_NAMESTORE_SignatureLocation *ploc, | 110 | |
161 | unsigned int num_entries, | ||
162 | const GNUNET_HashCode *entries); | ||
163 | |||
164 | 111 | ||
165 | /** | ||
166 | * Store a zone signature in the datastore. If a signature for the zone with a | ||
167 | * lower depth exists, the old signature is removed. If a signature for an | ||
168 | * older revision of the zone exists, this will delete all records, nodes | ||
169 | * and signatures for the older revision of the zone. | ||
170 | * | ||
171 | * @param cls closure (internal context for the plugin) | ||
172 | * @param zone_key public key of the zone | ||
173 | * @param loc location in the B-tree (top of the tree, offset 0, depth at 'maximum') | ||
174 | * @param top_sig signature at the top | ||
175 | * @param root_hash top level hash that is signed | ||
176 | * @param zone_time time the zone was signed | ||
177 | * @return GNUNET_OK on success | ||
178 | */ | ||
179 | int (*put_signature) (void *cls, | ||
180 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key, | ||
181 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | ||
182 | const struct GNUNET_CRYPTO_RsaSignature *top_sig, | ||
183 | const GNUNET_HashCode *root_hash, | ||
184 | struct GNUNET_TIME_Absolute zone_time); | ||
185 | |||
186 | |||
187 | /** | 112 | /** |
188 | * Iterate over the results for a particular key and zone in the | 113 | * Iterate over the results for a particular key and zone in the |
189 | * datastore. Will only query the latest revision known for the | 114 | * datastore. Will return at most one result to the iterator. |
190 | * zone (as adding a new zone revision will cause the plugin to | ||
191 | * delete all records from previous revisions). | ||
192 | * | 115 | * |
193 | * @param cls closure (internal context for the plugin) | 116 | * @param cls closure (internal context for the plugin) |
194 | * @param zone hash of public key of the zone | 117 | * @param zone hash of public key of the zone, NULL to iterate over all zones |
195 | * @param name_hash hash of name, NULL to iterate over all records of the zone | 118 | * @param name_hash hash of name, NULL to iterate over all records of the zone |
196 | * @param iter maybe NULL (to just count) | 119 | * @param offset offset in the list of all matching records |
120 | * @param iter function to call with the result | ||
197 | * @param iter_cls closure for iter | 121 | * @param iter_cls closure for iter |
198 | * @return the number of results found | 122 | * @return GNUNET_OK on success, GNUNET_NO if there were no results, GNUNET_SYSERR on error |
199 | */ | ||
200 | unsigned int (*iterate_records) (void *cls, | ||
201 | const GNUNET_HashCode *zone, | ||
202 | const GNUNET_HashCode *name_hash, | ||
203 | GNUNET_NAMESTORE_RecordIterator iter, void *iter_cls); | ||
204 | |||
205 | |||
206 | /** | ||
207 | * Get a particular node from the signature tree. | ||
208 | * | ||
209 | * @param cls closure (internal context for the plugin) | ||
210 | * @param zone hash of public key of the zone | ||
211 | * @param loc location of the node in the signature tree | ||
212 | * @param cb function to call with the result | ||
213 | * @param cb_cls closure for cont | ||
214 | */ | 123 | */ |
215 | int (*get_node) (void *cls, | 124 | int (*iterate_records) (void *cls, |
216 | const GNUNET_HashCode *zone, | 125 | const GNUNET_HashCode *zone, |
217 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | 126 | const GNUNET_HashCode *name_hash, |
218 | GNUNET_NAMESTORE_NodeCallback cb, void *cb_cls); | 127 | uint64_t offset, |
219 | 128 | GNUNET_NAMESTORE_RecordIterator iter, void *iter_cls); | |
220 | |||
221 | /** | ||
222 | * Get the current signature for a zone. | ||
223 | * | ||
224 | * @param cls closure (internal context for the plugin) | ||
225 | * @param zone hash of public key of the zone | ||
226 | * @param cb function to call with the result | ||
227 | * @param cb_cls closure for cont | ||
228 | */ | ||
229 | int (*get_signature) (void *cls, | ||
230 | const GNUNET_HashCode *zone, | ||
231 | GNUNET_NAMESTORE_SignatureCallback cb, void *cb_cls); | ||
232 | 129 | ||
233 | 130 | ||
234 | /** | 131 | /** |
235 | * Delete an entire zone (all revisions, all records, all nodes, | 132 | * Delete an entire zone (all records). Not used in normal operation. |
236 | * all signatures). Not used in normal operation. | ||
237 | * | 133 | * |
238 | * @param cls closure (internal context for the plugin) | 134 | * @param cls closure (internal context for the plugin) |
239 | * @param zone zone to delete | 135 | * @param zone zone to delete |