diff options
author | Christian Grothoff <christian@grothoff.org> | 2012-02-20 15:20:46 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2012-02-20 15:20:46 +0000 |
commit | c7e7b05c19dd113c065a73dde7d60a68e5fe7659 (patch) | |
tree | 368498ba29c9553b0f436baa429d57f41a94c1f3 /src/include/gnunet_namestore_plugin.h | |
parent | e36402e85e1c81ef2a11a8566564cd4d7d999fc6 (diff) | |
download | gnunet-c7e7b05c19dd113c065a73dde7d60a68e5fe7659.tar.gz gnunet-c7e7b05c19dd113c065a73dde7d60a68e5fe7659.zip |
-plugin api design for namestore
Diffstat (limited to 'src/include/gnunet_namestore_plugin.h')
-rw-r--r-- | src/include/gnunet_namestore_plugin.h | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/src/include/gnunet_namestore_plugin.h b/src/include/gnunet_namestore_plugin.h new file mode 100644 index 000000000..e93adb22c --- /dev/null +++ b/src/include/gnunet_namestore_plugin.h | |||
@@ -0,0 +1,254 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | (C) 2012 Christian Grothoff (and other contributing authors) | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify | ||
6 | it under the terms of the GNU General Public License as published | ||
7 | by the Free Software Foundation; either version 2, or (at your | ||
8 | 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 | General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU General Public License | ||
16 | along with GNUnet; see the file COPYING. If not, write to the | ||
17 | Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
18 | Boston, MA 02111-1307, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @file include/gnunet_namestore_plugin.h | ||
23 | * @brief plugin API for the namestore database backend | ||
24 | * @author Christian Grothoff | ||
25 | * | ||
26 | * Other functions we might want: | ||
27 | * - enumerate all known zones | ||
28 | */ | ||
29 | #ifndef GNUNET_NAMESTORE_PLUGIN_H | ||
30 | #define GNUNET_NAMESTORE_PLUGIN_H | ||
31 | |||
32 | #include "gnunet_namestore_service.h" | ||
33 | |||
34 | #ifdef __cplusplus | ||
35 | extern "C" | ||
36 | { | ||
37 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
38 | } | ||
39 | #endif | ||
40 | #endif | ||
41 | |||
42 | |||
43 | /** | ||
44 | * Function called by for each matching record. | ||
45 | * | ||
46 | * @param cls closure | ||
47 | * @param zone hash of the public key of the zone | ||
48 | * @param record_hash hash of the record | ||
49 | * @param record_key XOR of zone and hash of name | ||
50 | * @param name name that is being mapped (at most 255 characters long) | ||
51 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | ||
52 | * @param expiration expiration time for the content | ||
53 | * @param flags flags for the content | ||
54 | * @param data_size number of bytes in data | ||
55 | * @param data value, semantics depend on 'record_type' (see RFCs for DNS and | ||
56 | * GNS specification for GNS extensions) | ||
57 | */ | ||
58 | typedef void (*GNUNET_NAMESTORE_RecordIterator) (void *cls, | ||
59 | const GNUNET_HashCode *zone, | ||
60 | const GNUNET_HashCode *record_hash, | ||
61 | const GNUNET_HashCode *record_key, | ||
62 | const char *name, | ||
63 | uint32_t record_type, | ||
64 | struct GNUNET_TIME_Absolute expiration, | ||
65 | enum GNUNET_NAMESTORE_RecordFlags flags, | ||
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 struct 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 | ||
96 | * @param root_hash top level hash that is being signed | ||
97 | */ | ||
98 | typedef void (*GNUNET_NAMESTORE_SignatureCallback) (void *cls, | ||
99 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key, | ||
100 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | ||
101 | const struct GNUNET_CRYPTO_RsaSignature *top_sig, | ||
102 | const GNUNET_HashCode *root_hash); | ||
103 | |||
104 | |||
105 | /** | ||
106 | * @brief struct returned by the initialization function of the plugin | ||
107 | */ | ||
108 | struct GNUNET_NAMESTORE_PluginFunctions | ||
109 | { | ||
110 | |||
111 | /** | ||
112 | * Closure to pass to all plugin functions. | ||
113 | */ | ||
114 | void *cls; | ||
115 | |||
116 | /** | ||
117 | * Store a record in the datastore. | ||
118 | * | ||
119 | * @param cls closure (internal context for the plugin) | ||
120 | * @param zone hash of the public key of the zone | ||
121 | * @param record_hash hash of the record | ||
122 | * @param record_key XOR of zone and hash of name | ||
123 | * @param name name that is being mapped (at most 255 characters long) | ||
124 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | ||
125 | * @param expiration expiration time for the content | ||
126 | * @param flags flags for the content | ||
127 | * @param data_size number of bytes in data | ||
128 | * @param data value, semantics depend on 'record_type' (see RFCs for DNS and | ||
129 | * GNS specification for GNS extensions) | ||
130 | * @return GNUNET_OK on success | ||
131 | */ | ||
132 | int (*put_record) (void *cls, | ||
133 | const GNUNET_HashCode *zone, | ||
134 | const GNUNET_HashCode *record_hash, | ||
135 | const GNUNET_HashCode *record_key, | ||
136 | const char *name, | ||
137 | uint32_t record_type, | ||
138 | struct GNUNET_TIME_Absolute expiration, | ||
139 | enum GNUNET_NAMESTORE_RecordFlags flags, | ||
140 | size_t data_size, | ||
141 | const void *data); | ||
142 | |||
143 | |||
144 | /** | ||
145 | * Store a Merkle tree node in the datastore. | ||
146 | * | ||
147 | * @param cls closure (internal context for the plugin) | ||
148 | * @param zone hash of public key of the zone | ||
149 | * @param loc location in the B-tree | ||
150 | * @param ploc parent's location in the B-tree (must have depth = loc.depth - 1), NULL for root | ||
151 | * @param num_entries number of entries at this node in the B-tree | ||
152 | * @param entries the 'num_entries' entries to store (hashes over the | ||
153 | * records) | ||
154 | * @return GNUNET_OK on success | ||
155 | */ | ||
156 | int (*put_node) (void *cls, | ||
157 | const struct GNUNET_HashCode *zone, | ||
158 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | ||
159 | const struct GNUNET_NAMESTORE_SignatureLocation *ploc, | ||
160 | unsigned int num_entries, | ||
161 | const GNUNET_HashCode *entries); | ||
162 | |||
163 | |||
164 | /** | ||
165 | * Store a zone signature in the datastore. If a signature for the zone with a | ||
166 | * lower depth exists, the old signature is removed. If a signature for an | ||
167 | * older revision of the zone exists, this will delete all records, nodes | ||
168 | * and signatures for the older revision of the zone. | ||
169 | * | ||
170 | * @param cls closure (internal context for the plugin) | ||
171 | * @param zone_key public key of the zone | ||
172 | * @param loc location in the B-tree (top of the tree, offset 0, depth at 'maximum') | ||
173 | * @param top_sig signature at the top, NULL if 'loc.depth > 0' | ||
174 | * @param root_hash top level hash that is signed | ||
175 | * @return GNUNET_OK on success | ||
176 | */ | ||
177 | int (*put_signature) (void *cls, | ||
178 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key, | ||
179 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | ||
180 | const struct GNUNET_CRYPTO_RsaSignature *top_sig, | ||
181 | const GNUNET_HashCode *root_hash); | ||
182 | |||
183 | |||
184 | /** | ||
185 | * Iterate over the results for a particular key and zone in the | ||
186 | * datastore. Will only query the latest revision known for the | ||
187 | * zone (as adding a new zone revision will cause the plugin to | ||
188 | * delete all records from previous revisions). | ||
189 | * | ||
190 | * @param cls closure (internal context for the plugin) | ||
191 | * @param zone hash of public key of the zone | ||
192 | * @param record_key key for the record (XOR of zone and hash of name); | ||
193 | * NULL to iterate over all records of the zone | ||
194 | * @param iter maybe NULL (to just count) | ||
195 | * @param iter_cls closure for iter | ||
196 | * @return the number of results found | ||
197 | */ | ||
198 | unsigned int (*iterate_records) (void *cls, | ||
199 | const GNUNET_HashCode *zone, | ||
200 | const GNUNET_HashCode *record_key, | ||
201 | GNUNET_NAMESTORE_RecordIterator iter, void *iter_cls); | ||
202 | |||
203 | |||
204 | /** | ||
205 | * Get a particular node from the signature tree. | ||
206 | * | ||
207 | * @param cls closure (internal context for the plugin) | ||
208 | * @param zone hash of public key of the zone | ||
209 | * @param loc location of the node in the signature tree | ||
210 | * @param cb function to call with the result | ||
211 | * @param cb_cls closure for cont | ||
212 | */ | ||
213 | void (*get_node) (void *cls, | ||
214 | const GNUNET_HashCode *zone, | ||
215 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | ||
216 | GNUNET_NAMESTORE_NodeCallback cb, void *cb_cls); | ||
217 | |||
218 | |||
219 | /** | ||
220 | * Get the current signature for a zone. | ||
221 | * | ||
222 | * @param cls closure (internal context for the plugin) | ||
223 | * @param zone hash of public key of the zone | ||
224 | * @param cb function to call with the result | ||
225 | * @param cb_cls closure for cont | ||
226 | */ | ||
227 | void (*get_signature) (void *cls, | ||
228 | const GNUNET_HashCode *zone, | ||
229 | GNUNET_NAMESTORE_SignatureCallback cb, void *cb_cls); | ||
230 | |||
231 | |||
232 | /** | ||
233 | * Delete an entire zone (all revisions, all records, all nodes, | ||
234 | * all signatures). Not used in normal operation. | ||
235 | * | ||
236 | * @param cls closure (internal context for the plugin) | ||
237 | * @param zone zone to delete | ||
238 | */ | ||
239 | void (*delete_zone) (void *cls, | ||
240 | const GNUNET_HashCode *zone); | ||
241 | |||
242 | |||
243 | }; | ||
244 | |||
245 | |||
246 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
247 | { | ||
248 | #endif | ||
249 | #ifdef __cplusplus | ||
250 | } | ||
251 | #endif | ||
252 | |||
253 | /* end of gnunet_namestore_plugin.h */ | ||
254 | #endif | ||