diff options
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/.gitignore | 2 | ||||
-rw-r--r-- | src/include/Makefile.am | 15 | ||||
-rw-r--r-- | src/include/gnunet_multicast_service.h | 925 | ||||
-rw-r--r-- | src/include/gnunet_psyc_env.h | 340 | ||||
-rw-r--r-- | src/include/gnunet_psyc_message.h | 278 | ||||
-rw-r--r-- | src/include/gnunet_psyc_service.h | 1364 | ||||
-rw-r--r-- | src/include/gnunet_psyc_slicer.h | 378 | ||||
-rw-r--r-- | src/include/gnunet_psyc_util_lib.h | 53 | ||||
-rw-r--r-- | src/include/gnunet_psycstore_plugin.h | 383 | ||||
-rw-r--r-- | src/include/gnunet_psycstore_service.h | 701 | ||||
-rw-r--r-- | src/include/gnunet_social_service.h | 1344 |
11 files changed, 5783 insertions, 0 deletions
diff --git a/src/include/.gitignore b/src/include/.gitignore new file mode 100644 index 0000000..282522d --- /dev/null +++ b/src/include/.gitignore | |||
@@ -0,0 +1,2 @@ | |||
1 | Makefile | ||
2 | Makefile.in | ||
diff --git a/src/include/Makefile.am b/src/include/Makefile.am new file mode 100644 index 0000000..8b8bcba --- /dev/null +++ b/src/include/Makefile.am | |||
@@ -0,0 +1,15 @@ | |||
1 | # This Makefile.am is in the public domain | ||
2 | SUBDIRS = . | ||
3 | |||
4 | gnunetincludedir = $(includedir)/gnunet | ||
5 | |||
6 | gnunetinclude_HEADERS = \ | ||
7 | gnunet_multicast_service.h \ | ||
8 | gnunet_psycstore_plugin.h \ | ||
9 | gnunet_psycstore_service.h \ | ||
10 | gnunet_psyc_service.h \ | ||
11 | gnunet_psyc_util_lib.h \ | ||
12 | gnunet_psyc_env.h \ | ||
13 | gnunet_psyc_message.h \ | ||
14 | gnunet_psyc_slicer.h \ | ||
15 | gnunet_social_service.h | ||
diff --git a/src/include/gnunet_multicast_service.h b/src/include/gnunet_multicast_service.h new file mode 100644 index 0000000..58fca0b --- /dev/null +++ b/src/include/gnunet_multicast_service.h | |||
@@ -0,0 +1,925 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2012, 2013 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * @author Christian Grothoff | ||
24 | * | ||
25 | * @file | ||
26 | * Multicast service; multicast messaging via CADET | ||
27 | * | ||
28 | * @defgroup multicast Multicast service | ||
29 | * Multicast messaging via CADET. | ||
30 | * @{ | ||
31 | */ | ||
32 | |||
33 | #ifndef GNUNET_MULTICAST_SERVICE_H | ||
34 | #define GNUNET_MULTICAST_SERVICE_H | ||
35 | |||
36 | #ifdef __cplusplus | ||
37 | extern "C" | ||
38 | { | ||
39 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
40 | } | ||
41 | #endif | ||
42 | #endif | ||
43 | |||
44 | #include "gnunet_util_lib.h" | ||
45 | #include "gnunet_transport_service.h" | ||
46 | |||
47 | /** | ||
48 | * Version number of GNUnet-multicast API. | ||
49 | */ | ||
50 | #define GNUNET_MULTICAST_VERSION 0x00000000 | ||
51 | |||
52 | /** | ||
53 | * Opaque handle for a multicast group member. | ||
54 | */ | ||
55 | struct GNUNET_MULTICAST_Member; | ||
56 | |||
57 | /** | ||
58 | * Handle for the origin of a multicast group. | ||
59 | */ | ||
60 | struct GNUNET_MULTICAST_Origin; | ||
61 | |||
62 | |||
63 | enum GNUNET_MULTICAST_MessageFlags | ||
64 | { | ||
65 | /** | ||
66 | * First fragment of a message. | ||
67 | */ | ||
68 | GNUNET_MULTICAST_MESSAGE_FIRST_FRAGMENT = 1 << 0, | ||
69 | |||
70 | /** | ||
71 | * Last fragment of a message. | ||
72 | */ | ||
73 | GNUNET_MULTICAST_MESSAGE_LAST_FRAGMENT = 1 << 1, | ||
74 | |||
75 | /** | ||
76 | * OR'ed flags if message is not fragmented. | ||
77 | */ | ||
78 | GNUNET_MULTICAST_MESSAGE_NOT_FRAGMENTED | ||
79 | = GNUNET_MULTICAST_MESSAGE_FIRST_FRAGMENT | ||
80 | | GNUNET_MULTICAST_MESSAGE_LAST_FRAGMENT, | ||
81 | |||
82 | /** | ||
83 | * Historic message, used only locally when replaying messages from local | ||
84 | * storage. | ||
85 | */ | ||
86 | GNUNET_MULTICAST_MESSAGE_HISTORIC = 1 << 30 | ||
87 | |||
88 | }; | ||
89 | |||
90 | |||
91 | GNUNET_NETWORK_STRUCT_BEGIN | ||
92 | |||
93 | /** | ||
94 | * Header of a multicast message fragment. | ||
95 | * | ||
96 | * This format is public as the replay mechanism must replay message fragments using the | ||
97 | * same format. This is needed as we want to integrity-check message fragments within | ||
98 | * the multicast layer to avoid multicasting mal-formed messages. | ||
99 | */ | ||
100 | struct GNUNET_MULTICAST_MessageHeader | ||
101 | { | ||
102 | |||
103 | /** | ||
104 | * Header for all multicast message fragments from the origin. | ||
105 | */ | ||
106 | struct GNUNET_MessageHeader header; | ||
107 | |||
108 | /** | ||
109 | * Number of hops this message fragment has taken since the origin. | ||
110 | * | ||
111 | * Helpful to determine shortest paths to the origin among honest peers for | ||
112 | * unicast requests from members. Updated at each hop and thus not signed and | ||
113 | * not secure. | ||
114 | */ | ||
115 | uint32_t hop_counter GNUNET_PACKED; | ||
116 | |||
117 | /** | ||
118 | * ECC signature of the message fragment. | ||
119 | * | ||
120 | * Signature must match the public key of the multicast group. | ||
121 | */ | ||
122 | struct GNUNET_CRYPTO_EddsaSignature signature; | ||
123 | |||
124 | /** | ||
125 | * Purpose for the signature and size of the signed data. | ||
126 | */ | ||
127 | struct GNUNET_CRYPTO_EccSignaturePurpose purpose; | ||
128 | |||
129 | /** | ||
130 | * Number of the message fragment, monotonically increasing starting from 1. | ||
131 | */ | ||
132 | uint64_t fragment_id GNUNET_PACKED; | ||
133 | |||
134 | /** | ||
135 | * Byte offset of this @e fragment of the @e message. | ||
136 | */ | ||
137 | uint64_t fragment_offset GNUNET_PACKED; | ||
138 | |||
139 | /** | ||
140 | * Number of the message this fragment belongs to. | ||
141 | * | ||
142 | * Set in GNUNET_MULTICAST_origin_to_all(). | ||
143 | */ | ||
144 | uint64_t message_id GNUNET_PACKED; | ||
145 | |||
146 | /** | ||
147 | * Counter that monotonically increases whenever a member parts the group. | ||
148 | * | ||
149 | * Set in GNUNET_MULTICAST_origin_to_all(). | ||
150 | * | ||
151 | * It has significance in case of replay requests: when a member has missed | ||
152 | * messages and gets a replay request: in this case if the @a group_generation | ||
153 | * is still the same before and after the missed messages, it means that no | ||
154 | * @e join or @e part operations happened during the missed messages. | ||
155 | */ | ||
156 | uint64_t group_generation GNUNET_PACKED; | ||
157 | |||
158 | /** | ||
159 | * Flags for this message fragment. | ||
160 | * | ||
161 | * @see enum GNUNET_MULTICAST_MessageFlags | ||
162 | */ | ||
163 | uint32_t flags GNUNET_PACKED; | ||
164 | |||
165 | /* Followed by message body. */ | ||
166 | }; | ||
167 | |||
168 | |||
169 | /** | ||
170 | * Header of a request from a member to the origin. | ||
171 | */ | ||
172 | struct GNUNET_MULTICAST_RequestHeader | ||
173 | { | ||
174 | /** | ||
175 | * Header for all requests from a member to the origin. | ||
176 | */ | ||
177 | struct GNUNET_MessageHeader header; | ||
178 | |||
179 | /** | ||
180 | * Public key of the sending member. | ||
181 | */ | ||
182 | struct GNUNET_CRYPTO_EcdsaPublicKey member_pub_key; | ||
183 | |||
184 | /** | ||
185 | * ECC signature of the request fragment. | ||
186 | * | ||
187 | * Signature must match the public key of the multicast group. | ||
188 | */ | ||
189 | struct GNUNET_CRYPTO_EcdsaSignature signature; | ||
190 | |||
191 | /** | ||
192 | * Purpose for the signature and size of the signed data. | ||
193 | */ | ||
194 | struct GNUNET_CRYPTO_EccSignaturePurpose purpose; | ||
195 | |||
196 | /** | ||
197 | * Number of the request fragment. | ||
198 | * Monotonically increasing from 1. | ||
199 | */ | ||
200 | uint64_t fragment_id GNUNET_PACKED; | ||
201 | |||
202 | /** | ||
203 | * Byte offset of this @e fragment of the @e request. | ||
204 | */ | ||
205 | uint64_t fragment_offset GNUNET_PACKED; | ||
206 | |||
207 | /** | ||
208 | * Number of the request this fragment belongs to. | ||
209 | * | ||
210 | * Set in GNUNET_MULTICAST_origin_to_all(). | ||
211 | */ | ||
212 | uint64_t request_id GNUNET_PACKED; | ||
213 | |||
214 | /** | ||
215 | * Flags for this request. | ||
216 | */ | ||
217 | enum GNUNET_MULTICAST_MessageFlags flags GNUNET_PACKED; | ||
218 | |||
219 | /* Followed by request body. */ | ||
220 | }; | ||
221 | |||
222 | GNUNET_NETWORK_STRUCT_END | ||
223 | |||
224 | |||
225 | /** | ||
226 | * Maximum size of a multicast message fragment. | ||
227 | */ | ||
228 | #define GNUNET_MULTICAST_FRAGMENT_MAX_SIZE (63 * 1024) | ||
229 | |||
230 | #define GNUNET_MULTICAST_FRAGMENT_MAX_PAYLOAD \ | ||
231 | (GNUNET_MULTICAST_FRAGMENT_MAX_SIZE \ | ||
232 | - sizeof (struct GNUNET_MULTICAST_MessageHeader)) | ||
233 | |||
234 | |||
235 | /** | ||
236 | * Handle that identifies a join request. | ||
237 | * | ||
238 | * Used to match calls to #GNUNET_MULTICAST_JoinRequestCallback to the | ||
239 | * corresponding calls to #GNUNET_MULTICAST_join_decision(). | ||
240 | */ | ||
241 | struct GNUNET_MULTICAST_JoinHandle; | ||
242 | |||
243 | |||
244 | /** | ||
245 | * Function to call with the decision made for a join request. | ||
246 | * | ||
247 | * Must be called once and only once in response to an invocation of the | ||
248 | * #GNUNET_MULTICAST_JoinRequestCallback. | ||
249 | * | ||
250 | * @param jh | ||
251 | * Join request handle. | ||
252 | * @param is_admitted | ||
253 | * #GNUNET_YES if the join is approved, | ||
254 | * #GNUNET_NO if it is disapproved, | ||
255 | * #GNUNET_SYSERR if we cannot answer the request. | ||
256 | * @param relay_count | ||
257 | * Number of relays given. | ||
258 | * @param relays | ||
259 | * Array of suggested peers that might be useful relays to use | ||
260 | * when joining the multicast group (essentially a list of peers that | ||
261 | * are already part of the multicast group and might thus be willing | ||
262 | * to help with routing). If empty, only this local peer (which must | ||
263 | * be the multicast origin) is a good candidate for building the | ||
264 | * multicast tree. Note that it is unnecessary to specify our own | ||
265 | * peer identity in this array. | ||
266 | * @param join_resp | ||
267 | * Message to send in response to the joining peer; | ||
268 | * can also be used to redirect the peer to a different group at the | ||
269 | * application layer; this response is to be transmitted to the | ||
270 | * peer that issued the request even if admission is denied. | ||
271 | */ | ||
272 | struct GNUNET_MULTICAST_ReplayHandle * | ||
273 | GNUNET_MULTICAST_join_decision (struct GNUNET_MULTICAST_JoinHandle *jh, | ||
274 | int is_admitted, | ||
275 | uint16_t relay_count, | ||
276 | const struct GNUNET_PeerIdentity *relays, | ||
277 | const struct GNUNET_MessageHeader *join_resp); | ||
278 | |||
279 | |||
280 | /** | ||
281 | * Method called whenever another peer wants to join the multicast group. | ||
282 | * | ||
283 | * Implementations of this function must call GNUNET_MULTICAST_join_decision() | ||
284 | * with the decision. | ||
285 | * | ||
286 | * @param cls | ||
287 | * Closure. | ||
288 | * @param member_pub_key | ||
289 | * Public key of the member requesting join. | ||
290 | * @param join_msg | ||
291 | * Application-dependent join message from the new member. | ||
292 | * @param jh | ||
293 | * Join handle to pass to GNUNET_MULTICAST_join_decison(). | ||
294 | */ | ||
295 | typedef void | ||
296 | (*GNUNET_MULTICAST_JoinRequestCallback) (void *cls, | ||
297 | const struct GNUNET_CRYPTO_EcdsaPublicKey *member_pub_key, | ||
298 | const struct GNUNET_MessageHeader *join_msg, | ||
299 | struct GNUNET_MULTICAST_JoinHandle *jh); | ||
300 | |||
301 | |||
302 | /** | ||
303 | * Method called to inform about the decision in response to a join request. | ||
304 | * | ||
305 | * If @a is_admitted is not #GNUNET_YES, then the multicast service disconnects | ||
306 | * the client and the multicast member handle returned by | ||
307 | * GNUNET_MULTICAST_member_join() is invalidated. | ||
308 | * | ||
309 | * @param cls | ||
310 | * Closure. | ||
311 | * @param is_admitted | ||
312 | * #GNUNET_YES or #GNUNET_NO or #GNUNET_SYSERR | ||
313 | * @param peer | ||
314 | * The peer we are connected to and the join decision is from. | ||
315 | * @param relay_count | ||
316 | * Number of peers in the @a relays array. | ||
317 | * @param relays | ||
318 | * Peer identities of members of the group, which serve as relays | ||
319 | * and can be used to join the group at. If empty, only the origin can | ||
320 | * be used to connect to the group. | ||
321 | * @param join_msg | ||
322 | * Application-dependent join message from the origin. | ||
323 | */ | ||
324 | typedef void | ||
325 | (*GNUNET_MULTICAST_JoinDecisionCallback) (void *cls, | ||
326 | int is_admitted, | ||
327 | const struct GNUNET_PeerIdentity *peer, | ||
328 | uint16_t relay_count, | ||
329 | const struct GNUNET_PeerIdentity *relays, | ||
330 | const struct GNUNET_MessageHeader *join_msg); | ||
331 | |||
332 | |||
333 | /** | ||
334 | * Function called whenever a group member has transmitted a request | ||
335 | * to the origin (other than joining or leaving). | ||
336 | * | ||
337 | * FIXME: need to distinguish between origin cancelling a message (some fragments | ||
338 | * were sent, then the rest 'discarded') and the case where we got disconnected; | ||
339 | * right now, both would mean 'msg' is NULL, but they could be quite different... | ||
340 | * So the semantics from the receiver side of | ||
341 | * GNUNET_MULTICAST_member_to_origin_cancel() are not clear here. Maybe we | ||
342 | * should do something with the flags in this case? | ||
343 | * | ||
344 | * @param cls | ||
345 | * Closure (set from GNUNET_MULTICAST_origin_start). | ||
346 | * @param sender | ||
347 | * Identity of the sender. | ||
348 | * @param req | ||
349 | * Request to the origin. | ||
350 | * @param flags | ||
351 | * Flags for the request. | ||
352 | */ | ||
353 | typedef void | ||
354 | (*GNUNET_MULTICAST_RequestCallback) (void *cls, | ||
355 | const struct GNUNET_MULTICAST_RequestHeader *req); | ||
356 | |||
357 | |||
358 | /** | ||
359 | * Function called whenever a group member is receiving a message fragment from | ||
360 | * the origin. | ||
361 | * | ||
362 | * If admission to the group is denied, this function is called once with the | ||
363 | * response of the @e origin (as given to GNUNET_MULTICAST_join_decision()) and | ||
364 | * then a second time with NULL to indicate that the connection failed for good. | ||
365 | * | ||
366 | * FIXME: need to distinguish between origin cancelling a message (some fragments | ||
367 | * were sent, then the rest 'discarded') and the case where we got disconnected; | ||
368 | * right now, both would mean 'msg' is NULL, but they could be quite different... | ||
369 | * So the semantics from the receiver side of | ||
370 | * GNUNET_MULTICAST_origin_to_all_cancel() are not clear here. | ||
371 | * | ||
372 | * @param cls | ||
373 | * Closure (set from GNUNET_MULTICAST_member_join()) | ||
374 | * @param msg | ||
375 | * Message from the origin, NULL if the origin shut down | ||
376 | * (or we were kicked out, and we should thus call | ||
377 | * GNUNET_MULTICAST_member_part() next) | ||
378 | */ | ||
379 | typedef void | ||
380 | (*GNUNET_MULTICAST_MessageCallback) (void *cls, | ||
381 | const struct GNUNET_MULTICAST_MessageHeader *msg); | ||
382 | |||
383 | |||
384 | /** | ||
385 | * Opaque handle to a replay request from the multicast service. | ||
386 | */ | ||
387 | struct GNUNET_MULTICAST_ReplayHandle; | ||
388 | |||
389 | |||
390 | /** | ||
391 | * Functions with this signature are called whenever the multicast service needs | ||
392 | * a message fragment to be replayed by fragment_id. | ||
393 | * | ||
394 | * Implementations of this function MUST call GNUNET_MULTICAST_replay() ONCE | ||
395 | * (with a message or an error); however, if the origin is destroyed or the | ||
396 | * group is left, the replay handle must no longer be used. | ||
397 | * | ||
398 | * @param cls | ||
399 | * Closure (set from GNUNET_MULTICAST_origin_start() | ||
400 | * or GNUNET_MULTICAST_member_join()). | ||
401 | * @param member_pub_key | ||
402 | * The member requesting replay. | ||
403 | * @param fragment_id | ||
404 | * Which message fragment should be replayed. | ||
405 | * @param flags | ||
406 | * Flags for the replay. | ||
407 | * @param rh | ||
408 | * Handle to pass to message transmit function. | ||
409 | */ | ||
410 | typedef void | ||
411 | (*GNUNET_MULTICAST_ReplayFragmentCallback) (void *cls, | ||
412 | const struct GNUNET_CRYPTO_EcdsaPublicKey *member_pub_key, | ||
413 | uint64_t fragment_id, | ||
414 | uint64_t flags, | ||
415 | struct GNUNET_MULTICAST_ReplayHandle *rh); | ||
416 | |||
417 | /** | ||
418 | * Functions with this signature are called whenever the multicast service needs | ||
419 | * a message fragment to be replayed by message_id and fragment_offset. | ||
420 | * | ||
421 | * Implementations of this function MUST call GNUNET_MULTICAST_replay() ONCE | ||
422 | * (with a message or an error); however, if the origin is destroyed or the | ||
423 | * group is left, the replay handle must no longer be used. | ||
424 | * | ||
425 | * @param cls | ||
426 | * Closure (set from GNUNET_MULTICAST_origin_start() | ||
427 | * or GNUNET_MULTICAST_member_join()). | ||
428 | * @param member_pub_key | ||
429 | * The member requesting replay. | ||
430 | * @param message_id | ||
431 | * Which message should be replayed. | ||
432 | * @param fragment_offset | ||
433 | * Offset of the fragment within of @a message_id to be replayed. | ||
434 | * @param flags | ||
435 | * Flags for the replay. | ||
436 | * @param rh | ||
437 | * Handle to pass to message transmit function. | ||
438 | */ | ||
439 | typedef void | ||
440 | (*GNUNET_MULTICAST_ReplayMessageCallback) (void *cls, | ||
441 | const struct GNUNET_CRYPTO_EcdsaPublicKey *member_pub_key, | ||
442 | uint64_t message_id, | ||
443 | uint64_t fragment_offset, | ||
444 | uint64_t flags, | ||
445 | struct GNUNET_MULTICAST_ReplayHandle *rh); | ||
446 | |||
447 | |||
448 | /** | ||
449 | * Possible error codes during replay. | ||
450 | */ | ||
451 | enum GNUNET_MULTICAST_ReplayErrorCode | ||
452 | { | ||
453 | |||
454 | /** | ||
455 | * Everything is fine. | ||
456 | */ | ||
457 | GNUNET_MULTICAST_REC_OK = 0, | ||
458 | |||
459 | /** | ||
460 | * Message fragment not found in the message store. | ||
461 | * | ||
462 | * Either discarded if it is too old, or not arrived yet if this member has | ||
463 | * missed some messages. | ||
464 | */ | ||
465 | GNUNET_MULTICAST_REC_NOT_FOUND = 1, | ||
466 | |||
467 | /** | ||
468 | * Fragment ID counter was larger than the highest counter this | ||
469 | * replay function has ever encountered; thus it is likely the | ||
470 | * origin never sent it and we're at the HEAD of the multicast | ||
471 | * stream as far as this node is concerned. | ||
472 | * | ||
473 | * FIXME: needed? | ||
474 | */ | ||
475 | GNUNET_MULTICAST_REC_PAST_HEAD = 2, | ||
476 | |||
477 | /** | ||
478 | * Access is denied to the requested fragment, membership test did not pass. | ||
479 | */ | ||
480 | GNUNET_MULTICAST_REC_ACCESS_DENIED = 3, | ||
481 | |||
482 | /** | ||
483 | * Internal error (i.e. database error). Try some other peer. | ||
484 | */ | ||
485 | GNUNET_MULTICAST_REC_INTERNAL_ERROR = 4 | ||
486 | |||
487 | }; | ||
488 | |||
489 | |||
490 | /** | ||
491 | * Replay a message fragment for the multicast group. | ||
492 | * | ||
493 | * @param rh | ||
494 | * Replay handle identifying which replay operation was requested. | ||
495 | * @param msg | ||
496 | * Replayed message fragment, NULL if not found / an error occurred. | ||
497 | * @param ec | ||
498 | * Error code. See enum GNUNET_MULTICAST_ReplayErrorCode | ||
499 | * If not #GNUNET_MULTICAST_REC_OK, the replay handle is invalidated. | ||
500 | */ | ||
501 | void | ||
502 | GNUNET_MULTICAST_replay_response (struct GNUNET_MULTICAST_ReplayHandle *rh, | ||
503 | const struct GNUNET_MessageHeader *msg, | ||
504 | enum GNUNET_MULTICAST_ReplayErrorCode ec); | ||
505 | |||
506 | |||
507 | /** | ||
508 | * Indicate the end of the replay session. | ||
509 | * | ||
510 | * Invalidates the replay handle. | ||
511 | * | ||
512 | * @param rh Replay session to end. | ||
513 | */ | ||
514 | void | ||
515 | GNUNET_MULTICAST_replay_response_end (struct GNUNET_MULTICAST_ReplayHandle *rh); | ||
516 | |||
517 | |||
518 | /** | ||
519 | * Function called to provide data for a transmission for a replay. | ||
520 | * | ||
521 | * @see GNUNET_MULTICAST_replay2() | ||
522 | */ | ||
523 | typedef int | ||
524 | (*GNUNET_MULTICAST_ReplayTransmitNotify) (void *cls, | ||
525 | size_t *data_size, | ||
526 | void *data); | ||
527 | |||
528 | |||
529 | /** | ||
530 | * Replay a message for the multicast group. | ||
531 | * | ||
532 | * @param rh | ||
533 | * Replay handle identifying which replay operation was requested. | ||
534 | * @param notify | ||
535 | * Function to call to get the message. | ||
536 | * @param notify_cls | ||
537 | * Closure for @a notify. | ||
538 | */ | ||
539 | void | ||
540 | GNUNET_MULTICAST_replay_response2 (struct GNUNET_MULTICAST_ReplayHandle *rh, | ||
541 | GNUNET_MULTICAST_ReplayTransmitNotify notify, | ||
542 | void *notify_cls); | ||
543 | |||
544 | |||
545 | /** | ||
546 | * Start a multicast group. | ||
547 | * | ||
548 | * Peers that issue GNUNET_MULTICAST_member_join() can transmit a join request | ||
549 | * to either an existing group member or to the origin. If the joining is | ||
550 | * approved, the member is cleared for @e replay and will begin to receive | ||
551 | * messages transmitted to the group. If joining is disapproved, the failed | ||
552 | * candidate will be given a response. Members in the group can send messages | ||
553 | * to the origin. | ||
554 | * | ||
555 | * TODO: This function could optionally offer to advertise the origin in the | ||
556 | * P2P overlay network(where?) under the respective public key so that other | ||
557 | * peers can find an alternate PeerId to join it. Higher level protocols may | ||
558 | * however provide other means of solving the problem of the offline host | ||
559 | * (see secushare specs about that) and therefore merely need a way to provide | ||
560 | * a list of possible PeerIds. | ||
561 | * | ||
562 | * @param cfg | ||
563 | * Configuration to use. | ||
564 | * @param priv_key | ||
565 | * ECC key that will be used to sign messages for this | ||
566 | * multicast session; public key is used to identify the multicast group; | ||
567 | * @param max_fragment_id | ||
568 | * Maximum fragment ID already sent to the group. | ||
569 | * 0 for a new group. | ||
570 | * @param join_request_cb | ||
571 | * Function called to approve / disapprove joining of a peer. | ||
572 | * @param replay_frag_cb | ||
573 | * Function that can be called to replay a message fragment. | ||
574 | * @param replay_msg_cb | ||
575 | * Function that can be called to replay a message. | ||
576 | * @param request_cb | ||
577 | * Function called with message fragments from group members. | ||
578 | * @param message_cb | ||
579 | * Function called with the message fragments sent to the | ||
580 | * network by GNUNET_MULTICAST_origin_to_all(). These message fragments | ||
581 | * should be stored for answering replay requests later. | ||
582 | * @param cls | ||
583 | * Closure for the various callbacks that follow. | ||
584 | * | ||
585 | * @return Handle for the origin, NULL on error. | ||
586 | */ | ||
587 | struct GNUNET_MULTICAST_Origin * | ||
588 | GNUNET_MULTICAST_origin_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
589 | const struct GNUNET_CRYPTO_EddsaPrivateKey *priv_key, | ||
590 | uint64_t max_fragment_id, | ||
591 | GNUNET_MULTICAST_JoinRequestCallback join_request_cb, | ||
592 | GNUNET_MULTICAST_ReplayFragmentCallback replay_frag_cb, | ||
593 | GNUNET_MULTICAST_ReplayMessageCallback replay_msg_cb, | ||
594 | GNUNET_MULTICAST_RequestCallback request_cb, | ||
595 | GNUNET_MULTICAST_MessageCallback message_cb, | ||
596 | void *cls); | ||
597 | |||
598 | /** | ||
599 | * Function called to provide data for a transmission from the origin to all | ||
600 | * members. | ||
601 | * | ||
602 | * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) | ||
603 | * invalidates the respective transmission handle. | ||
604 | * | ||
605 | * @param cls | ||
606 | * Closure. | ||
607 | * @param[in,out] data_size | ||
608 | * Initially set to the number of bytes available in | ||
609 | * @a data, should be set to the number of bytes written to data. | ||
610 | * @param[out] data | ||
611 | * Where to write the body of the message to give to the | ||
612 | * method. The function must copy at most @a data_size bytes to @a data. | ||
613 | * | ||
614 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) | ||
615 | * #GNUNET_NO on success, if more data is to be transmitted later. | ||
616 | * Should be used if @a data_size was not big enough to take all the | ||
617 | * data. If 0 is returned in @a data_size the transmission is paused, | ||
618 | * and can be resumed with GNUNET_MULTICAST_origin_to_all_resume(). | ||
619 | * #GNUNET_YES if this completes the transmission (all data supplied) | ||
620 | * @deprecated should move to MQ-style API! | ||
621 | */ | ||
622 | typedef int | ||
623 | (*GNUNET_MULTICAST_OriginTransmitNotify) (void *cls, | ||
624 | size_t *data_size, | ||
625 | void *data); | ||
626 | |||
627 | |||
628 | /** | ||
629 | * Handle for a request to send a message to all multicast group members | ||
630 | * (from the origin). | ||
631 | */ | ||
632 | struct GNUNET_MULTICAST_OriginTransmitHandle; | ||
633 | |||
634 | |||
635 | /** | ||
636 | * Send a message to the multicast group. | ||
637 | * | ||
638 | * @param origin | ||
639 | * Handle to the multicast group. | ||
640 | * @param message_id | ||
641 | * Application layer ID for the message. Opaque to multicast. | ||
642 | * @param group_generation | ||
643 | * Group generation of the message. Documented in | ||
644 | * struct GNUNET_MULTICAST_MessageHeader. | ||
645 | * @param notify | ||
646 | * Function to call to get the message. | ||
647 | * @param notify_cls | ||
648 | * Closure for @a notify. | ||
649 | * | ||
650 | * @return NULL on error (i.e. request already pending). | ||
651 | * @deprecated should move to MQ-style API! | ||
652 | */ | ||
653 | struct GNUNET_MULTICAST_OriginTransmitHandle * | ||
654 | GNUNET_MULTICAST_origin_to_all (struct GNUNET_MULTICAST_Origin *origin, | ||
655 | uint64_t message_id, | ||
656 | uint64_t group_generation, | ||
657 | GNUNET_MULTICAST_OriginTransmitNotify notify, | ||
658 | void *notify_cls); | ||
659 | |||
660 | |||
661 | |||
662 | /** | ||
663 | * Resume message transmission to multicast group. | ||
664 | * | ||
665 | * @param th Transmission to cancel. | ||
666 | */ | ||
667 | void | ||
668 | GNUNET_MULTICAST_origin_to_all_resume (struct GNUNET_MULTICAST_OriginTransmitHandle *th); | ||
669 | |||
670 | |||
671 | /** | ||
672 | * Cancel request for message transmission to multicast group. | ||
673 | * | ||
674 | * @param th Transmission to cancel. | ||
675 | */ | ||
676 | void | ||
677 | GNUNET_MULTICAST_origin_to_all_cancel (struct GNUNET_MULTICAST_OriginTransmitHandle *th); | ||
678 | |||
679 | |||
680 | /** | ||
681 | * Stop a multicast group. | ||
682 | * | ||
683 | * @param origin Multicast group to stop. | ||
684 | */ | ||
685 | void | ||
686 | GNUNET_MULTICAST_origin_stop (struct GNUNET_MULTICAST_Origin *origin, | ||
687 | GNUNET_ContinuationCallback stop_cb, | ||
688 | void *stop_cls); | ||
689 | |||
690 | |||
691 | /** | ||
692 | * Join a multicast group. | ||
693 | * | ||
694 | * The entity joining is always the local peer. Further information about the | ||
695 | * candidate can be provided in @a join_msg. If the join fails, the | ||
696 | * @a message_cb is invoked with a (failure) response and then with NULL. If | ||
697 | * the join succeeds, outstanding (state) messages and ongoing multicast | ||
698 | * messages will be given to the @a message_cb until the member decides to part | ||
699 | * the group. The @a mem_test_cb and @a replay_cb functions may be called at | ||
700 | * anytime by the multicast service to support relaying messages to other | ||
701 | * members of the group. | ||
702 | * | ||
703 | * @param cfg | ||
704 | * Configuration to use. | ||
705 | * @param group_key | ||
706 | * ECC public key that identifies the group to join. | ||
707 | * @param member_pub_key | ||
708 | * ECC key that identifies the member | ||
709 | * and used to sign requests sent to the origin. | ||
710 | * @param origin | ||
711 | * Peer ID of the origin to send unicast requsets to. If NULL, | ||
712 | * unicast requests are sent back via multiple hops on the reverse path | ||
713 | * of multicast messages. | ||
714 | * @param relay_count | ||
715 | * Number of peers in the @a relays array. | ||
716 | * @param relays | ||
717 | * Peer identities of members of the group, which serve as relays | ||
718 | * and can be used to join the group at. and send the @a join_request to. | ||
719 | * If empty, the @a join_request is sent directly to the @a origin. | ||
720 | * @param join_msg | ||
721 | * Application-dependent join message to be passed to the peer @a origin. | ||
722 | * @param join_request_cb | ||
723 | * Function called to approve / disapprove joining of a peer. | ||
724 | * @param join_decision_cb | ||
725 | * Function called to inform about the join decision. | ||
726 | * @param replay_frag_cb | ||
727 | * Function that can be called to replay message fragments | ||
728 | * this peer already knows from this group. NULL if this | ||
729 | * client is unable to support replay. | ||
730 | * @param replay_msg_cb | ||
731 | * Function that can be called to replay message fragments | ||
732 | * this peer already knows from this group. NULL if this | ||
733 | * client is unable to support replay. | ||
734 | * @param message_cb | ||
735 | * Function to be called for all message fragments we | ||
736 | * receive from the group, excluding those our @a replay_cb | ||
737 | * already has. | ||
738 | * @param cls | ||
739 | * Closure for callbacks. | ||
740 | * | ||
741 | * @return Handle for the member, NULL on error. | ||
742 | */ | ||
743 | struct GNUNET_MULTICAST_Member * | ||
744 | GNUNET_MULTICAST_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
745 | const struct GNUNET_CRYPTO_EddsaPublicKey *group_key, | ||
746 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *member_pub_key, | ||
747 | const struct GNUNET_PeerIdentity *origin, | ||
748 | uint16_t relay_count, | ||
749 | const struct GNUNET_PeerIdentity *relays, | ||
750 | const struct GNUNET_MessageHeader *join_request, | ||
751 | GNUNET_MULTICAST_JoinRequestCallback join_request_cb, | ||
752 | GNUNET_MULTICAST_JoinDecisionCallback join_decision_cb, | ||
753 | GNUNET_MULTICAST_ReplayFragmentCallback replay_frag_cb, | ||
754 | GNUNET_MULTICAST_ReplayMessageCallback replay_msg_cb, | ||
755 | GNUNET_MULTICAST_MessageCallback message_cb, | ||
756 | void *cls); | ||
757 | |||
758 | /** | ||
759 | * Handle for a replay request. | ||
760 | */ | ||
761 | struct GNUNET_MULTICAST_MemberReplayHandle; | ||
762 | |||
763 | |||
764 | /** | ||
765 | * Request a fragment to be replayed by fragment ID. | ||
766 | * | ||
767 | * Useful if messages below the @e max_known_fragment_id given when joining are | ||
768 | * needed and not known to the client. | ||
769 | * | ||
770 | * @param member | ||
771 | * Membership handle. | ||
772 | * @param fragment_id | ||
773 | * ID of a message fragment that this client would like to see replayed. | ||
774 | * @param flags | ||
775 | * Additional flags for the replay request. | ||
776 | * It is used and defined by GNUNET_MULTICAST_ReplayFragmentCallback | ||
777 | * | ||
778 | * @return Replay request handle, NULL on error. | ||
779 | */ | ||
780 | struct GNUNET_MULTICAST_MemberReplayHandle * | ||
781 | GNUNET_MULTICAST_member_replay_fragment (struct GNUNET_MULTICAST_Member *member, | ||
782 | uint64_t fragment_id, | ||
783 | uint64_t flags); | ||
784 | |||
785 | |||
786 | /** | ||
787 | * Request a message fr to be replayed. | ||
788 | * | ||
789 | * Useful if messages below the @e max_known_fragment_id given when joining are | ||
790 | * needed and not known to the client. | ||
791 | * | ||
792 | * @param member | ||
793 | * Membership handle. | ||
794 | * @param message_id | ||
795 | * ID of the message this client would like to see replayed. | ||
796 | * @param fragment_offset | ||
797 | * Offset of the fragment within the message to replay. | ||
798 | * @param flags | ||
799 | * Additional flags for the replay request. | ||
800 | * It is used & defined by GNUNET_MULTICAST_ReplayMessageCallback | ||
801 | * | ||
802 | * @return Replay request handle, NULL on error. | ||
803 | */ | ||
804 | struct GNUNET_MULTICAST_MemberReplayHandle * | ||
805 | GNUNET_MULTICAST_member_replay_message (struct GNUNET_MULTICAST_Member *member, | ||
806 | uint64_t message_id, | ||
807 | uint64_t fragment_offset, | ||
808 | uint64_t flags); | ||
809 | |||
810 | |||
811 | /** | ||
812 | * Cancel a replay request. | ||
813 | * | ||
814 | * @param rh | ||
815 | * Request to cancel. | ||
816 | */ | ||
817 | void | ||
818 | GNUNET_MULTICAST_member_replay_cancel (struct GNUNET_MULTICAST_MemberReplayHandle *rh); | ||
819 | |||
820 | |||
821 | /** | ||
822 | * Part a multicast group. | ||
823 | * | ||
824 | * Disconnects from all group members and invalidates the @a member handle. | ||
825 | * | ||
826 | * An application-dependent part message can be transmitted beforehand using | ||
827 | * #GNUNET_MULTICAST_member_to_origin()) | ||
828 | * | ||
829 | * @param member | ||
830 | * Membership handle. | ||
831 | */ | ||
832 | void | ||
833 | GNUNET_MULTICAST_member_part (struct GNUNET_MULTICAST_Member *member, | ||
834 | GNUNET_ContinuationCallback part_cb, | ||
835 | void *part_cls); | ||
836 | |||
837 | |||
838 | /** | ||
839 | * Function called to provide data for a transmission from a member to the origin. | ||
840 | * | ||
841 | * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) | ||
842 | * invalidates the respective transmission handle. | ||
843 | * | ||
844 | * @param cls | ||
845 | * Closure. | ||
846 | * @param[in,out] data_size | ||
847 | * Initially set to the number of bytes available in | ||
848 | * @a data, should be set to the number of bytes written to data. | ||
849 | * @param[out] data | ||
850 | * Where to write the body of the message to give to the | ||
851 | * method. The function must copy at most @a data_size bytes to @a data. | ||
852 | * | ||
853 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) | ||
854 | * #GNUNET_NO on success, if more data is to be transmitted later. | ||
855 | * Should be used if @a data_size was not big enough to take all the | ||
856 | * data. If 0 is returned in @a data_size the transmission is paused, | ||
857 | * and can be resumed with GNUNET_MULTICAST_member_to_origin_resume(). | ||
858 | * #GNUNET_YES if this completes the transmission (all data supplied) | ||
859 | * @deprecated should move to MQ-style API! | ||
860 | */ | ||
861 | typedef int | ||
862 | (*GNUNET_MULTICAST_MemberTransmitNotify) (void *cls, | ||
863 | size_t *data_size, | ||
864 | void *data); | ||
865 | |||
866 | |||
867 | /** | ||
868 | * Handle for a message to be delivered from a member to the origin. | ||
869 | */ | ||
870 | struct GNUNET_MULTICAST_MemberTransmitHandle; | ||
871 | |||
872 | |||
873 | /** | ||
874 | * Send a message to the origin of the multicast group. | ||
875 | * | ||
876 | * @param member | ||
877 | * Membership handle. | ||
878 | * @param request_id | ||
879 | * Application layer ID for the request. Opaque to multicast. | ||
880 | * @param notify | ||
881 | * Callback to call to get the message. | ||
882 | * @param notify_cls | ||
883 | * Closure for @a notify. | ||
884 | * | ||
885 | * @return Handle to cancel request, NULL on error (i.e. request already pending). | ||
886 | * @deprecated should move to MQ-style API! | ||
887 | */ | ||
888 | struct GNUNET_MULTICAST_MemberTransmitHandle * | ||
889 | GNUNET_MULTICAST_member_to_origin (struct GNUNET_MULTICAST_Member *member, | ||
890 | uint64_t request_id, | ||
891 | GNUNET_MULTICAST_MemberTransmitNotify notify, | ||
892 | void *notify_cls); | ||
893 | |||
894 | |||
895 | /** | ||
896 | * Resume message transmission to origin. | ||
897 | * | ||
898 | * @param th | ||
899 | * Transmission to cancel. | ||
900 | */ | ||
901 | void | ||
902 | GNUNET_MULTICAST_member_to_origin_resume (struct GNUNET_MULTICAST_MemberTransmitHandle *th); | ||
903 | |||
904 | |||
905 | /** | ||
906 | * Cancel request for message transmission to origin. | ||
907 | * | ||
908 | * @param th | ||
909 | * Transmission to cancel. | ||
910 | */ | ||
911 | void | ||
912 | GNUNET_MULTICAST_member_to_origin_cancel (struct GNUNET_MULTICAST_MemberTransmitHandle *th); | ||
913 | |||
914 | |||
915 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
916 | { | ||
917 | #endif | ||
918 | #ifdef __cplusplus | ||
919 | } | ||
920 | #endif | ||
921 | |||
922 | /* ifndef GNUNET_MULTICAST_SERVICE_H */ | ||
923 | #endif | ||
924 | |||
925 | /** @} */ /* end of group */ | ||
diff --git a/src/include/gnunet_psyc_env.h b/src/include/gnunet_psyc_env.h new file mode 100644 index 0000000..0d878cb --- /dev/null +++ b/src/include/gnunet_psyc_env.h | |||
@@ -0,0 +1,340 @@ | |||
1 | /* | ||
2 | * This file is part of GNUnet. | ||
3 | * Copyright (C) 2013 GNUnet e.V. | ||
4 | * | ||
5 | * GNUnet is free software: you can redistribute it and/or modify it | ||
6 | * under the terms of the GNU Affero General Public License as published | ||
7 | * by the Free Software Foundation, either version 3 of the License, | ||
8 | * or (at your 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 | * Affero General Public License for more details. | ||
14 | * | ||
15 | * You should have received a copy of the GNU Affero General Public License | ||
16 | * along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * | ||
24 | * @file | ||
25 | * PSYC Environment library | ||
26 | * | ||
27 | * @defgroup psyc-util-env PSYC Utilities library: Environment | ||
28 | * Environment data structure operations for PSYC and Social messages. | ||
29 | * | ||
30 | * Library providing operations for the @e environment of | ||
31 | * PSYC and Social messages, and for (de)serializing variable values. | ||
32 | * | ||
33 | * @{ | ||
34 | */ | ||
35 | |||
36 | |||
37 | #ifndef GNUNET_PSYC_ENV_H | ||
38 | #define GNUNET_PSYC_ENV_H | ||
39 | |||
40 | #ifdef __cplusplus | ||
41 | extern "C" | ||
42 | { | ||
43 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
44 | } | ||
45 | #endif | ||
46 | #endif | ||
47 | |||
48 | |||
49 | /** | ||
50 | * Possible operations on PSYC state (persistent) and transient variables (per message). | ||
51 | */ | ||
52 | enum GNUNET_PSYC_Operator | ||
53 | { | ||
54 | /** | ||
55 | * Set value of a transient variable. | ||
56 | */ | ||
57 | GNUNET_PSYC_OP_SET = ':', | ||
58 | |||
59 | /** | ||
60 | * Assign value for a persistent state variable. | ||
61 | * | ||
62 | * If an assigned value is NULL, the variable is deleted. | ||
63 | */ | ||
64 | GNUNET_PSYC_OP_ASSIGN = '=', | ||
65 | |||
66 | /** | ||
67 | * Augment state variable. | ||
68 | * | ||
69 | * Used for appending strings, adding numbers, and adding new items to a list or dictionary. | ||
70 | */ | ||
71 | GNUNET_PSYC_OP_AUGMENT = '+', | ||
72 | |||
73 | /** | ||
74 | * Diminish state variable. | ||
75 | * | ||
76 | * Used for subtracting numbers, and removing items from a list or dictionary. | ||
77 | */ | ||
78 | GNUNET_PSYC_OP_DIMINISH = '-', | ||
79 | |||
80 | /** | ||
81 | * Update state variable. | ||
82 | * | ||
83 | * Used for modifying a single item of a list or dictionary. | ||
84 | */ | ||
85 | GNUNET_PSYC_OP_UPDATE = '@', | ||
86 | }; | ||
87 | |||
88 | |||
89 | /** | ||
90 | * PSYC variable types. | ||
91 | */ | ||
92 | enum GNUNET_PSYC_Type | ||
93 | { | ||
94 | GNUNET_PSYC_TYPE_DATA = 0, | ||
95 | GNUNET_PSYC_TYPE_NUMBER, | ||
96 | GNUNET_PSYC_TYPE_LIST, | ||
97 | GNUNET_PSYC_TYPE_DICT | ||
98 | }; | ||
99 | |||
100 | |||
101 | /** | ||
102 | * PSYC state modifier. | ||
103 | */ | ||
104 | struct GNUNET_PSYC_Modifier | ||
105 | { | ||
106 | /** | ||
107 | * State operation. | ||
108 | */ | ||
109 | enum GNUNET_PSYC_Operator oper; | ||
110 | |||
111 | /** | ||
112 | * Variable name. | ||
113 | */ | ||
114 | const char *name; | ||
115 | |||
116 | /** | ||
117 | * Size of @a value. | ||
118 | */ | ||
119 | size_t value_size; | ||
120 | |||
121 | /** | ||
122 | * Value of variable. | ||
123 | */ | ||
124 | const void *value; | ||
125 | |||
126 | /** | ||
127 | * Next modifier. | ||
128 | */ | ||
129 | struct GNUNET_PSYC_Modifier *next; | ||
130 | |||
131 | /** | ||
132 | * Previous modifier. | ||
133 | */ | ||
134 | struct GNUNET_PSYC_Modifier *prev; | ||
135 | }; | ||
136 | |||
137 | |||
138 | /** | ||
139 | * Environment for a message. | ||
140 | * | ||
141 | * Contains modifiers. | ||
142 | */ | ||
143 | struct GNUNET_PSYC_Environment; | ||
144 | |||
145 | |||
146 | /** | ||
147 | * Create an environment. | ||
148 | * | ||
149 | * @return A newly allocated environment. | ||
150 | */ | ||
151 | struct GNUNET_PSYC_Environment * | ||
152 | GNUNET_PSYC_env_create (); | ||
153 | |||
154 | |||
155 | /** | ||
156 | * Add a modifier to the environment. | ||
157 | * | ||
158 | * @param env The environment. | ||
159 | * @param oper Operation to perform. | ||
160 | * @param name Name of the variable. | ||
161 | * @param value Value of the variable. | ||
162 | * @param value_size Size of @a value. | ||
163 | */ | ||
164 | void | ||
165 | GNUNET_PSYC_env_add (struct GNUNET_PSYC_Environment *env, | ||
166 | enum GNUNET_PSYC_Operator oper, const char *name, | ||
167 | const void *value, size_t value_size); | ||
168 | |||
169 | |||
170 | /** | ||
171 | * Get the first modifier of the environment. | ||
172 | */ | ||
173 | struct GNUNET_PSYC_Modifier * | ||
174 | GNUNET_PSYC_env_head (const struct GNUNET_PSYC_Environment *env); | ||
175 | |||
176 | |||
177 | |||
178 | /** | ||
179 | * Get the last modifier of the environment. | ||
180 | */ | ||
181 | struct GNUNET_PSYC_Modifier * | ||
182 | GNUNET_PSYC_env_tail (const struct GNUNET_PSYC_Environment *env); | ||
183 | |||
184 | |||
185 | /** | ||
186 | * Remove a modifier from the environment. | ||
187 | */ | ||
188 | void | ||
189 | GNUNET_PSYC_env_remove (struct GNUNET_PSYC_Environment *env, | ||
190 | struct GNUNET_PSYC_Modifier *mod); | ||
191 | |||
192 | |||
193 | /** | ||
194 | * Remove a modifier at the beginning of the environment. | ||
195 | */ | ||
196 | int | ||
197 | GNUNET_PSYC_env_shift (struct GNUNET_PSYC_Environment *env, | ||
198 | enum GNUNET_PSYC_Operator *oper, const char **name, | ||
199 | const void **value, size_t *value_size); | ||
200 | |||
201 | |||
202 | /** | ||
203 | * Iterator for modifiers in the environment. | ||
204 | * | ||
205 | * @param cls Closure. | ||
206 | * @param mod Modifier. | ||
207 | * | ||
208 | * @return #GNUNET_YES to continue iterating, | ||
209 | * #GNUNET_NO to stop. | ||
210 | */ | ||
211 | typedef int | ||
212 | (*GNUNET_PSYC_Iterator) (void *cls, enum GNUNET_PSYC_Operator oper, | ||
213 | const char *name, const char *value, | ||
214 | uint32_t value_size); | ||
215 | |||
216 | |||
217 | /** | ||
218 | * Iterate through all modifiers in the environment. | ||
219 | * | ||
220 | * @param env The environment. | ||
221 | * @param it Iterator. | ||
222 | * @param it_cls Closure for iterator. | ||
223 | */ | ||
224 | void | ||
225 | GNUNET_PSYC_env_iterate (const struct GNUNET_PSYC_Environment *env, | ||
226 | GNUNET_PSYC_Iterator it, void *it_cls); | ||
227 | |||
228 | |||
229 | /** | ||
230 | * Get the number of modifiers in the environment. | ||
231 | * | ||
232 | * @param env The environment. | ||
233 | * | ||
234 | * @return Number of modifiers. | ||
235 | */ | ||
236 | size_t | ||
237 | GNUNET_PSYC_env_get_count (const struct GNUNET_PSYC_Environment *env); | ||
238 | |||
239 | |||
240 | /** | ||
241 | * Destroy an environment. | ||
242 | * | ||
243 | * @param env The environment to destroy. | ||
244 | */ | ||
245 | void | ||
246 | GNUNET_PSYC_env_destroy (struct GNUNET_PSYC_Environment *env); | ||
247 | |||
248 | |||
249 | /** | ||
250 | * Get the type of variable. | ||
251 | * | ||
252 | * @param name Name of the variable. | ||
253 | * | ||
254 | * @return Variable type. | ||
255 | */ | ||
256 | enum GNUNET_PSYC_Type | ||
257 | GNUNET_PSYC_var_get_type (char *name); | ||
258 | |||
259 | |||
260 | /** | ||
261 | * Perform an operation on a variable. | ||
262 | * | ||
263 | * @param name Name of variable. | ||
264 | * @param current_value Current value of variable. | ||
265 | * @param current_value_size Size of @a current_value. | ||
266 | * @param oper Operator. | ||
267 | * @param args Arguments for the operation. | ||
268 | * @param args_size Size of @a args. | ||
269 | * @param return_value Return value. | ||
270 | * @param return_value_size Size of @a return_value. | ||
271 | * | ||
272 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
273 | */ | ||
274 | int | ||
275 | GNUNET_PSYC_operation (char *name, void *current_value, size_t current_value_size, | ||
276 | enum GNUNET_PSYC_Operator oper, void *args, size_t args_size, | ||
277 | void **return_value, size_t *return_value_size); | ||
278 | |||
279 | |||
280 | /** | ||
281 | * Get the variable's value as an integer. | ||
282 | * | ||
283 | * @param size Size of value. | ||
284 | * @param value Raw value of variable. | ||
285 | * @param[out] number Value converted to a 64-bit integer. | ||
286 | * | ||
287 | * @return #GNUNET_OK on success, #GNUNET_SYSERR if an error occurred (e.g. the value is invalid). | ||
288 | */ | ||
289 | int | ||
290 | GNUNET_PSYC_value_to_number (size_t size, const void *value, int64_t *number); | ||
291 | |||
292 | |||
293 | /** | ||
294 | * Get the variable's value as a dictionary. | ||
295 | * | ||
296 | * @param size Size of value. | ||
297 | * @param value Raw value of variable. | ||
298 | * @param[out] dict A newly created hashmap holding the elements of the dictionary. | ||
299 | * | ||
300 | * @return #GNUNET_OK on success, #GNUNET_SYSERR if an error occurred (e.g. the value is invalid). | ||
301 | */ | ||
302 | int | ||
303 | GNUNET_PSYC_value_to_dict (size_t size, const void *value, struct GNUNET_CONTAINER_MultiHashMap **dict); | ||
304 | |||
305 | |||
306 | /** | ||
307 | * Create a PSYC variable value from an integer. | ||
308 | * | ||
309 | * @param number The number to convert. | ||
310 | * @param[out] value_size Size of returned value. | ||
311 | * | ||
312 | * @return A newly allocated value or NULL on error. | ||
313 | */ | ||
314 | void * | ||
315 | GNUNET_PSYC_value_from_number (int64_t number, size_t *value_size); | ||
316 | |||
317 | |||
318 | /** | ||
319 | * Create a PSYC variable value from a dictionary. | ||
320 | * | ||
321 | * @param dict The dict to convert. | ||
322 | * @param[out] value_size Size of returned value. | ||
323 | * | ||
324 | * @return A newly allocated value or NULL on error. | ||
325 | */ | ||
326 | void * | ||
327 | GNUNET_PSYC_value_from_dict (struct GNUNET_CONTAINER_MultiHashMap *dict, size_t *value_size); | ||
328 | |||
329 | |||
330 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
331 | { | ||
332 | #endif | ||
333 | #ifdef __cplusplus | ||
334 | } | ||
335 | #endif | ||
336 | |||
337 | /* ifndef GNUNET_PSYC_ENV_H */ | ||
338 | #endif | ||
339 | |||
340 | /** @} */ /* end of group */ | ||
diff --git a/src/include/gnunet_psyc_message.h b/src/include/gnunet_psyc_message.h new file mode 100644 index 0000000..d0cf9cc --- /dev/null +++ b/src/include/gnunet_psyc_message.h | |||
@@ -0,0 +1,278 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2012, 2013 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * | ||
24 | * @file | ||
25 | * PSYC message utilities; receiving/transmitting/logging PSYC messages | ||
26 | * | ||
27 | * @defgroup psyc-util-message PSYC Utilities library: Messages | ||
28 | * Receiving, transmitting, logging PSYC messages. | ||
29 | * @{ | ||
30 | */ | ||
31 | |||
32 | #ifndef GNUNET_PSYC_MESSAGE_H | ||
33 | #define GNUNET_PSYC_MESSAGE_H | ||
34 | |||
35 | #ifdef __cplusplus | ||
36 | extern "C" | ||
37 | { | ||
38 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
39 | } | ||
40 | #endif | ||
41 | #endif | ||
42 | |||
43 | |||
44 | #include "gnunet_util_lib.h" | ||
45 | #include "gnunet_psyc_util_lib.h" | ||
46 | #include "gnunet_psyc_service.h" | ||
47 | |||
48 | |||
49 | /** | ||
50 | * Create a PSYC message. | ||
51 | * | ||
52 | * @param method_name | ||
53 | * PSYC method for the message. | ||
54 | * @param env | ||
55 | * Environment for the message. | ||
56 | * @param data | ||
57 | * Data payload for the message. | ||
58 | * @param data_size | ||
59 | * Size of @a data. | ||
60 | * | ||
61 | * @return Message header with size information, | ||
62 | * followed by the message parts. | ||
63 | * | ||
64 | * FIXME: arg order | ||
65 | */ | ||
66 | struct GNUNET_PSYC_Message * | ||
67 | GNUNET_PSYC_message_create (const char *method_name, | ||
68 | const struct GNUNET_PSYC_Environment *env, | ||
69 | const void *data, | ||
70 | size_t data_size); | ||
71 | |||
72 | /** | ||
73 | * Parse PSYC message. | ||
74 | * | ||
75 | * @param msg | ||
76 | * The PSYC message to parse. | ||
77 | * @param env | ||
78 | * The environment for the message with a list of modifiers. | ||
79 | * @param[out] method_name | ||
80 | * Pointer to the method name inside @a pmsg. | ||
81 | * @param[out] data | ||
82 | * Pointer to data inside @a pmsg. | ||
83 | * @param[out] data_size | ||
84 | * Size of @data is written here. | ||
85 | * | ||
86 | * @return #GNUNET_OK on success, | ||
87 | * #GNUNET_SYSERR on parse error. | ||
88 | * | ||
89 | * FIXME: arg order | ||
90 | */ | ||
91 | int | ||
92 | GNUNET_PSYC_message_parse (const struct GNUNET_PSYC_MessageHeader *msg, | ||
93 | const char **method_name, | ||
94 | struct GNUNET_PSYC_Environment *env, | ||
95 | const void **data, | ||
96 | uint16_t *data_size); | ||
97 | |||
98 | |||
99 | void | ||
100 | GNUNET_PSYC_log_message (enum GNUNET_ErrorType kind, | ||
101 | const struct GNUNET_MessageHeader *msg); | ||
102 | |||
103 | |||
104 | struct GNUNET_PSYC_TransmitHandle; | ||
105 | |||
106 | /** | ||
107 | * Create a transmission handle. | ||
108 | */ | ||
109 | struct GNUNET_PSYC_TransmitHandle * | ||
110 | GNUNET_PSYC_transmit_create (struct GNUNET_MQ_Handle *mq); | ||
111 | |||
112 | |||
113 | /** | ||
114 | * Destroy a transmission handle. | ||
115 | */ | ||
116 | void | ||
117 | GNUNET_PSYC_transmit_destroy (struct GNUNET_PSYC_TransmitHandle *tmit); | ||
118 | |||
119 | |||
120 | /** | ||
121 | * Transmit a message. | ||
122 | * | ||
123 | * @param tmit | ||
124 | * Transmission handle. | ||
125 | * @param method_name | ||
126 | * Which method should be invoked. | ||
127 | * @param env | ||
128 | * Environment for the message. | ||
129 | * Should stay available until the first call to notify_data. | ||
130 | * Can be NULL if there are no modifiers or @a notify_mod is | ||
131 | * provided instead. | ||
132 | * @param notify_mod | ||
133 | * Function to call to obtain modifiers. | ||
134 | * Can be NULL if there are no modifiers or @a env is provided instead. | ||
135 | * @param notify_data | ||
136 | * Function to call to obtain fragments of the data. | ||
137 | * @param notify_cls | ||
138 | * Closure for @a notify_mod and @a notify_data. | ||
139 | * @param flags | ||
140 | * Flags for the message being transmitted. | ||
141 | * | ||
142 | * @return #GNUNET_OK if the transmission was started. | ||
143 | * #GNUNET_SYSERR if another transmission is already going on. | ||
144 | */ | ||
145 | int | ||
146 | GNUNET_PSYC_transmit_message (struct GNUNET_PSYC_TransmitHandle *tmit, | ||
147 | const char *method_name, | ||
148 | const struct GNUNET_PSYC_Environment *env, | ||
149 | GNUNET_PSYC_TransmitNotifyModifier notify_mod, | ||
150 | GNUNET_PSYC_TransmitNotifyData notify_data, | ||
151 | void *notify_cls, | ||
152 | uint32_t flags); | ||
153 | |||
154 | |||
155 | /** | ||
156 | * Resume transmission. | ||
157 | * | ||
158 | * @param tmit Transmission handle. | ||
159 | */ | ||
160 | void | ||
161 | GNUNET_PSYC_transmit_resume (struct GNUNET_PSYC_TransmitHandle *tmit); | ||
162 | |||
163 | |||
164 | /** | ||
165 | * Abort transmission request. | ||
166 | * | ||
167 | * @param tmit Transmission handle. | ||
168 | */ | ||
169 | void | ||
170 | GNUNET_PSYC_transmit_cancel (struct GNUNET_PSYC_TransmitHandle *tmit); | ||
171 | |||
172 | |||
173 | /** | ||
174 | * Got acknowledgement of a transmitted message part, continue transmission. | ||
175 | * | ||
176 | * @param tmit Transmission handle. | ||
177 | */ | ||
178 | void | ||
179 | GNUNET_PSYC_transmit_got_ack (struct GNUNET_PSYC_TransmitHandle *tmit); | ||
180 | |||
181 | |||
182 | struct GNUNET_PSYC_ReceiveHandle; | ||
183 | |||
184 | |||
185 | /** | ||
186 | * Create handle for receiving messages. | ||
187 | */ | ||
188 | struct GNUNET_PSYC_ReceiveHandle * | ||
189 | GNUNET_PSYC_receive_create (GNUNET_PSYC_MessageCallback message_cb, | ||
190 | GNUNET_PSYC_MessagePartCallback message_part_cb, | ||
191 | void *cb_cls); | ||
192 | |||
193 | |||
194 | /** | ||
195 | * Destroy handle for receiving messages. | ||
196 | */ | ||
197 | void | ||
198 | GNUNET_PSYC_receive_destroy (struct GNUNET_PSYC_ReceiveHandle *recv); | ||
199 | |||
200 | |||
201 | /** | ||
202 | * Reset stored data related to the last received message. | ||
203 | */ | ||
204 | void | ||
205 | GNUNET_PSYC_receive_reset (struct GNUNET_PSYC_ReceiveHandle *recv); | ||
206 | |||
207 | |||
208 | /** | ||
209 | * Handle incoming PSYC message. | ||
210 | * | ||
211 | * @param recv | ||
212 | * Receive handle. | ||
213 | * @param msg | ||
214 | * The message. | ||
215 | * | ||
216 | * @return #GNUNET_OK on success, | ||
217 | * #GNUNET_SYSERR on receive error. | ||
218 | */ | ||
219 | int | ||
220 | GNUNET_PSYC_receive_message (struct GNUNET_PSYC_ReceiveHandle *recv, | ||
221 | const struct GNUNET_PSYC_MessageHeader *msg); | ||
222 | |||
223 | |||
224 | /** | ||
225 | * Check if @a data contains a series of valid message parts. | ||
226 | * | ||
227 | * @param data_size | ||
228 | * Size of @a data. | ||
229 | * @param data | ||
230 | * Data. | ||
231 | * @param[out] first_ptype | ||
232 | * Type of first message part. | ||
233 | * @param[out] last_ptype | ||
234 | * Type of last message part. | ||
235 | * | ||
236 | * @return Number of message parts found in @a data. | ||
237 | * or GNUNET_SYSERR if the message contains invalid parts. | ||
238 | */ | ||
239 | int | ||
240 | GNUNET_PSYC_receive_check_parts (uint16_t data_size, const char *data, | ||
241 | uint16_t *first_ptype, uint16_t *last_ptype); | ||
242 | |||
243 | |||
244 | /** | ||
245 | * Initialize PSYC message header. | ||
246 | */ | ||
247 | void | ||
248 | GNUNET_PSYC_message_header_init (struct GNUNET_PSYC_MessageHeader *pmsg, | ||
249 | const struct GNUNET_MULTICAST_MessageHeader *mmsg, | ||
250 | uint32_t flags); | ||
251 | |||
252 | |||
253 | /** | ||
254 | * Create a new PSYC message header from a multicast message for sending it to clients. | ||
255 | */ | ||
256 | struct GNUNET_PSYC_MessageHeader * | ||
257 | GNUNET_PSYC_message_header_create (const struct GNUNET_MULTICAST_MessageHeader *mmsg, | ||
258 | uint32_t flags); | ||
259 | |||
260 | |||
261 | /** | ||
262 | * Create a new PSYC message header from a PSYC message. | ||
263 | */ | ||
264 | struct GNUNET_PSYC_MessageHeader * | ||
265 | GNUNET_PSYC_message_header_create_from_psyc (const struct GNUNET_PSYC_Message *msg); | ||
266 | |||
267 | |||
268 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
269 | { | ||
270 | #endif | ||
271 | #ifdef __cplusplus | ||
272 | } | ||
273 | #endif | ||
274 | |||
275 | /* ifndef GNUNET_PSYC_MESSAGE_H */ | ||
276 | #endif | ||
277 | |||
278 | /** @} */ /* end of group */ | ||
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h new file mode 100644 index 0000000..3a3131e --- /dev/null +++ b/src/include/gnunet_psyc_service.h | |||
@@ -0,0 +1,1364 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2012, 2013 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * @author Christian Grothoff | ||
24 | * | ||
25 | * @file | ||
26 | * PSYC service | ||
27 | * | ||
28 | * @defgroup psyc PSYC service | ||
29 | * Send/receive messages in PSYC channels and access the PSYC Store. | ||
30 | * | ||
31 | * Note that clients of this API are NOT expected to understand the PSYC message | ||
32 | * format, only the semantics! Parsing (and serializing) the PSYC stream format | ||
33 | * is done within the implementation of the libgnunetpsyc library, and this API | ||
34 | * deliberately exposes as little as possible of the actual data stream format | ||
35 | * to the application! | ||
36 | * | ||
37 | * NOTE: | ||
38 | * - this API does not know about PSYC's "root" and "places"; | ||
39 | * there is no 'root' in GNUnet-PSYC as we're decentralized; | ||
40 | * 'places' and 'persons' are combined within the same | ||
41 | * abstraction, that of a "channel". Channels are identified | ||
42 | * and accessed in this API using a public/private key. | ||
43 | * Higher-level applications should use NAMES within GNS | ||
44 | * to obtain public keys, and the distinction between | ||
45 | * 'places' and 'persons' can then be made with the help | ||
46 | * of the naming system (and/or conventions). | ||
47 | * Channels are (as in PSYC) organized into a hierarchy; each | ||
48 | * channel master (the one with the private key) is then | ||
49 | * the operator of the multicast group (its Origin in | ||
50 | * the terminology of the multicast API). | ||
51 | * - The API supports passing large amounts of data using | ||
52 | * 'streaming' for the argument passed to a method. State | ||
53 | * and variables must fit into memory and cannot be streamed | ||
54 | * (thus, no passing of 4 GB of data in a variable; | ||
55 | * once we implement this, we might want to create a | ||
56 | * @c \#define for the maximum size of a variable). | ||
57 | * - PSYC defines standard variables, methods, etc. This | ||
58 | * library deliberately abstracts over all of these; a | ||
59 | * higher-level API should combine the naming system (GNS) | ||
60 | * and standard methods (_converse, _notice, _request, | ||
61 | * _warning, _error etc) and variables (_action, _color, | ||
62 | * _time, etc). However, this API does take over the | ||
63 | * routing variables, specifically '_context' (channel), | ||
64 | * and '_source'. We only kind-of support '_target', as | ||
65 | * the target is either everyone in the group or the | ||
66 | * origin, and never just a single member of the group; | ||
67 | * for such individual messages, an application needs to | ||
68 | * construct an 'inbox' channel where the master (only) | ||
69 | * receives messages (but never forwards; private responses | ||
70 | * would be transmitted by joining the senders 'inbox' | ||
71 | * channel -- or a inbox#bob subchannel). The | ||
72 | * goal for all of this is to keep the abstractions in this | ||
73 | * API minimal: interaction with multicast, try \& slice, | ||
74 | * state/variable/channel management. Higher-level | ||
75 | * operations belong elsewhere (so maybe this API should | ||
76 | * be called 'PSYC-low', whereas a higher-level API | ||
77 | * implementing defaults for standard methods and | ||
78 | * variables might be called 'PSYC-std' or 'PSYC-high'. | ||
79 | * | ||
80 | * In PSYC terminology this is simply called the "PSYC | ||
81 | * routing layer" and the abstractions, for instance in | ||
82 | * psyced, are quite similar. The higher one is called | ||
83 | * "PSYC entity layer." In the text rendering of the | ||
84 | * protocol the two are separated by an empty line. See | ||
85 | * http://about.psyc.eu/Spec:Packet and related. --lynX | ||
86 | * | ||
87 | * @{ | ||
88 | */ | ||
89 | |||
90 | #ifndef GNUNET_PSYC_SERVICE_H | ||
91 | #define GNUNET_PSYC_SERVICE_H | ||
92 | |||
93 | #ifdef __cplusplus | ||
94 | extern "C" | ||
95 | { | ||
96 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
97 | } | ||
98 | #endif | ||
99 | #endif | ||
100 | |||
101 | #include "gnunet_util_lib.h" | ||
102 | #include "gnunet_multicast_service.h" | ||
103 | //Mingw work around | ||
104 | #ifdef MINGW | ||
105 | # ifndef UINT64_MAX | ||
106 | # define UINT64_MAX 0xffffffffffffffffULL | ||
107 | # endif | ||
108 | #endif | ||
109 | |||
110 | /** | ||
111 | * Version number of GNUnet-PSYC API. | ||
112 | */ | ||
113 | #define GNUNET_PSYC_VERSION 0x00000000 | ||
114 | |||
115 | |||
116 | /** | ||
117 | * Policy flags for a channel. | ||
118 | */ | ||
119 | enum GNUNET_PSYC_ChannelFlags | ||
120 | { | ||
121 | /** | ||
122 | * Admission must be confirmed by the master. | ||
123 | */ | ||
124 | GNUNET_PSYC_CHANNEL_ADMISSION_CONTROL = 1 << 0, | ||
125 | |||
126 | /** | ||
127 | * Past messages are only available to slaves who were admitted at the time | ||
128 | * they were sent to the channel. | ||
129 | */ | ||
130 | GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY = 1 << 1 | ||
131 | }; | ||
132 | |||
133 | |||
134 | /** | ||
135 | * PSYC channel policies. | ||
136 | */ | ||
137 | enum GNUNET_PSYC_Policy | ||
138 | { | ||
139 | /** | ||
140 | * Anyone can join the channel, without announcing their presence; | ||
141 | * all messages are always public and can be distributed freely. | ||
142 | * Joins may be announced, but this is not required. | ||
143 | */ | ||
144 | GNUNET_PSYC_CHANNEL_ANONYMOUS = 0, | ||
145 | |||
146 | /** | ||
147 | * The master must approve membership to the channel, messages must only be | ||
148 | * distributed to current channel slaves. This includes the channel | ||
149 | * state as well as transient messages. | ||
150 | */ | ||
151 | GNUNET_PSYC_CHANNEL_PRIVATE | ||
152 | = GNUNET_PSYC_CHANNEL_ADMISSION_CONTROL | ||
153 | | GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY | ||
154 | |||
155 | #if IDEAS_FOR_FUTURE | ||
156 | /** | ||
157 | * Anyone can freely join the channel (no approval required); | ||
158 | * however, messages must only be distributed to current channel | ||
159 | * slaves, so the master must still acknowledge that the slave | ||
160 | * joined before transient messages are delivered. As approval is | ||
161 | * guaranteed, the presistent channel state can be synchronized freely | ||
162 | * immediately, prior to master confirmation. | ||
163 | */ | ||
164 | GNUNET_PSYC_CHANNEL_OPEN | ||
165 | = GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY, | ||
166 | |||
167 | /** | ||
168 | * The master must approve joins to the channel, but past messages can be | ||
169 | * freely distributed to slaves. | ||
170 | */ | ||
171 | GNUNET_PSYC_CHANNEL_CLOSED | ||
172 | = GNUNET_PSYC_CHANNEL_ADMISSION_CONTROL, | ||
173 | #endif | ||
174 | }; | ||
175 | |||
176 | |||
177 | enum GNUNET_PSYC_MessageFlags | ||
178 | { | ||
179 | /** | ||
180 | * Default / no flags. | ||
181 | */ | ||
182 | GNUNET_PSYC_MESSAGE_DEFAULT = 0, | ||
183 | |||
184 | /** | ||
185 | * Historic message, retrieved from PSYCstore. | ||
186 | */ | ||
187 | GNUNET_PSYC_MESSAGE_HISTORIC = 1 << 0, | ||
188 | |||
189 | /** | ||
190 | * Request from slave to master. | ||
191 | */ | ||
192 | GNUNET_PSYC_MESSAGE_REQUEST = 1 << 1, | ||
193 | |||
194 | /** | ||
195 | * Message can be delivered out of order. | ||
196 | */ | ||
197 | GNUNET_PSYC_MESSAGE_ORDER_ANY = 1 << 2 | ||
198 | }; | ||
199 | |||
200 | |||
201 | /** | ||
202 | * Values for the @a state_delta field of GNUNET_PSYC_MessageHeader. | ||
203 | */ | ||
204 | enum GNUNET_PSYC_StateDeltaValues | ||
205 | { | ||
206 | GNUNET_PSYC_STATE_RESET = 0, | ||
207 | |||
208 | GNUNET_PSYC_STATE_NOT_MODIFIED = UINT64_MAX | ||
209 | }; | ||
210 | |||
211 | |||
212 | GNUNET_NETWORK_STRUCT_BEGIN | ||
213 | |||
214 | /** | ||
215 | * A PSYC message. | ||
216 | * | ||
217 | * Used for single-fragment messages e.g. in a join request or response. | ||
218 | */ | ||
219 | struct GNUNET_PSYC_Message | ||
220 | { | ||
221 | /** | ||
222 | * Message header with size and type information. | ||
223 | */ | ||
224 | struct GNUNET_MessageHeader header; | ||
225 | |||
226 | /* Followed by concatenated PSYC message parts: | ||
227 | * messages with GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_* types | ||
228 | */ | ||
229 | }; | ||
230 | |||
231 | |||
232 | /** | ||
233 | * Header of a PSYC message. | ||
234 | * | ||
235 | * The PSYC service adds this when delivering the message to local clients, | ||
236 | * not present on the multicast layer. | ||
237 | */ | ||
238 | struct GNUNET_PSYC_MessageHeader | ||
239 | { | ||
240 | /** | ||
241 | * Generic message header with size and type information. | ||
242 | */ | ||
243 | struct GNUNET_MessageHeader header; | ||
244 | |||
245 | /** | ||
246 | * Flags for this message fragment. | ||
247 | * | ||
248 | * @see enum GNUNET_PSYC_MessageFlags | ||
249 | */ | ||
250 | uint32_t flags GNUNET_PACKED; | ||
251 | |||
252 | /** | ||
253 | * Number of the message this message part belongs to. | ||
254 | * Monotonically increasing from 1. | ||
255 | */ | ||
256 | uint64_t message_id GNUNET_PACKED; | ||
257 | |||
258 | /** | ||
259 | * Byte offset of this @e fragment of the @e message. | ||
260 | */ | ||
261 | uint64_t fragment_offset GNUNET_PACKED; | ||
262 | |||
263 | /** | ||
264 | * Sending slave's public key. | ||
265 | * Not set if the message is from the master. | ||
266 | */ | ||
267 | struct GNUNET_CRYPTO_EcdsaPublicKey slave_pub_key; | ||
268 | |||
269 | /* Followed by concatenated PSYC message parts: | ||
270 | * messages with GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_* types | ||
271 | */ | ||
272 | }; | ||
273 | |||
274 | |||
275 | /** | ||
276 | * The method of a message. | ||
277 | */ | ||
278 | struct GNUNET_PSYC_MessageMethod | ||
279 | { | ||
280 | /** | ||
281 | * Type: GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_METHOD | ||
282 | */ | ||
283 | struct GNUNET_MessageHeader header; | ||
284 | |||
285 | /** | ||
286 | * OR'ed GNUNET_PSYC_MasterTransmitFlags | ||
287 | */ | ||
288 | uint32_t flags GNUNET_PACKED; | ||
289 | |||
290 | /** | ||
291 | * Number of message IDs since the last message that contained state | ||
292 | * operations. @see enum GNUNET_PSYC_StateDeltaValues | ||
293 | */ | ||
294 | uint64_t state_delta GNUNET_PACKED; | ||
295 | |||
296 | /* Followed by NUL-terminated method name. */ | ||
297 | }; | ||
298 | |||
299 | |||
300 | /** | ||
301 | * A modifier of a message. | ||
302 | */ | ||
303 | struct GNUNET_PSYC_MessageModifier | ||
304 | { | ||
305 | /** | ||
306 | * Type: GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER | ||
307 | */ | ||
308 | struct GNUNET_MessageHeader header; | ||
309 | |||
310 | /** | ||
311 | * Size of value. | ||
312 | */ | ||
313 | uint32_t value_size GNUNET_PACKED; | ||
314 | |||
315 | /** | ||
316 | * Size of name, including NUL terminator. | ||
317 | */ | ||
318 | uint16_t name_size GNUNET_PACKED; | ||
319 | |||
320 | /** | ||
321 | * enum GNUNET_PSYC_Operator | ||
322 | */ | ||
323 | uint8_t oper; | ||
324 | |||
325 | /* Followed by NUL-terminated name, then the value. */ | ||
326 | }; | ||
327 | |||
328 | |||
329 | struct GNUNET_PSYC_CountersResultMessage | ||
330 | { | ||
331 | /** | ||
332 | * Type: GNUNET_MESSAGE_TYPE_PSYC_RESULT_COUNTERS | ||
333 | */ | ||
334 | struct GNUNET_MessageHeader header; | ||
335 | |||
336 | /** | ||
337 | * Status code for the operation. | ||
338 | */ | ||
339 | uint32_t result_code GNUNET_PACKED; | ||
340 | |||
341 | /** | ||
342 | * Last message ID sent to the channel. | ||
343 | */ | ||
344 | uint64_t max_message_id GNUNET_PACKED; | ||
345 | }; | ||
346 | |||
347 | |||
348 | /** | ||
349 | * Join request sent to a PSYC master. | ||
350 | */ | ||
351 | struct GNUNET_PSYC_JoinRequestMessage | ||
352 | { | ||
353 | /** | ||
354 | * Type: GNUNET_MESSAGE_TYPE_PSYC_MASTER_JOIN_REQUEST | ||
355 | */ | ||
356 | struct GNUNET_MessageHeader header; | ||
357 | /** | ||
358 | * Public key of the joining slave. | ||
359 | */ | ||
360 | struct GNUNET_CRYPTO_EcdsaPublicKey slave_pub_key; | ||
361 | |||
362 | /* Followed by struct GNUNET_MessageHeader join_request */ | ||
363 | }; | ||
364 | |||
365 | |||
366 | /** | ||
367 | * Join decision sent in reply to a join request. | ||
368 | */ | ||
369 | struct GNUNET_PSYC_JoinDecisionMessage | ||
370 | { | ||
371 | /** | ||
372 | * Type: GNUNET_MESSAGE_TYPE_PSYC_JOIN_DECISION | ||
373 | */ | ||
374 | struct GNUNET_MessageHeader header; | ||
375 | |||
376 | /** | ||
377 | * #GNUNET_YES if the slave was admitted. | ||
378 | */ | ||
379 | int32_t is_admitted; | ||
380 | |||
381 | /** | ||
382 | * Public key of the joining slave. | ||
383 | * Only set when the master is sending the decision, | ||
384 | * not set when a slave is receiving it. | ||
385 | */ | ||
386 | struct GNUNET_CRYPTO_EcdsaPublicKey slave_pub_key; | ||
387 | |||
388 | /* Followed by struct GNUNET_MessageHeader join_response */ | ||
389 | }; | ||
390 | |||
391 | |||
392 | enum GNUNET_PSYC_HistoryReplayFlags | ||
393 | { | ||
394 | /** | ||
395 | * Replay locally available messages. | ||
396 | */ | ||
397 | GNUNET_PSYC_HISTORY_REPLAY_LOCAL = 0, | ||
398 | |||
399 | /** | ||
400 | * Replay messages from remote peers if not found locally. | ||
401 | */ | ||
402 | GNUNET_PSYC_HISTORY_REPLAY_REMOTE = 1, | ||
403 | }; | ||
404 | |||
405 | |||
406 | struct GNUNET_PSYC_HistoryRequestMessage | ||
407 | { | ||
408 | /** | ||
409 | * Type: GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_HISTORY_REPLAY | ||
410 | */ | ||
411 | struct GNUNET_MessageHeader header; | ||
412 | |||
413 | /** | ||
414 | * @see enum GNUNET_PSYC_HistoryReplayFlags | ||
415 | */ | ||
416 | uint32_t flags GNUNET_PACKED; | ||
417 | |||
418 | /** | ||
419 | * ID for this operation. | ||
420 | */ | ||
421 | uint64_t op_id GNUNET_PACKED; | ||
422 | |||
423 | uint64_t start_message_id GNUNET_PACKED; | ||
424 | |||
425 | uint64_t end_message_id GNUNET_PACKED; | ||
426 | |||
427 | uint64_t message_limit GNUNET_PACKED; | ||
428 | |||
429 | /* Followed by NUL-terminated method name prefix. */ | ||
430 | }; | ||
431 | |||
432 | |||
433 | struct GNUNET_PSYC_StateRequestMessage | ||
434 | { | ||
435 | /** | ||
436 | * Types: | ||
437 | * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_GET | ||
438 | * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_GET_PREFIX | ||
439 | */ | ||
440 | struct GNUNET_MessageHeader header; | ||
441 | |||
442 | uint32_t reserved GNUNET_PACKED; | ||
443 | |||
444 | /** | ||
445 | * ID for this operation. | ||
446 | */ | ||
447 | uint64_t op_id GNUNET_PACKED; | ||
448 | |||
449 | /* Followed by NUL-terminated name. */ | ||
450 | }; | ||
451 | |||
452 | |||
453 | /**** service -> library ****/ | ||
454 | |||
455 | |||
456 | /** | ||
457 | * Answer from service to client about last operation. | ||
458 | */ | ||
459 | struct GNUNET_PSYC_OperationResultMessage | ||
460 | { | ||
461 | /** | ||
462 | * Types: | ||
463 | * - GNUNET_MESSAGE_TYPE_PSYC_RESULT_CODE | ||
464 | * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_RESULT | ||
465 | */ | ||
466 | struct GNUNET_MessageHeader header; | ||
467 | |||
468 | uint32_t reserved GNUNET_PACKED; | ||
469 | |||
470 | /** | ||
471 | * Operation ID. | ||
472 | */ | ||
473 | uint64_t op_id GNUNET_PACKED; | ||
474 | |||
475 | /** | ||
476 | * Status code for the operation. | ||
477 | */ | ||
478 | uint64_t result_code GNUNET_PACKED; | ||
479 | |||
480 | /* Followed by: | ||
481 | * - on error: NUL-terminated error message | ||
482 | * - on success: one of the following message types | ||
483 | * | ||
484 | * For a STATE_RESULT, one of: | ||
485 | * - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER | ||
486 | * - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MOD_CONT | ||
487 | * - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_END | ||
488 | */ | ||
489 | }; | ||
490 | |||
491 | GNUNET_NETWORK_STRUCT_END | ||
492 | |||
493 | |||
494 | #define GNUNET_PSYC_MODIFIER_MAX_PAYLOAD \ | ||
495 | GNUNET_MULTICAST_FRAGMENT_MAX_PAYLOAD \ | ||
496 | - sizeof (struct GNUNET_PSYC_MessageModifier) | ||
497 | |||
498 | #define GNUNET_PSYC_MOD_CONT_MAX_PAYLOAD \ | ||
499 | GNUNET_MULTICAST_FRAGMENT_MAX_PAYLOAD \ | ||
500 | - sizeof (struct GNUNET_MessageHeader) | ||
501 | |||
502 | #define GNUNET_PSYC_DATA_MAX_PAYLOAD \ | ||
503 | GNUNET_MULTICAST_FRAGMENT_MAX_PAYLOAD \ | ||
504 | - sizeof (struct GNUNET_MessageHeader) | ||
505 | |||
506 | |||
507 | /** | ||
508 | * PSYC message part processing states. | ||
509 | */ | ||
510 | enum GNUNET_PSYC_MessageState | ||
511 | { | ||
512 | GNUNET_PSYC_MESSAGE_STATE_START = 0, | ||
513 | GNUNET_PSYC_MESSAGE_STATE_HEADER = 1, | ||
514 | GNUNET_PSYC_MESSAGE_STATE_METHOD = 2, | ||
515 | GNUNET_PSYC_MESSAGE_STATE_MODIFIER = 3, | ||
516 | GNUNET_PSYC_MESSAGE_STATE_MOD_CONT = 4, | ||
517 | GNUNET_PSYC_MESSAGE_STATE_DATA = 5, | ||
518 | GNUNET_PSYC_MESSAGE_STATE_END = 6, | ||
519 | GNUNET_PSYC_MESSAGE_STATE_CANCEL = 7, | ||
520 | GNUNET_PSYC_MESSAGE_STATE_ERROR = 8, | ||
521 | }; | ||
522 | |||
523 | |||
524 | /** | ||
525 | * Handle that identifies a join request. | ||
526 | * | ||
527 | * Used to match calls to #GNUNET_PSYC_JoinCallback to the | ||
528 | * corresponding calls to GNUNET_PSYC_join_decision(). | ||
529 | */ | ||
530 | struct GNUNET_PSYC_JoinHandle; | ||
531 | |||
532 | |||
533 | /** | ||
534 | * Method called from PSYC upon receiving a message. | ||
535 | * | ||
536 | * @param cls Closure. | ||
537 | * @param message_id Sequence number of the message. | ||
538 | * @param flags OR'ed GNUNET_PSYC_MessageFlags | ||
539 | * @param msg Message part, one of the following types: | ||
540 | */ | ||
541 | typedef void | ||
542 | (*GNUNET_PSYC_MessageCallback) (void *cls, | ||
543 | const struct GNUNET_PSYC_MessageHeader *msg); | ||
544 | |||
545 | |||
546 | /** | ||
547 | * Method called from PSYC upon receiving part of a message. | ||
548 | * | ||
549 | * @param cls | ||
550 | * Closure. | ||
551 | * @param slave_pub_key | ||
552 | * Public key of the slave sending the message. | ||
553 | * Only set for channel master. | ||
554 | * @param message_id | ||
555 | * Sequence number of the message. | ||
556 | * @param flags | ||
557 | * OR'ed GNUNET_PSYC_MessageFlags | ||
558 | * @param fragment_offset | ||
559 | * Multicast message fragment offset. | ||
560 | * @param msg Message part, one of the following types: | ||
561 | * - #GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_HEADER | ||
562 | * - #GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_METHOD | ||
563 | * - #GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER | ||
564 | * - #GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MOD_CONT | ||
565 | * - #GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_DATA | ||
566 | * or NULL if an error occurred while receiving a message. | ||
567 | */ | ||
568 | typedef void | ||
569 | (*GNUNET_PSYC_MessagePartCallback) (void *cls, | ||
570 | const struct GNUNET_PSYC_MessageHeader *msg, | ||
571 | const struct GNUNET_MessageHeader *pmsg); | ||
572 | |||
573 | |||
574 | /** | ||
575 | * Method called from PSYC upon receiving a join request. | ||
576 | * | ||
577 | * @param cls | ||
578 | * Closure. | ||
579 | * @param slave_pub_key | ||
580 | * Public key of the slave requesting join. | ||
581 | * @param join_msg | ||
582 | * Join message sent along with the request. | ||
583 | * @param jh | ||
584 | * Join handle to use with GNUNET_PSYC_join_decision() | ||
585 | */ | ||
586 | typedef void | ||
587 | (*GNUNET_PSYC_JoinRequestCallback) (void *cls, | ||
588 | const struct GNUNET_PSYC_JoinRequestMessage *req, | ||
589 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_pub_key, | ||
590 | const struct GNUNET_PSYC_Message *join_msg, | ||
591 | struct GNUNET_PSYC_JoinHandle *jh); | ||
592 | |||
593 | |||
594 | /** | ||
595 | * Function to call with the decision made for a join request. | ||
596 | * | ||
597 | * Must be called once and only once in response to an invocation of the | ||
598 | * #GNUNET_PSYC_JoinCallback. | ||
599 | * | ||
600 | * @param jh Join request handle. | ||
601 | * @param is_admitted | ||
602 | * #GNUNET_YES if the join is approved, | ||
603 | * #GNUNET_NO if it is disapproved, | ||
604 | * #GNUNET_SYSERR if we cannot answer the request. | ||
605 | * @param relay_count Number of relays given. | ||
606 | * @param relays Array of suggested peers that might be useful relays to use | ||
607 | * when joining the multicast group (essentially a list of peers that | ||
608 | * are already part of the multicast group and might thus be willing | ||
609 | * to help with routing). If empty, only this local peer (which must | ||
610 | * be the multicast origin) is a good candidate for building the | ||
611 | * multicast tree. Note that it is unnecessary to specify our own | ||
612 | * peer identity in this array. | ||
613 | * @param join_resp Application-dependent join response message to send along | ||
614 | * with the decision. | ||
615 | * | ||
616 | * @return #GNUNET_OK on success, | ||
617 | * #GNUNET_SYSERR if @a join_resp is too large. | ||
618 | */ | ||
619 | int | ||
620 | GNUNET_PSYC_join_decision (struct GNUNET_PSYC_JoinHandle *jh, | ||
621 | int is_admitted, | ||
622 | uint32_t relay_count, | ||
623 | const struct GNUNET_PeerIdentity *relays, | ||
624 | const struct GNUNET_PSYC_Message *join_resp); | ||
625 | |||
626 | |||
627 | /** | ||
628 | * Handle for the master of a PSYC channel. | ||
629 | */ | ||
630 | struct GNUNET_PSYC_Master; | ||
631 | |||
632 | |||
633 | /** | ||
634 | * Function called once we are connected to the PSYC service | ||
635 | * and the channel master is started. | ||
636 | * | ||
637 | * Also called when we reconnected to the service | ||
638 | * after the connection closed unexpectedly. | ||
639 | * | ||
640 | * @param cls | ||
641 | * Closure. | ||
642 | * @param result | ||
643 | * #GNUNET_YES if there were already messages sent to the channel, | ||
644 | * #GNUNET_NO if the message history is empty, | ||
645 | * #GNUNET_SYSERR on error. | ||
646 | * @param max_message_id | ||
647 | * Last message ID sent to the channel. | ||
648 | */ | ||
649 | typedef void | ||
650 | (*GNUNET_PSYC_MasterStartCallback) (void *cls, int result, | ||
651 | uint64_t max_message_id); | ||
652 | |||
653 | |||
654 | /** | ||
655 | * Start a PSYC master channel. | ||
656 | * | ||
657 | * Will start a multicast group identified by the given ECC key. Messages | ||
658 | * received from group members will be given to the respective handler methods. | ||
659 | * If a new member wants to join a group, the "join" method handler will be | ||
660 | * invoked; the join handler must then generate a "join" message to approve the | ||
661 | * joining of the new member. The channel can also change group membership | ||
662 | * without explicit requests. Note that PSYC doesn't itself "understand" join | ||
663 | * or part messages, the respective methods must call other PSYC functions to | ||
664 | * inform PSYC about the meaning of the respective events. | ||
665 | * | ||
666 | * @param cfg Configuration to use (to connect to PSYC service). | ||
667 | * @param channel_key ECC key that will be used to sign messages for this | ||
668 | * PSYC session. The public key is used to identify the PSYC channel. | ||
669 | * Note that end-users will usually not use the private key directly, but | ||
670 | * rather look it up in GNS for places managed by other users, or select | ||
671 | * a file with the private key(s) when setting up their own channels | ||
672 | * FIXME: we'll likely want to use NOT the p521 curve here, but a cheaper | ||
673 | * one in the future. | ||
674 | * @param policy Channel policy specifying join and history restrictions. | ||
675 | * Used to automate join decisions. | ||
676 | * @param master_start_cb Function to invoke after the channel master started. | ||
677 | * @param join_request_cb Function to invoke when a slave wants to join. | ||
678 | * @param message_cb Function to invoke on message parts sent to the channel | ||
679 | * and received from slaves | ||
680 | * @param cls Closure for @a method and @a join_cb. | ||
681 | * | ||
682 | * @return Handle for the channel master, NULL on error. | ||
683 | */ | ||
684 | struct GNUNET_PSYC_Master * | ||
685 | GNUNET_PSYC_master_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
686 | const struct GNUNET_CRYPTO_EddsaPrivateKey *channel_key, | ||
687 | enum GNUNET_PSYC_Policy policy, | ||
688 | GNUNET_PSYC_MasterStartCallback master_start_cb, | ||
689 | GNUNET_PSYC_JoinRequestCallback join_request_cb, | ||
690 | GNUNET_PSYC_MessageCallback message_cb, | ||
691 | GNUNET_PSYC_MessagePartCallback message_part_cb, | ||
692 | void *cls); | ||
693 | |||
694 | |||
695 | /** | ||
696 | * Function called to provide data for a transmission via PSYC. | ||
697 | * | ||
698 | * Note that returning #GNUNET_YES or #GNUNET_SYSERR (but not #GNUNET_NO) | ||
699 | * invalidates the respective transmission handle. | ||
700 | * | ||
701 | * @param cls Closure. | ||
702 | * @param[in,out] data_size Initially set to the number of bytes available in | ||
703 | * @a data, should be set to the number of bytes written to data. | ||
704 | * @param[out] data Where to write the body of the message to give to the | ||
705 | * method. The function must copy at most @a data_size bytes to @a data. | ||
706 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) | ||
707 | * #GNUNET_NO on success, if more data is to be transmitted later. | ||
708 | * Should be used if @a data_size was not big enough to take all the | ||
709 | * data. If 0 is returned in @a data_size the transmission is paused, | ||
710 | * and can be resumed with GNUNET_PSYC_master_transmit_resume(). | ||
711 | * #GNUNET_YES if this completes the transmission (all data supplied) | ||
712 | */ | ||
713 | typedef int | ||
714 | (*GNUNET_PSYC_TransmitNotifyData) (void *cls, | ||
715 | uint16_t *data_size, | ||
716 | void *data); | ||
717 | |||
718 | /** | ||
719 | * Function called to provide a modifier for a transmission via PSYC. | ||
720 | * | ||
721 | * Note that returning #GNUNET_YES or #GNUNET_SYSERR (but not #GNUNET_NO) | ||
722 | * invalidates the respective transmission handle. | ||
723 | * | ||
724 | * @param cls Closure. | ||
725 | * @param[in,out] data_size Initially set to the number of bytes available in | ||
726 | * @a data, should be set to the number of bytes written to data. | ||
727 | * @param[out] data Where to write the modifier's name and value. | ||
728 | * The function must copy at most @a data_size bytes to @a data. | ||
729 | * When this callback is first called for a modifier, @a data should | ||
730 | * contain: "name\0value". If the whole value does not fit, subsequent | ||
731 | * calls to this function should write continuations of the value to | ||
732 | * @a data. | ||
733 | * @param[out] oper Where to write the operator of the modifier. | ||
734 | * Only needed during the first call to this callback at the beginning | ||
735 | * of the modifier. In case of subsequent calls asking for value | ||
736 | * continuations @a oper is set to #NULL. | ||
737 | * @param[out] full_value_size Where to write the full size of the value. | ||
738 | * Only needed during the first call to this callback at the beginning | ||
739 | * of the modifier. In case of subsequent calls asking for value | ||
740 | * continuations @a value_size is set to #NULL. | ||
741 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) | ||
742 | * #GNUNET_NO on success, if more data is to be transmitted later. | ||
743 | * Should be used if @a data_size was not big enough to take all the | ||
744 | * data for the modifier's value (the name must be always returned | ||
745 | * during the first call to this callback). | ||
746 | * If 0 is returned in @a data_size the transmission is paused, | ||
747 | * and can be resumed with GNUNET_PSYC_master_transmit_resume(). | ||
748 | * #GNUNET_YES if this completes the modifier (the whole value is supplied). | ||
749 | */ | ||
750 | typedef int | ||
751 | (*GNUNET_PSYC_TransmitNotifyModifier) (void *cls, | ||
752 | uint16_t *data_size, | ||
753 | void *data, | ||
754 | uint8_t *oper, | ||
755 | uint32_t *full_value_size); | ||
756 | |||
757 | /** | ||
758 | * Flags for transmitting messages to a channel by the master. | ||
759 | */ | ||
760 | enum GNUNET_PSYC_MasterTransmitFlags | ||
761 | { | ||
762 | GNUNET_PSYC_MASTER_TRANSMIT_NONE = 0, | ||
763 | |||
764 | /** | ||
765 | * Whether this message should reset the channel state, | ||
766 | * i.e. remove all previously stored state variables. | ||
767 | */ | ||
768 | |||
769 | GNUNET_PSYC_MASTER_TRANSMIT_STATE_RESET = 1 << 0, | ||
770 | |||
771 | /** | ||
772 | * Whether this message contains any state modifiers. | ||
773 | */ | ||
774 | GNUNET_PSYC_MASTER_TRANSMIT_STATE_MODIFY = 1 << 1, | ||
775 | |||
776 | /** | ||
777 | * Add PSYC header variable with the hash of the current channel state. | ||
778 | */ | ||
779 | GNUNET_PSYC_MASTER_TRANSMIT_STATE_HASH = 1 << 2, | ||
780 | |||
781 | /** | ||
782 | * Whether we need to increment the group generation counter after | ||
783 | * transmitting this message. | ||
784 | */ | ||
785 | GNUNET_PSYC_MASTER_TRANSMIT_INC_GROUP_GEN = 1 << 3 | ||
786 | }; | ||
787 | |||
788 | |||
789 | /** | ||
790 | * Handle for a pending PSYC transmission operation. | ||
791 | */ | ||
792 | struct GNUNET_PSYC_MasterTransmitHandle; | ||
793 | |||
794 | |||
795 | /** | ||
796 | * Send a message to call a method to all members in the PSYC channel. | ||
797 | * | ||
798 | * @param master Handle to the PSYC channel. | ||
799 | * @param method_name Which method should be invoked. | ||
800 | * @param notify_mod Function to call to obtain modifiers. | ||
801 | * @param notify_data Function to call to obtain fragments of the data. | ||
802 | * @param notify_cls Closure for @a notify_mod and @a notify_data. | ||
803 | * @param flags Flags for the message being transmitted. | ||
804 | * @return Transmission handle, NULL on error (i.e. more than one request queued). | ||
805 | */ | ||
806 | struct GNUNET_PSYC_MasterTransmitHandle * | ||
807 | GNUNET_PSYC_master_transmit (struct GNUNET_PSYC_Master *master, | ||
808 | const char *method_name, | ||
809 | GNUNET_PSYC_TransmitNotifyModifier notify_mod, | ||
810 | GNUNET_PSYC_TransmitNotifyData notify_data, | ||
811 | void *notify_cls, | ||
812 | enum GNUNET_PSYC_MasterTransmitFlags flags); | ||
813 | |||
814 | |||
815 | /** | ||
816 | * Resume transmission to the channel. | ||
817 | * | ||
818 | * @param th Handle of the request that is being resumed. | ||
819 | */ | ||
820 | void | ||
821 | GNUNET_PSYC_master_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); | ||
822 | |||
823 | |||
824 | /** | ||
825 | * Abort transmission request to channel. | ||
826 | * | ||
827 | * @param th Handle of the request that is being aborted. | ||
828 | */ | ||
829 | void | ||
830 | GNUNET_PSYC_master_transmit_cancel (struct GNUNET_PSYC_MasterTransmitHandle *th); | ||
831 | |||
832 | |||
833 | /** | ||
834 | * Relay a message | ||
835 | * | ||
836 | * @param master Handle to the PSYC channel. | ||
837 | * @param method_name Which method should be invoked. | ||
838 | * @param notify_mod Function to call to obtain modifiers. | ||
839 | * @param notify_data Function to call to obtain fragments of the data. | ||
840 | * @param notify_cls Closure for @a notify_mod and @a notify_data. | ||
841 | * @param flags Flags for the message being transmitted. | ||
842 | * @return Transmission handle, NULL on error (i.e. more than one request queued). | ||
843 | */ | ||
844 | struct GNUNET_PSYC_MasterTransmitHandle * | ||
845 | GNUNET_PSYC_master_relay (struct GNUNET_PSYC_Master *master, | ||
846 | uint64_t message_id); | ||
847 | |||
848 | |||
849 | /** | ||
850 | * Stop a PSYC master channel. | ||
851 | * | ||
852 | * @param master | ||
853 | * PSYC channel master to stop. | ||
854 | * @param keep_active | ||
855 | * Keep place active after last application disconnected. | ||
856 | * @param stop_cb | ||
857 | * Function called after the master stopped | ||
858 | * and disconnected from the psyc service. | ||
859 | * @param stop_cls | ||
860 | * Closure for @a part_cb. | ||
861 | */ | ||
862 | void | ||
863 | GNUNET_PSYC_master_stop (struct GNUNET_PSYC_Master *master, | ||
864 | int keep_active, | ||
865 | GNUNET_ContinuationCallback stop_cb, | ||
866 | void *stop_cls); | ||
867 | |||
868 | |||
869 | /** | ||
870 | * Handle for a PSYC channel slave. | ||
871 | */ | ||
872 | struct GNUNET_PSYC_Slave; | ||
873 | |||
874 | |||
875 | /** | ||
876 | * Function called after the slave connected to the PSYC service. | ||
877 | * | ||
878 | * Also called when reconnected to the service | ||
879 | * after the connection closed unexpectedly. | ||
880 | * | ||
881 | * @param cls | ||
882 | * Closure. | ||
883 | * @param result | ||
884 | * #GNUNET_YES if there were already messages sent to the channel, | ||
885 | * #GNUNET_NO if the message history is empty, | ||
886 | * #GNUNET_SYSERR on error. | ||
887 | * @param max_message_id | ||
888 | * Last message ID sent to the channel. | ||
889 | */ | ||
890 | typedef void | ||
891 | (*GNUNET_PSYC_SlaveConnectCallback) (void *cls, int result, | ||
892 | uint64_t max_message_id); | ||
893 | |||
894 | |||
895 | /** | ||
896 | * Method called to inform about the decision in response to a join request. | ||
897 | * | ||
898 | * If @a is_admitted is not #GNUNET_YES, then sending messages to the channel is | ||
899 | * not possible, but earlier history can be still queried. | ||
900 | * | ||
901 | * @param cls Closure. | ||
902 | * @param is_admitted #GNUNET_YES or #GNUNET_NO or #GNUNET_SYSERR | ||
903 | * @param join_msg Application-dependent join message from the origin. | ||
904 | */ | ||
905 | typedef void | ||
906 | (*GNUNET_PSYC_JoinDecisionCallback) (void *cls, | ||
907 | const struct GNUNET_PSYC_JoinDecisionMessage *dcsn, | ||
908 | int is_admitted, | ||
909 | const struct GNUNET_PSYC_Message *join_msg); | ||
910 | |||
911 | /** | ||
912 | * Flags for GNUNET_PSYC_slave_join() | ||
913 | */ | ||
914 | enum GNUNET_PSYC_SlaveJoinFlags | ||
915 | { | ||
916 | GNUNET_PSYC_SLAVE_JOIN_NONE = 0, | ||
917 | |||
918 | /** | ||
919 | * Local join for history access, no network connection is established. | ||
920 | */ | ||
921 | GNUNET_PSYC_SLAVE_JOIN_LOCAL = 1, | ||
922 | }; | ||
923 | |||
924 | |||
925 | /** | ||
926 | * Join a PSYC channel. | ||
927 | * | ||
928 | * The entity joining is always the local peer. The user must immediately use | ||
929 | * the GNUNET_PSYC_slave_transmit() functions to transmit a @e join_msg to the | ||
930 | * channel; if the join request succeeds, the channel state (and @e recent | ||
931 | * method calls) will be replayed to the joining member. There is no explicit | ||
932 | * notification on failure (as the channel may simply take days to approve, | ||
933 | * and disapproval is simply being ignored). | ||
934 | * | ||
935 | * @param cfg | ||
936 | * Configuration to use. | ||
937 | * @param channel_pub_key | ||
938 | * ECC public key that identifies the channel we wish to join. | ||
939 | * @param slave_pub_key | ||
940 | * ECC private-public key pair that identifies the slave, and | ||
941 | * used by multicast to sign the join request and subsequent unicast | ||
942 | * requests sent to the master. | ||
943 | * @param flags | ||
944 | * Join flags. | ||
945 | * @param origin | ||
946 | * Peer identity of the origin. | ||
947 | * @param relay_count | ||
948 | * Number of peers in the @a relays array. | ||
949 | * @param relays | ||
950 | * Peer identities of members of the multicast group, which serve | ||
951 | * as relays and used to join the group at. | ||
952 | * @param message_cb | ||
953 | * Function to invoke on message fragments received from the channel. | ||
954 | * @param message_part_cb | ||
955 | * Function to invoke on message parts received from the channel. | ||
956 | * @param slave_connect_cb | ||
957 | * Function invoked once we have connected to the PSYC service. | ||
958 | * @param join_decision_cb | ||
959 | * Function invoked once we have received a join decision. | ||
960 | * @param cls | ||
961 | * Closure for @a message_cb and @a slave_joined_cb. | ||
962 | * @param join_msg | ||
963 | * Join message. | ||
964 | * | ||
965 | * @return Handle for the slave, NULL on error. | ||
966 | */ | ||
967 | struct GNUNET_PSYC_Slave * | ||
968 | GNUNET_PSYC_slave_join (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
969 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_pub_key, | ||
970 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *slave_pub_key, | ||
971 | enum GNUNET_PSYC_SlaveJoinFlags flags, | ||
972 | const struct GNUNET_PeerIdentity *origin, | ||
973 | uint32_t relay_count, | ||
974 | const struct GNUNET_PeerIdentity *relays, | ||
975 | GNUNET_PSYC_MessageCallback message_cb, | ||
976 | GNUNET_PSYC_MessagePartCallback message_part_cb, | ||
977 | GNUNET_PSYC_SlaveConnectCallback slave_connect_cb, | ||
978 | GNUNET_PSYC_JoinDecisionCallback join_decision_cb, | ||
979 | void *cls, | ||
980 | const struct GNUNET_PSYC_Message *join_msg); | ||
981 | |||
982 | |||
983 | /** | ||
984 | * Part a PSYC channel. | ||
985 | * | ||
986 | * Will terminate the connection to the PSYC service. Polite clients should | ||
987 | * first explicitly send a part request (via GNUNET_PSYC_slave_transmit()). | ||
988 | * | ||
989 | * @param slave | ||
990 | * Slave handle. | ||
991 | * @param keep_active | ||
992 | * Keep place active after last application disconnected. | ||
993 | * @param part_cb | ||
994 | * Function called after the slave parted the channel | ||
995 | * and disconnected from the psyc service. | ||
996 | * @param part_cls | ||
997 | * Closure for @a part_cb. | ||
998 | */ | ||
999 | void | ||
1000 | GNUNET_PSYC_slave_part (struct GNUNET_PSYC_Slave *slave, | ||
1001 | int keep_active, | ||
1002 | GNUNET_ContinuationCallback part_cb, | ||
1003 | void *part_cls); | ||
1004 | |||
1005 | |||
1006 | /** | ||
1007 | * Flags for transmitting messages to the channel master by a slave. | ||
1008 | */ | ||
1009 | enum GNUNET_PSYC_SlaveTransmitFlags | ||
1010 | { | ||
1011 | GNUNET_PSYC_SLAVE_TRANSMIT_NONE = 0 | ||
1012 | }; | ||
1013 | |||
1014 | |||
1015 | /** | ||
1016 | * Handle for a pending PSYC transmission operation. | ||
1017 | */ | ||
1018 | struct GNUNET_PSYC_SlaveTransmitHandle; | ||
1019 | |||
1020 | |||
1021 | /** | ||
1022 | * Request a message to be sent to the channel master. | ||
1023 | * | ||
1024 | * @param slave Slave handle. | ||
1025 | * @param method_name Which (PSYC) method should be invoked (on host). | ||
1026 | * @param notify_mod Function to call to obtain modifiers. | ||
1027 | * @param notify_data Function to call to obtain fragments of the data. | ||
1028 | * @param notify_cls Closure for @a notify. | ||
1029 | * @param flags Flags for the message being transmitted. | ||
1030 | * @return Transmission handle, NULL on error (i.e. more than one request queued). | ||
1031 | */ | ||
1032 | struct GNUNET_PSYC_SlaveTransmitHandle * | ||
1033 | GNUNET_PSYC_slave_transmit (struct GNUNET_PSYC_Slave *slave, | ||
1034 | const char *method_name, | ||
1035 | GNUNET_PSYC_TransmitNotifyModifier notify_mod, | ||
1036 | GNUNET_PSYC_TransmitNotifyData notify_data, | ||
1037 | void *notify_cls, | ||
1038 | enum GNUNET_PSYC_SlaveTransmitFlags flags); | ||
1039 | |||
1040 | |||
1041 | /** | ||
1042 | * Resume transmission to the master. | ||
1043 | * | ||
1044 | * @param th Handle of the request that is being resumed. | ||
1045 | */ | ||
1046 | void | ||
1047 | GNUNET_PSYC_slave_transmit_resume (struct GNUNET_PSYC_SlaveTransmitHandle *th); | ||
1048 | |||
1049 | |||
1050 | /** | ||
1051 | * Abort transmission request to master. | ||
1052 | * | ||
1053 | * @param th Handle of the request that is being aborted. | ||
1054 | */ | ||
1055 | void | ||
1056 | GNUNET_PSYC_slave_transmit_cancel (struct GNUNET_PSYC_SlaveTransmitHandle *th); | ||
1057 | |||
1058 | |||
1059 | /** | ||
1060 | * Handle to access PSYC channel operations for both the master and slaves. | ||
1061 | */ | ||
1062 | struct GNUNET_PSYC_Channel; | ||
1063 | |||
1064 | |||
1065 | /** | ||
1066 | * Convert a channel @a master to a @e channel handle to access the @e channel | ||
1067 | * APIs. | ||
1068 | * | ||
1069 | * @param master Channel master handle. | ||
1070 | * @return Channel handle, valid for as long as @a master is valid. | ||
1071 | */ | ||
1072 | struct GNUNET_PSYC_Channel * | ||
1073 | GNUNET_PSYC_master_get_channel (struct GNUNET_PSYC_Master *master); | ||
1074 | |||
1075 | |||
1076 | /** | ||
1077 | * Convert @a slave to a @e channel handle to access the @e channel APIs. | ||
1078 | * | ||
1079 | * @param slave Slave handle. | ||
1080 | * @return Channel handle, valid for as long as @a slave is valid. | ||
1081 | */ | ||
1082 | struct GNUNET_PSYC_Channel * | ||
1083 | GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave); | ||
1084 | |||
1085 | |||
1086 | /** | ||
1087 | * Add a slave to the channel's membership list. | ||
1088 | * | ||
1089 | * Note that this will NOT generate any PSYC traffic, it will merely update the | ||
1090 | * local database to modify how we react to <em>membership test</em> queries. | ||
1091 | * The channel master still needs to explicitly transmit a @e join message to | ||
1092 | * notify other channel members and they then also must still call this function | ||
1093 | * in their respective methods handling the @e join message. This way, how @e | ||
1094 | * join and @e part operations are exactly implemented is still up to the | ||
1095 | * application; for example, there might be a @e part_all method to kick out | ||
1096 | * everyone. | ||
1097 | * | ||
1098 | * Note that channel slaves are explicitly trusted to execute such methods | ||
1099 | * correctly; not doing so correctly will result in either denying other slaves | ||
1100 | * access or offering access to channel data to non-members. | ||
1101 | * | ||
1102 | * @param channel | ||
1103 | * Channel handle. | ||
1104 | * @param slave_pub_key | ||
1105 | * Identity of channel slave to add. | ||
1106 | * @param announced_at | ||
1107 | * ID of the message that announced the membership change. | ||
1108 | * @param effective_since | ||
1109 | * Addition of slave is in effect since this message ID. | ||
1110 | * @param result_cb | ||
1111 | * Function to call with the result of the operation. | ||
1112 | * The @e result_code argument is #GNUNET_OK on success, or | ||
1113 | * #GNUNET_SYSERR on error. In case of an error, the @e data argument | ||
1114 | * can contain an optional error message. | ||
1115 | * @param cls | ||
1116 | * Closure for @a result_cb. | ||
1117 | */ | ||
1118 | void | ||
1119 | GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, | ||
1120 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_pub_key, | ||
1121 | uint64_t announced_at, | ||
1122 | uint64_t effective_since, | ||
1123 | GNUNET_ResultCallback result_cb, | ||
1124 | void *cls); | ||
1125 | |||
1126 | |||
1127 | /** | ||
1128 | * Remove a slave from the channel's membership list. | ||
1129 | * | ||
1130 | * Note that this will NOT generate any PSYC traffic, it will merely update the | ||
1131 | * local database to modify how we react to <em>membership test</em> queries. | ||
1132 | * The channel master still needs to explicitly transmit a @e part message to | ||
1133 | * notify other channel members and they then also must still call this function | ||
1134 | * in their respective methods handling the @e part message. This way, how | ||
1135 | * @e join and @e part operations are exactly implemented is still up to the | ||
1136 | * application; for example, there might be a @e part_all message to kick out | ||
1137 | * everyone. | ||
1138 | * | ||
1139 | * Note that channel members are explicitly trusted to perform these | ||
1140 | * operations correctly; not doing so correctly will result in either | ||
1141 | * denying members access or offering access to channel data to | ||
1142 | * non-members. | ||
1143 | * | ||
1144 | * @param channel | ||
1145 | * Channel handle. | ||
1146 | * @param slave_pub_key | ||
1147 | * Identity of channel slave to remove. | ||
1148 | * @param announced_at | ||
1149 | * ID of the message that announced the membership change. | ||
1150 | * @param result_cb | ||
1151 | * Function to call with the result of the operation. | ||
1152 | * The @e result_code argument is #GNUNET_OK on success, or | ||
1153 | * #GNUNET_SYSERR on error. In case of an error, the @e data argument | ||
1154 | * can contain an optional error message. | ||
1155 | * @param cls | ||
1156 | * Closure for @a result_cb. | ||
1157 | */ | ||
1158 | void | ||
1159 | GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel, | ||
1160 | const struct GNUNET_CRYPTO_EcdsaPublicKey | ||
1161 | *slave_pub_key, | ||
1162 | uint64_t announced_at, | ||
1163 | GNUNET_ResultCallback result_cb, | ||
1164 | void *cls); | ||
1165 | |||
1166 | |||
1167 | /** | ||
1168 | * History request handle. | ||
1169 | */ | ||
1170 | struct GNUNET_PSYC_HistoryRequest; | ||
1171 | |||
1172 | |||
1173 | /** | ||
1174 | * Request to replay a part of the message history of the channel. | ||
1175 | * | ||
1176 | * Historic messages (but NOT the state at the time) will be replayed (given to | ||
1177 | * the normal method handlers) if available and if access is permitted. | ||
1178 | * | ||
1179 | * @param channel | ||
1180 | * Which channel should be replayed? | ||
1181 | * @param start_message_id | ||
1182 | * Earliest interesting point in history. | ||
1183 | * @param end_message_id | ||
1184 | * Last (inclusive) interesting point in history. | ||
1185 | * @param method_prefix | ||
1186 | * Retrieve only messages with a matching method prefix. | ||
1187 | * @param flags | ||
1188 | * OR'ed enum GNUNET_PSYC_HistoryReplayFlags | ||
1189 | * @param result_cb | ||
1190 | * Function to call when the requested history has been fully replayed. | ||
1191 | * Once this function has been called, the client must not call | ||
1192 | * GNUNET_PSYC_channel_history_replay_cancel() anymore. | ||
1193 | * @param cls | ||
1194 | * Closure for the callbacks. | ||
1195 | * | ||
1196 | * @return Handle to cancel history replay operation. | ||
1197 | */ | ||
1198 | struct GNUNET_PSYC_HistoryRequest * | ||
1199 | GNUNET_PSYC_channel_history_replay (struct GNUNET_PSYC_Channel *channel, | ||
1200 | uint64_t start_message_id, | ||
1201 | uint64_t end_message_id, | ||
1202 | const char *method_prefix, | ||
1203 | uint32_t flags, | ||
1204 | GNUNET_PSYC_MessageCallback message_cb, | ||
1205 | GNUNET_PSYC_MessagePartCallback message_part_cb, | ||
1206 | GNUNET_ResultCallback result_cb, | ||
1207 | void *cls); | ||
1208 | |||
1209 | |||
1210 | /** | ||
1211 | * Request to replay the latest messages from the message history of the channel. | ||
1212 | * | ||
1213 | * Historic messages (but NOT the state at the time) will be replayed (given to | ||
1214 | * the normal method handlers) if available and if access is permitted. | ||
1215 | * | ||
1216 | * @param channel | ||
1217 | * Which channel should be replayed? | ||
1218 | * @param message_limit | ||
1219 | * Maximum number of messages to replay. | ||
1220 | * @param flags | ||
1221 | * OR'ed enum GNUNET_PSYC_HistoryReplayFlags | ||
1222 | * @param finish_cb | ||
1223 | * Function to call when the requested history has been fully replayed | ||
1224 | * (counting message IDs might not suffice, as some messages might be | ||
1225 | * secret and thus the listener would not know the story is finished | ||
1226 | * without being told explicitly)o once this function has been called, the | ||
1227 | * client must not call GNUNET_PSYC_channel_history_replay_cancel() anymore. | ||
1228 | * @param cls | ||
1229 | * Closure for the callbacks. | ||
1230 | * | ||
1231 | * @return Handle to cancel history replay operation. | ||
1232 | */ | ||
1233 | struct GNUNET_PSYC_HistoryRequest * | ||
1234 | GNUNET_PSYC_channel_history_replay_latest (struct GNUNET_PSYC_Channel *channel, | ||
1235 | uint64_t message_limit, | ||
1236 | const char *method_prefix, | ||
1237 | uint32_t flags, | ||
1238 | GNUNET_PSYC_MessageCallback message_cb, | ||
1239 | GNUNET_PSYC_MessagePartCallback message_part_cb, | ||
1240 | GNUNET_ResultCallback result_cb, | ||
1241 | void *cls); | ||
1242 | |||
1243 | |||
1244 | void | ||
1245 | GNUNET_PSYC_channel_history_replay_cancel (struct GNUNET_PSYC_Channel *channel, | ||
1246 | struct GNUNET_PSYC_HistoryRequest *hr); | ||
1247 | |||
1248 | |||
1249 | /** | ||
1250 | * Function called to inform a member about stored state values for a channel. | ||
1251 | * | ||
1252 | * If @a full_value_size > value_size then this function is called multiple | ||
1253 | * times until the whole value arrived. | ||
1254 | * | ||
1255 | * @param cls | ||
1256 | * Closure. | ||
1257 | * @param name | ||
1258 | * Name of the state variable. | ||
1259 | * NULL if there are no more state variables to be returned. | ||
1260 | * @param value | ||
1261 | * Value of the state variable. | ||
1262 | * @param value_size | ||
1263 | * Number of bytes in @a value. | ||
1264 | * @param full_value_size | ||
1265 | * Number of bytes in the full value, including continuations. | ||
1266 | * Only set for the first part of a variable, | ||
1267 | * in case of a continuation it is 0. | ||
1268 | */ | ||
1269 | typedef void | ||
1270 | (*GNUNET_PSYC_StateVarCallback) (void *cls, | ||
1271 | const struct GNUNET_MessageHeader *mod, | ||
1272 | const char *name, | ||
1273 | const void *value, | ||
1274 | uint32_t value_size, | ||
1275 | uint32_t full_value_size); | ||
1276 | |||
1277 | |||
1278 | /** | ||
1279 | * State request handle. | ||
1280 | */ | ||
1281 | struct GNUNET_PSYC_StateRequest; | ||
1282 | |||
1283 | |||
1284 | /** | ||
1285 | * Retrieve the best matching channel state variable. | ||
1286 | * | ||
1287 | * If the requested variable name is not present in the state, the nearest | ||
1288 | * less-specific name is matched; for example, requesting "_a_b" will match "_a" | ||
1289 | * if "_a_b" does not exist. | ||
1290 | * | ||
1291 | * @param channel | ||
1292 | * Channel handle. | ||
1293 | * @param full_name | ||
1294 | * Full name of the requested variable. | ||
1295 | * The actual variable returned might have a shorter name. | ||
1296 | * @param var_cb | ||
1297 | * Function called once when a matching state variable is found. | ||
1298 | * Not called if there's no matching state variable. | ||
1299 | * @param result_cb | ||
1300 | * Function called after the operation finished. | ||
1301 | * (i.e. all state variables have been returned via @a state_cb) | ||
1302 | * @param cls | ||
1303 | * Closure for the callbacks. | ||
1304 | */ | ||
1305 | struct GNUNET_PSYC_StateRequest * | ||
1306 | GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel, | ||
1307 | const char *full_name, | ||
1308 | GNUNET_PSYC_StateVarCallback var_cb, | ||
1309 | GNUNET_ResultCallback result_cb, | ||
1310 | void *cls); | ||
1311 | |||
1312 | |||
1313 | /** | ||
1314 | * Return all channel state variables whose name matches a given prefix. | ||
1315 | * | ||
1316 | * A name matches if it starts with the given @a name_prefix, thus requesting | ||
1317 | * the empty prefix ("") will match all values; requesting "_a_b" will also | ||
1318 | * return values stored under "_a_b_c". | ||
1319 | * | ||
1320 | * The @a state_cb is invoked on all matching state variables asynchronously, as | ||
1321 | * the state is stored in and retrieved from the PSYCstore, | ||
1322 | * | ||
1323 | * @param channel | ||
1324 | * Channel handle. | ||
1325 | * @param name_prefix | ||
1326 | * Prefix of the state variable name to match. | ||
1327 | * @param var_cb | ||
1328 | * Function called once when a matching state variable is found. | ||
1329 | * Not called if there's no matching state variable. | ||
1330 | * @param result_cb | ||
1331 | * Function called after the operation finished. | ||
1332 | * (i.e. all state variables have been returned via @a state_cb) | ||
1333 | * @param cls | ||
1334 | * Closure for the callbacks. | ||
1335 | */ | ||
1336 | struct GNUNET_PSYC_StateRequest * | ||
1337 | GNUNET_PSYC_channel_state_get_prefix (struct GNUNET_PSYC_Channel *channel, | ||
1338 | const char *name_prefix, | ||
1339 | GNUNET_PSYC_StateVarCallback var_cb, | ||
1340 | GNUNET_ResultCallback result_cb, | ||
1341 | void *cls); | ||
1342 | |||
1343 | /** | ||
1344 | * Cancel a state request operation. | ||
1345 | * | ||
1346 | * @param sr | ||
1347 | * Handle for the operation to cancel. | ||
1348 | */ | ||
1349 | void | ||
1350 | GNUNET_PSYC_channel_state_get_cancel (struct GNUNET_PSYC_StateRequest *sr); | ||
1351 | |||
1352 | |||
1353 | |||
1354 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
1355 | { | ||
1356 | #endif | ||
1357 | #ifdef __cplusplus | ||
1358 | } | ||
1359 | #endif | ||
1360 | |||
1361 | /* ifndef GNUNET_PSYC_SERVICE_H */ | ||
1362 | #endif | ||
1363 | |||
1364 | /** @} */ /* end of group */ | ||
diff --git a/src/include/gnunet_psyc_slicer.h b/src/include/gnunet_psyc_slicer.h new file mode 100644 index 0000000..87f66d7 --- /dev/null +++ b/src/include/gnunet_psyc_slicer.h | |||
@@ -0,0 +1,378 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2013 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * @author Christian Grothoff | ||
24 | * | ||
25 | * @file | ||
26 | * PSYC Slicer library | ||
27 | * | ||
28 | * @defgroup psyc-util-slicer PSYC Utilities library: Slicer | ||
29 | * Try-and-slice processing of PSYC method names and environment. | ||
30 | * @{ | ||
31 | */ | ||
32 | |||
33 | #ifndef GNUNET_PSYC_SLICER_H | ||
34 | #define GNUNET_PSYC_SLICER_H | ||
35 | |||
36 | |||
37 | #ifdef __cplusplus | ||
38 | extern "C" | ||
39 | { | ||
40 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
41 | } | ||
42 | #endif | ||
43 | #endif | ||
44 | |||
45 | #include "gnunet_util_lib.h" | ||
46 | |||
47 | |||
48 | /** | ||
49 | * Handle to an implementation of try-and-slice. | ||
50 | */ | ||
51 | struct GNUNET_PSYC_Slicer; | ||
52 | |||
53 | |||
54 | /** | ||
55 | * Function called upon receiving a message indicating a call to a @e method. | ||
56 | * | ||
57 | * This function is called one or more times for each message until all data | ||
58 | * fragments arrive from the network. | ||
59 | * | ||
60 | * @param cls | ||
61 | * Closure. | ||
62 | * @param msg | ||
63 | * Message part, as it arrived from the network. | ||
64 | * @param message_id | ||
65 | * Message counter, monotonically increasing from 1. | ||
66 | * @param flags | ||
67 | * OR'ed GNUNET_PSYC_MessageFlags | ||
68 | * @param fragment_offset | ||
69 | * Multicast message fragment offset. | ||
70 | * @param tmit_flags | ||
71 | * OR'ed GNUNET_PSYC_MasterTransmitFlags | ||
72 | * @param nym | ||
73 | * The sender of the message. | ||
74 | * Can be NULL if the message is not connected to a pseudonym. | ||
75 | * @param method_name | ||
76 | * Original method name from PSYC. | ||
77 | * May be more specific than the registered method name due to | ||
78 | * try-and-slice matching. | ||
79 | */ | ||
80 | typedef void | ||
81 | (*GNUNET_PSYC_MethodCallback) (void *cls, | ||
82 | const struct GNUNET_PSYC_MessageHeader *msg, | ||
83 | const struct GNUNET_PSYC_MessageMethod *meth, | ||
84 | uint64_t message_id, | ||
85 | const char *method_name); | ||
86 | |||
87 | |||
88 | /** | ||
89 | * Function called upon receiving a modifier of a message. | ||
90 | * | ||
91 | * @param cls | ||
92 | * Closure. | ||
93 | * @param message_id | ||
94 | * Message ID this data fragment belongs to. | ||
95 | * @param flags | ||
96 | * OR'ed GNUNET_PSYC_MessageFlags | ||
97 | * @param fragment_offset | ||
98 | * Multicast message fragment offset. | ||
99 | * @param msg | ||
100 | * Message part, as it arrived from the network. | ||
101 | * @param oper | ||
102 | * Operation to perform. | ||
103 | * 0 in case of a modifier continuation. | ||
104 | * @param name | ||
105 | * Name of the modifier. | ||
106 | * NULL in case of a modifier continuation. | ||
107 | * @param value | ||
108 | * Value of the modifier. | ||
109 | * @param value_size | ||
110 | * Size of @value. | ||
111 | */ | ||
112 | typedef void | ||
113 | (*GNUNET_PSYC_ModifierCallback) (void *cls, | ||
114 | const struct GNUNET_PSYC_MessageHeader *msg, | ||
115 | const struct GNUNET_MessageHeader *pmsg, | ||
116 | uint64_t message_id, | ||
117 | enum GNUNET_PSYC_Operator oper, | ||
118 | const char *name, | ||
119 | const void *value, | ||
120 | uint16_t value_size, | ||
121 | uint16_t full_value_size); | ||
122 | |||
123 | |||
124 | /** | ||
125 | * Function called upon receiving a data fragment of a message. | ||
126 | * | ||
127 | * @param cls | ||
128 | * Closure. | ||
129 | * @param msg | ||
130 | * Message part, as it arrived from the network. | ||
131 | * @param message_id | ||
132 | * Message ID this data fragment belongs to. | ||
133 | * @param flags | ||
134 | * OR'ed GNUNET_PSYC_MessageFlags | ||
135 | * @param fragment_offset | ||
136 | * Multicast message fragment offset. | ||
137 | * @param data | ||
138 | * Data stream given to the method. | ||
139 | * @param data_size | ||
140 | * Number of bytes in @a data. | ||
141 | * @param end | ||
142 | * End of message? | ||
143 | * #GNUNET_NO if there are further fragments, | ||
144 | * #GNUNET_YES if this is the last fragment, | ||
145 | * #GNUNET_SYSERR indicates the message was cancelled by the sender. | ||
146 | */ | ||
147 | typedef void | ||
148 | (*GNUNET_PSYC_DataCallback) (void *cls, | ||
149 | const struct GNUNET_PSYC_MessageHeader *msg, | ||
150 | const struct GNUNET_MessageHeader *pmsg, | ||
151 | uint64_t message_id, | ||
152 | const void *data, | ||
153 | uint16_t data_size); | ||
154 | |||
155 | |||
156 | /** | ||
157 | * End of message. | ||
158 | * | ||
159 | * @param cls | ||
160 | * Closure. | ||
161 | * @param msg | ||
162 | * Message part, as it arrived from the network. | ||
163 | * @param message_id | ||
164 | * Message ID this data fragment belongs to. | ||
165 | * @param flags | ||
166 | * OR'ed GNUNET_PSYC_MessageFlags | ||
167 | * @param fragment_offset | ||
168 | * Multicast message fragment offset. | ||
169 | * @param cancelled | ||
170 | * #GNUNET_YES if the message was cancelled, | ||
171 | * #GNUNET_NO if the message is complete. | ||
172 | */ | ||
173 | typedef void | ||
174 | (*GNUNET_PSYC_EndOfMessageCallback) (void *cls, | ||
175 | const struct GNUNET_PSYC_MessageHeader *msg, | ||
176 | const struct GNUNET_MessageHeader *pmsg, | ||
177 | uint64_t message_id, | ||
178 | uint8_t is_cancelled); | ||
179 | |||
180 | |||
181 | /** | ||
182 | * Create a try-and-slice instance. | ||
183 | * | ||
184 | * A slicer processes incoming messages and notifies callbacks about matching | ||
185 | * methods or modifiers encountered. | ||
186 | * | ||
187 | * @return A new try-and-slice construct. | ||
188 | */ | ||
189 | struct GNUNET_PSYC_Slicer * | ||
190 | GNUNET_PSYC_slicer_create (void); | ||
191 | |||
192 | |||
193 | /** | ||
194 | * Add a method to the try-and-slice instance. | ||
195 | * | ||
196 | * The callbacks are called for messages with a matching @a method_name prefix. | ||
197 | * | ||
198 | * @param slicer | ||
199 | * The try-and-slice instance to extend. | ||
200 | * @param method_name | ||
201 | * Name of the given method, use empty string to match all. | ||
202 | * @param method_cb | ||
203 | * Method handler invoked upon a matching message. | ||
204 | * @param modifier_cb | ||
205 | * Modifier handler, invoked after @a method_cb | ||
206 | * for each modifier in the message. | ||
207 | * @param data_cb | ||
208 | * Data handler, invoked after @a modifier_cb for each data fragment. | ||
209 | * @param eom_cb | ||
210 | * Invoked upon reaching the end of a matching message. | ||
211 | * @param cls | ||
212 | * Closure for the callbacks. | ||
213 | */ | ||
214 | void | ||
215 | GNUNET_PSYC_slicer_method_add (struct GNUNET_PSYC_Slicer *slicer, | ||
216 | const char *method_name, | ||
217 | GNUNET_PSYC_MessageCallback msg_cb, | ||
218 | GNUNET_PSYC_MethodCallback method_cb, | ||
219 | GNUNET_PSYC_ModifierCallback modifier_cb, | ||
220 | GNUNET_PSYC_DataCallback data_cb, | ||
221 | GNUNET_PSYC_EndOfMessageCallback eom_cb, | ||
222 | void *cls); | ||
223 | |||
224 | /** | ||
225 | * Remove a registered method from the try-and-slice instance. | ||
226 | * | ||
227 | * Removes one matching handler registered with the given | ||
228 | * @a method_name and callbacks. | ||
229 | * | ||
230 | * @param slicer | ||
231 | * The try-and-slice instance. | ||
232 | * @param method_name | ||
233 | * Name of the method to remove. | ||
234 | * @param method_cb | ||
235 | * Only remove matching method handler, or NULL. | ||
236 | * @param modifier_cb | ||
237 | * Only remove matching modifier handler, or NULL. | ||
238 | * @param data_cb | ||
239 | * Only remove matching data handler, or NULL. | ||
240 | * @param eom_cb | ||
241 | * Only remove matching End of Message handler, or NULL. | ||
242 | * | ||
243 | * @return #GNUNET_OK if a method handler was removed, | ||
244 | * #GNUNET_NO if no handler matched the given method name and callbacks. | ||
245 | */ | ||
246 | int | ||
247 | GNUNET_PSYC_slicer_method_remove (struct GNUNET_PSYC_Slicer *slicer, | ||
248 | const char *method_name, | ||
249 | GNUNET_PSYC_MessageCallback msg_cb, | ||
250 | GNUNET_PSYC_MethodCallback method_cb, | ||
251 | GNUNET_PSYC_ModifierCallback modifier_cb, | ||
252 | GNUNET_PSYC_DataCallback data_cb, | ||
253 | GNUNET_PSYC_EndOfMessageCallback eom_cb); | ||
254 | |||
255 | |||
256 | /** | ||
257 | * Watch a place for changed objects. | ||
258 | * | ||
259 | * @param slicer | ||
260 | * The try-and-slice instance. | ||
261 | * @param object_filter | ||
262 | * Object prefix to match. | ||
263 | * @param modifier_cb | ||
264 | * Function to call when encountering a state modifier. | ||
265 | * @param cls | ||
266 | * Closure for callback. | ||
267 | */ | ||
268 | void | ||
269 | GNUNET_PSYC_slicer_modifier_add (struct GNUNET_PSYC_Slicer *slicer, | ||
270 | const char *object_filter, | ||
271 | GNUNET_PSYC_ModifierCallback modifier_cb, | ||
272 | void *cls); | ||
273 | |||
274 | |||
275 | /** | ||
276 | * Remove a registered modifier from the try-and-slice instance. | ||
277 | * | ||
278 | * Removes one matching handler registered with the given | ||
279 | * @a object_filter and callback. | ||
280 | * | ||
281 | * @param slicer | ||
282 | * The try-and-slice instance. | ||
283 | * @param object_filter | ||
284 | * Object prefix to match. | ||
285 | * @param modifier_cb | ||
286 | * Function to call when encountering a state modifier changes. | ||
287 | */ | ||
288 | int | ||
289 | GNUNET_PSYC_slicer_modifier_remove (struct GNUNET_PSYC_Slicer *slicer, | ||
290 | const char *object_filter, | ||
291 | GNUNET_PSYC_ModifierCallback modifier_cb); | ||
292 | |||
293 | |||
294 | /** | ||
295 | * Process an incoming message and call matching handlers. | ||
296 | * | ||
297 | * @param slicer | ||
298 | * The slicer to use. | ||
299 | * @param msg | ||
300 | * The message as it arrived from the network. | ||
301 | */ | ||
302 | void | ||
303 | GNUNET_PSYC_slicer_message (struct GNUNET_PSYC_Slicer *slicer, | ||
304 | const struct GNUNET_PSYC_MessageHeader *msg); | ||
305 | |||
306 | |||
307 | /** | ||
308 | * Process an incoming message part and call matching handlers. | ||
309 | * | ||
310 | * @param slicer | ||
311 | * The slicer to use. | ||
312 | * @param message_id | ||
313 | * ID of the message. | ||
314 | * @param flags | ||
315 | * Flags for the message. | ||
316 | * @see enum GNUNET_PSYC_MessageFlags | ||
317 | * @param fragment offset | ||
318 | * Fragment offset of the message. | ||
319 | * @param msg | ||
320 | * The message part as it arrived from the network. | ||
321 | */ | ||
322 | void | ||
323 | GNUNET_PSYC_slicer_message_part (struct GNUNET_PSYC_Slicer *slicer, | ||
324 | const struct GNUNET_PSYC_MessageHeader *msg, | ||
325 | const struct GNUNET_MessageHeader *pmsg); | ||
326 | |||
327 | |||
328 | /** | ||
329 | * Remove all registered method handlers. | ||
330 | * | ||
331 | * @param slicer | ||
332 | * Slicer to clear. | ||
333 | */ | ||
334 | void | ||
335 | GNUNET_PSYC_slicer_method_clear (struct GNUNET_PSYC_Slicer *slicer); | ||
336 | |||
337 | |||
338 | /** | ||
339 | * Remove all registered modifier handlers. | ||
340 | * | ||
341 | * @param slicer | ||
342 | * Slicer to clear. | ||
343 | */ | ||
344 | void | ||
345 | GNUNET_PSYC_slicer_modifier_clear (struct GNUNET_PSYC_Slicer *slicer); | ||
346 | |||
347 | |||
348 | /** | ||
349 | * Remove all registered method & modifier handlers. | ||
350 | * | ||
351 | * @param slicer | ||
352 | * Slicer to clear. | ||
353 | */ | ||
354 | void | ||
355 | GNUNET_PSYC_slicer_clear (struct GNUNET_PSYC_Slicer *slicer); | ||
356 | |||
357 | |||
358 | /** | ||
359 | * Destroy a given try-and-slice instance. | ||
360 | * | ||
361 | * @param slicer | ||
362 | * Slicer to destroy | ||
363 | */ | ||
364 | void | ||
365 | GNUNET_PSYC_slicer_destroy (struct GNUNET_PSYC_Slicer *slicer); | ||
366 | |||
367 | |||
368 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
369 | { | ||
370 | #endif | ||
371 | #ifdef __cplusplus | ||
372 | } | ||
373 | #endif | ||
374 | |||
375 | /* ifndef GNUNET_PSYC_SLICER_H */ | ||
376 | #endif | ||
377 | |||
378 | /** @} */ /* end of group */ | ||
diff --git a/src/include/gnunet_psyc_util_lib.h b/src/include/gnunet_psyc_util_lib.h new file mode 100644 index 0000000..57eec65 --- /dev/null +++ b/src/include/gnunet_psyc_util_lib.h | |||
@@ -0,0 +1,53 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2012, 2013 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * | ||
24 | * @file | ||
25 | * PSYC utilities: messages, environment, slicer | ||
26 | */ | ||
27 | |||
28 | #ifndef GNUNET_PSYC_UTIL_LIB_H | ||
29 | #define GNUNET_PSYC_UTIL_LIB_H | ||
30 | |||
31 | #ifdef __cplusplus | ||
32 | extern "C" | ||
33 | { | ||
34 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
35 | } | ||
36 | #endif | ||
37 | #endif | ||
38 | |||
39 | |||
40 | #include "gnunet_psyc_env.h" | ||
41 | #include "gnunet_psyc_message.h" | ||
42 | #include "gnunet_psyc_slicer.h" | ||
43 | |||
44 | |||
45 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
46 | { | ||
47 | #endif | ||
48 | #ifdef __cplusplus | ||
49 | } | ||
50 | #endif | ||
51 | |||
52 | /* ifndef GNUNET_PSYC_UTIL_LIB_H */ | ||
53 | #endif | ||
diff --git a/src/include/gnunet_psycstore_plugin.h b/src/include/gnunet_psycstore_plugin.h new file mode 100644 index 0000000..fac549f --- /dev/null +++ b/src/include/gnunet_psycstore_plugin.h | |||
@@ -0,0 +1,383 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | Copyright (C) 2013 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * | ||
24 | * @file | ||
25 | * Plugin API for the PSYCstore database backend | ||
26 | * | ||
27 | * @defgroup psycstore-plugin PSYC Store plugin API | ||
28 | * Plugin API for the PSYC Store database backend | ||
29 | * @{ | ||
30 | */ | ||
31 | #ifndef GNUNET_PSYCSTORE_PLUGIN_H | ||
32 | #define GNUNET_PSYCSTORE_PLUGIN_H | ||
33 | |||
34 | #include "gnunet_util_lib.h" | ||
35 | #include "gnunet_psycstore_service.h" | ||
36 | |||
37 | #ifdef __cplusplus | ||
38 | extern "C" | ||
39 | { | ||
40 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
41 | } | ||
42 | #endif | ||
43 | #endif | ||
44 | |||
45 | |||
46 | /** | ||
47 | * Struct returned by the initialization function of the plugin. | ||
48 | */ | ||
49 | struct GNUNET_PSYCSTORE_PluginFunctions | ||
50 | { | ||
51 | |||
52 | /** | ||
53 | * Closure to pass to all plugin functions. | ||
54 | */ | ||
55 | void *cls; | ||
56 | |||
57 | /** | ||
58 | * Store join/leave events for a PSYC channel in order to be able to answer | ||
59 | * membership test queries later. | ||
60 | * | ||
61 | * @see GNUNET_PSYCSTORE_membership_store() | ||
62 | * | ||
63 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
64 | */ | ||
65 | int | ||
66 | (*membership_store) (void *cls, | ||
67 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
68 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | ||
69 | int did_join, | ||
70 | uint64_t announced_at, | ||
71 | uint64_t effective_since, | ||
72 | uint64_t group_generation); | ||
73 | |||
74 | /** | ||
75 | * Test if a member was admitted to the channel at the given message ID. | ||
76 | * | ||
77 | * @see GNUNET_PSYCSTORE_membership_test() | ||
78 | * | ||
79 | * @return #GNUNET_YES if the member was admitted, #GNUNET_NO if not, | ||
80 | * #GNUNET_SYSERR if there was en error. | ||
81 | */ | ||
82 | int | ||
83 | (*membership_test) (void *cls, | ||
84 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
85 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | ||
86 | uint64_t message_id); | ||
87 | |||
88 | /** | ||
89 | * Store a message fragment sent to a channel. | ||
90 | * | ||
91 | * @see GNUNET_PSYCSTORE_fragment_store() | ||
92 | * | ||
93 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
94 | */ | ||
95 | int | ||
96 | (*fragment_store) (void *cls, | ||
97 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
98 | const struct GNUNET_MULTICAST_MessageHeader *message, | ||
99 | uint32_t psycstore_flags); | ||
100 | |||
101 | /** | ||
102 | * Set additional flags for a given message. | ||
103 | * | ||
104 | * They are OR'd with any existing flags set. | ||
105 | * | ||
106 | * @param cls Closure. | ||
107 | * @param channel_key Public key of the channel. | ||
108 | * @param message_id ID of the message. | ||
109 | * @param psycstore_flags OR'd GNUNET_PSYCSTORE_MessageFlags. | ||
110 | * | ||
111 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
112 | */ | ||
113 | int | ||
114 | (*message_add_flags) (void *cls, | ||
115 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
116 | uint64_t message_id, | ||
117 | uint32_t psycstore_flags); | ||
118 | |||
119 | /** | ||
120 | * Retrieve a message fragment range by fragment ID. | ||
121 | * | ||
122 | * @see GNUNET_PSYCSTORE_fragment_get() | ||
123 | * | ||
124 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
125 | */ | ||
126 | int | ||
127 | (*fragment_get) (void *cls, | ||
128 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
129 | uint64_t first_fragment_id, | ||
130 | uint64_t last_fragment_id, | ||
131 | uint64_t *returned_fragments, | ||
132 | GNUNET_PSYCSTORE_FragmentCallback cb, | ||
133 | void *cb_cls); | ||
134 | |||
135 | /** | ||
136 | * Retrieve latest message fragments. | ||
137 | * | ||
138 | * @see GNUNET_PSYCSTORE_fragment_get() | ||
139 | * | ||
140 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
141 | */ | ||
142 | int | ||
143 | (*fragment_get_latest) (void *cls, | ||
144 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
145 | uint64_t fragment_limit, | ||
146 | uint64_t *returned_fragments, | ||
147 | GNUNET_PSYCSTORE_FragmentCallback cb, | ||
148 | void *cb_cls); | ||
149 | |||
150 | /** | ||
151 | * Retrieve all fragments of a message ID range. | ||
152 | * | ||
153 | * @see GNUNET_PSYCSTORE_message_get() | ||
154 | * | ||
155 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
156 | */ | ||
157 | int | ||
158 | (*message_get) (void *cls, | ||
159 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
160 | uint64_t first_fragment_id, | ||
161 | uint64_t last_fragment_id, | ||
162 | uint64_t fragment_limit, | ||
163 | uint64_t *returned_fragments, | ||
164 | GNUNET_PSYCSTORE_FragmentCallback cb, | ||
165 | void *cb_cls); | ||
166 | |||
167 | /** | ||
168 | * Retrieve all fragments of the latest messages. | ||
169 | * | ||
170 | * @see GNUNET_PSYCSTORE_message_get() | ||
171 | * | ||
172 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
173 | */ | ||
174 | int | ||
175 | (*message_get_latest) (void *cls, | ||
176 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
177 | uint64_t fragment_limit, | ||
178 | uint64_t *returned_fragments, | ||
179 | GNUNET_PSYCSTORE_FragmentCallback cb, | ||
180 | void *cb_cls); | ||
181 | |||
182 | /** | ||
183 | * Retrieve a fragment of message specified by its message ID and fragment | ||
184 | * offset. | ||
185 | * | ||
186 | * @see GNUNET_PSYCSTORE_message_get_fragment() | ||
187 | * | ||
188 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
189 | */ | ||
190 | int | ||
191 | (*message_get_fragment) (void *cls, | ||
192 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
193 | uint64_t message_id, | ||
194 | uint64_t fragment_offset, | ||
195 | GNUNET_PSYCSTORE_FragmentCallback cb, | ||
196 | void *cb_cls); | ||
197 | |||
198 | /** | ||
199 | * Retrieve the max. values of message counters for a channel. | ||
200 | * | ||
201 | * @see GNUNET_PSYCSTORE_counters_get() | ||
202 | * | ||
203 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
204 | */ | ||
205 | int | ||
206 | (*counters_message_get) (void *cls, | ||
207 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
208 | uint64_t *max_fragment_id, | ||
209 | uint64_t *max_message_id, | ||
210 | uint64_t *max_group_generation); | ||
211 | |||
212 | /** | ||
213 | * Retrieve the max. values of state counters for a channel. | ||
214 | * | ||
215 | * @see GNUNET_PSYCSTORE_counters_get() | ||
216 | * | ||
217 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
218 | */ | ||
219 | int | ||
220 | (*counters_state_get) (void *cls, | ||
221 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
222 | uint64_t *max_state_message_id); | ||
223 | |||
224 | |||
225 | /** | ||
226 | * Begin modifying current state. | ||
227 | * | ||
228 | * @see GNUNET_PSYCSTORE_state_modify() | ||
229 | * | ||
230 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
231 | */ | ||
232 | int | ||
233 | (*state_modify_begin) (void *cls, | ||
234 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
235 | uint64_t message_id, uint64_t state_delta); | ||
236 | |||
237 | /** | ||
238 | * Set the current value of a state variable. | ||
239 | * | ||
240 | * The state modification process is started with state_modify_begin(), | ||
241 | * which is followed by one or more calls to this function, | ||
242 | * and finished with state_modify_end(). | ||
243 | * | ||
244 | * @see GNUNET_PSYCSTORE_state_modify() | ||
245 | * | ||
246 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
247 | */ | ||
248 | int | ||
249 | (*state_modify_op) (void *cls, | ||
250 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
251 | enum GNUNET_PSYC_Operator op, | ||
252 | const char *name, const void *value, size_t value_size); | ||
253 | |||
254 | |||
255 | /** | ||
256 | * End modifying current state. | ||
257 | * | ||
258 | * @see GNUNET_PSYCSTORE_state_modify() | ||
259 | * | ||
260 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
261 | */ | ||
262 | int | ||
263 | (*state_modify_end) (void *cls, | ||
264 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
265 | uint64_t message_id); | ||
266 | |||
267 | |||
268 | /** | ||
269 | * Begin synchronizing state. | ||
270 | * | ||
271 | * @see GNUNET_PSYCSTORE_state_sync() | ||
272 | * | ||
273 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
274 | */ | ||
275 | int | ||
276 | (*state_sync_begin) (void *cls, | ||
277 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key); | ||
278 | |||
279 | /** | ||
280 | * Assign value of a state variable while synchronizing state. | ||
281 | * | ||
282 | * The state synchronization process is started with state_sync_begin(), | ||
283 | * which is followed by one or more calls to this function, | ||
284 | * and finished using state_sync_end(). | ||
285 | * | ||
286 | * @see GNUNET_PSYCSTORE_state_sync() | ||
287 | * | ||
288 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
289 | */ | ||
290 | int | ||
291 | (*state_sync_assign) (void *cls, | ||
292 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
293 | const char *name, const void *value, size_t value_size); | ||
294 | |||
295 | |||
296 | /** | ||
297 | * End synchronizing state. | ||
298 | * | ||
299 | * @see GNUNET_PSYCSTORE_state_sync() | ||
300 | * | ||
301 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
302 | */ | ||
303 | int | ||
304 | (*state_sync_end) (void *cls, | ||
305 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
306 | uint64_t max_state_message_id, | ||
307 | uint64_t state_hash_message_id); | ||
308 | |||
309 | |||
310 | /** | ||
311 | * Reset the state of a channel. | ||
312 | * | ||
313 | * Delete all state variables stored for the given channel. | ||
314 | * | ||
315 | * @see GNUNET_PSYCSTORE_state_reset() | ||
316 | * | ||
317 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
318 | */ | ||
319 | int | ||
320 | (*state_reset) (void *cls, | ||
321 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key); | ||
322 | |||
323 | /** | ||
324 | * Update signed state values from the current ones. | ||
325 | * | ||
326 | * Sets value_signed = value_current for each variable for the given channel. | ||
327 | */ | ||
328 | int | ||
329 | (*state_update_signed) (void *cls, | ||
330 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key); | ||
331 | |||
332 | |||
333 | /** | ||
334 | * Retrieve a state variable by name (exact match). | ||
335 | * | ||
336 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
337 | */ | ||
338 | int | ||
339 | (*state_get) (void *cls, | ||
340 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
341 | const char *name, | ||
342 | GNUNET_PSYCSTORE_StateCallback cb, | ||
343 | void *cb_cls); | ||
344 | |||
345 | /** | ||
346 | * Retrieve all state variables for a channel with the given prefix. | ||
347 | * | ||
348 | * @see GNUNET_PSYCSTORE_state_get_prefix() | ||
349 | * | ||
350 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
351 | */ | ||
352 | int | ||
353 | (*state_get_prefix) (void *cls, | ||
354 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
355 | const char *name, | ||
356 | GNUNET_PSYCSTORE_StateCallback cb, | ||
357 | void *cb_cls); | ||
358 | |||
359 | |||
360 | /** | ||
361 | * Retrieve all signed state variables for a channel. | ||
362 | * | ||
363 | * @return #GNUNET_OK on success, else #GNUNET_SYSERR | ||
364 | */ | ||
365 | int | ||
366 | (*state_get_signed) (void *cls, | ||
367 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
368 | GNUNET_PSYCSTORE_StateCallback cb, | ||
369 | void *cb_cls); | ||
370 | |||
371 | }; | ||
372 | |||
373 | |||
374 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
375 | { | ||
376 | #endif | ||
377 | #ifdef __cplusplus | ||
378 | } | ||
379 | #endif | ||
380 | |||
381 | #endif | ||
382 | |||
383 | /** @} */ /* end of group */ | ||
diff --git a/src/include/gnunet_psycstore_service.h b/src/include/gnunet_psycstore_service.h new file mode 100644 index 0000000..92516f4 --- /dev/null +++ b/src/include/gnunet_psycstore_service.h | |||
@@ -0,0 +1,701 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2013 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * @author Christian Grothoff | ||
24 | * | ||
25 | * @file | ||
26 | * PSYCstore service; implements persistent storage for the PSYC service | ||
27 | * | ||
28 | * @defgroup psycstore PSYC Store service | ||
29 | * Persistent storage for the PSYC service. | ||
30 | * @{ | ||
31 | */ | ||
32 | #ifndef GNUNET_PSYCSTORE_SERVICE_H | ||
33 | #define GNUNET_PSYCSTORE_SERVICE_H | ||
34 | |||
35 | #ifdef __cplusplus | ||
36 | extern "C" | ||
37 | { | ||
38 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
39 | } | ||
40 | #endif | ||
41 | #endif | ||
42 | |||
43 | #include "gnunet_util_lib.h" | ||
44 | #include "gnunet_psyc_util_lib.h" | ||
45 | #include "gnunet_multicast_service.h" | ||
46 | #include "gnunet_psyc_service.h" | ||
47 | |||
48 | /** | ||
49 | * Version number of GNUnet PSYCstore API. | ||
50 | */ | ||
51 | #define GNUNET_PSYCSTORE_VERSION 0x00000000 | ||
52 | |||
53 | /** | ||
54 | * Membership test failed. | ||
55 | */ | ||
56 | #define GNUNET_PSYCSTORE_MEMBERSHIP_TEST_FAILED -2 | ||
57 | |||
58 | /** | ||
59 | * Flags for stored messages. | ||
60 | */ | ||
61 | enum GNUNET_PSYCSTORE_MessageFlags | ||
62 | { | ||
63 | /** | ||
64 | * The message contains state modifiers. | ||
65 | */ | ||
66 | GNUNET_PSYCSTORE_MESSAGE_STATE = 1 << 0, | ||
67 | |||
68 | /** | ||
69 | * The state modifiers have been applied to the state store. | ||
70 | */ | ||
71 | GNUNET_PSYCSTORE_MESSAGE_STATE_APPLIED = 1 << 1, | ||
72 | |||
73 | /** | ||
74 | * The message contains a state hash. | ||
75 | */ | ||
76 | GNUNET_PSYCSTORE_MESSAGE_STATE_HASH = 1 << 2 | ||
77 | }; | ||
78 | |||
79 | |||
80 | /** | ||
81 | * Handle for a PSYCstore | ||
82 | */ | ||
83 | struct GNUNET_PSYCSTORE_Handle; | ||
84 | |||
85 | |||
86 | /** | ||
87 | * Connect to the PSYCstore service. | ||
88 | * | ||
89 | * @param cfg Configuration to use. | ||
90 | * | ||
91 | * @return Handle for the connecton. | ||
92 | */ | ||
93 | struct GNUNET_PSYCSTORE_Handle * | ||
94 | GNUNET_PSYCSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
95 | |||
96 | |||
97 | /** | ||
98 | * Disconnect from the PSYCstore service. | ||
99 | * | ||
100 | * @param h Handle for the connection. | ||
101 | */ | ||
102 | void | ||
103 | GNUNET_PSYCSTORE_disconnect (struct GNUNET_PSYCSTORE_Handle *h); | ||
104 | |||
105 | |||
106 | /** | ||
107 | * Handle for an operation on the PSYCSTORE (useful to cancel the operation). | ||
108 | */ | ||
109 | struct GNUNET_PSYCSTORE_OperationHandle; | ||
110 | |||
111 | |||
112 | /** | ||
113 | * Function called with the result of an asynchronous operation. | ||
114 | * | ||
115 | * @param cls | ||
116 | * Closure. | ||
117 | * @param result | ||
118 | * Result of the operation. | ||
119 | * @param err_msg | ||
120 | * Error message, or NULL if there's no error. | ||
121 | * @param err_msg_size | ||
122 | * Size of @a err_msg | ||
123 | */ | ||
124 | typedef void | ||
125 | (*GNUNET_PSYCSTORE_ResultCallback) (void *cls, | ||
126 | int64_t result, | ||
127 | const char *err_msg, | ||
128 | uint16_t err_msg_size); | ||
129 | |||
130 | |||
131 | /** | ||
132 | * Store join/leave events for a PSYC channel in order to be able to answer | ||
133 | * membership test queries later. | ||
134 | * | ||
135 | * @param h | ||
136 | * Handle for the PSYCstore. | ||
137 | * @param channel_key | ||
138 | * The channel where the event happened. | ||
139 | * @param slave_key | ||
140 | * Public key of joining/leaving slave. | ||
141 | * @param did_join | ||
142 | * #GNUNET_YES on join, #GNUNET_NO on part. | ||
143 | * @param announced_at | ||
144 | * ID of the message that announced the membership change. | ||
145 | * @param effective_since | ||
146 | * Message ID this membership change is in effect since. | ||
147 | * For joins it is <= announced_at, for parts it is always 0. | ||
148 | * @param group_generation | ||
149 | * In case of a part, the last group generation the slave has access to. | ||
150 | * It has relevance when a larger message have fragments with different | ||
151 | * group generations. | ||
152 | * @param result_cb | ||
153 | * Callback to call with the result of the storage operation. | ||
154 | * @param cls | ||
155 | * Closure for the callback. | ||
156 | * | ||
157 | * @return Operation handle that can be used to cancel the operation. | ||
158 | */ | ||
159 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
160 | GNUNET_PSYCSTORE_membership_store (struct GNUNET_PSYCSTORE_Handle *h, | ||
161 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
162 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | ||
163 | int did_join, | ||
164 | uint64_t announced_at, | ||
165 | uint64_t effective_since, | ||
166 | uint64_t group_generation, | ||
167 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
168 | void *cls); | ||
169 | |||
170 | |||
171 | /** | ||
172 | * Test if a member was admitted to the channel at the given message ID. | ||
173 | * | ||
174 | * This is useful when relaying and replaying messages to check if a particular | ||
175 | * slave has access to the message fragment with a given group generation. It | ||
176 | * is also used when handling join requests to determine whether the slave is | ||
177 | * currently admitted to the channel. | ||
178 | * | ||
179 | * @param h | ||
180 | * Handle for the PSYCstore. | ||
181 | * @param channel_key | ||
182 | * The channel we are interested in. | ||
183 | * @param slave_key | ||
184 | * Public key of slave whose membership to check. | ||
185 | * @param message_id | ||
186 | * Message ID for which to do the membership test. | ||
187 | * @param group_generation | ||
188 | * Group generation of the fragment of the message to test. | ||
189 | * It has relevance if the message consists of multiple fragments with | ||
190 | * different group generations. | ||
191 | * @param result_cb | ||
192 | * Callback to call with the test result. | ||
193 | * @param cls | ||
194 | * Closure for the callback. | ||
195 | * | ||
196 | * @return Operation handle that can be used to cancel the operation. | ||
197 | */ | ||
198 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
199 | GNUNET_PSYCSTORE_membership_test (struct GNUNET_PSYCSTORE_Handle *h, | ||
200 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
201 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | ||
202 | uint64_t message_id, | ||
203 | uint64_t group_generation, | ||
204 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
205 | void *cls); | ||
206 | |||
207 | |||
208 | /** | ||
209 | * Store a message fragment sent to a channel. | ||
210 | * | ||
211 | * @param h Handle for the PSYCstore. | ||
212 | * @param channel_key The channel the message belongs to. | ||
213 | * @param msg Message to store. | ||
214 | * @param psycstore_flags Flags indicating whether the PSYC message contains | ||
215 | * state modifiers. | ||
216 | * @param result_cb Callback to call with the result of the operation. | ||
217 | * @param cls Closure for the callback. | ||
218 | * | ||
219 | * @return Handle that can be used to cancel the operation. | ||
220 | */ | ||
221 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
222 | GNUNET_PSYCSTORE_fragment_store (struct GNUNET_PSYCSTORE_Handle *h, | ||
223 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
224 | const struct GNUNET_MULTICAST_MessageHeader *msg, | ||
225 | enum GNUNET_PSYCSTORE_MessageFlags psycstore_flags, | ||
226 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
227 | void *cls); | ||
228 | |||
229 | |||
230 | /** | ||
231 | * Function called with one message fragment, as the result of a | ||
232 | * GNUNET_PSYCSTORE_fragment_get() or GNUNET_PSYCSTORE_message_get() call. | ||
233 | * | ||
234 | * @param cls Closure. | ||
235 | * @param message The retrieved message fragment. A NULL value indicates that | ||
236 | * there are no more results to be returned. | ||
237 | * @param psycstore_flags Flags stored with the message. | ||
238 | * | ||
239 | * @return #GNUNET_NO to stop calling this callback with further fragments, | ||
240 | * #GNUNET_YES to continue. | ||
241 | */ | ||
242 | typedef int | ||
243 | (*GNUNET_PSYCSTORE_FragmentCallback) (void *cls, | ||
244 | struct GNUNET_MULTICAST_MessageHeader *message, | ||
245 | enum GNUNET_PSYCSTORE_MessageFlags psycstore_flags); | ||
246 | |||
247 | |||
248 | /** | ||
249 | * Retrieve message fragments by fragment ID range. | ||
250 | * | ||
251 | * @param h | ||
252 | * Handle for the PSYCstore. | ||
253 | * @param channel_key | ||
254 | * The channel we are interested in. | ||
255 | * @param slave_key | ||
256 | * The slave requesting the fragment. If not NULL, a membership test is | ||
257 | * performed first and the fragment is only returned if the slave has | ||
258 | * access to it. | ||
259 | * @param first_fragment_id | ||
260 | * First fragment ID to retrieve. | ||
261 | * Use 0 to get the latest message fragment. | ||
262 | * @param last_fragment_id | ||
263 | * Last consecutive fragment ID to retrieve. | ||
264 | * Use 0 to get the latest message fragment. | ||
265 | * @param fragment_cb | ||
266 | * Callback to call with the retrieved fragments. | ||
267 | * @param result_cb | ||
268 | * Callback to call with the result of the operation. | ||
269 | * @param cls | ||
270 | * Closure for the callbacks. | ||
271 | * | ||
272 | * @return Handle that can be used to cancel the operation. | ||
273 | */ | ||
274 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
275 | GNUNET_PSYCSTORE_fragment_get (struct GNUNET_PSYCSTORE_Handle *h, | ||
276 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
277 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | ||
278 | uint64_t first_message_id, | ||
279 | uint64_t last_message_id, | ||
280 | GNUNET_PSYCSTORE_FragmentCallback fragment_cb, | ||
281 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
282 | void *cls); | ||
283 | |||
284 | |||
285 | /** | ||
286 | * Retrieve latest message fragments. | ||
287 | * | ||
288 | * @param h | ||
289 | * Handle for the PSYCstore. | ||
290 | * @param channel_key | ||
291 | * The channel we are interested in. | ||
292 | * @param slave_key | ||
293 | * The slave requesting the fragment. If not NULL, a membership test is | ||
294 | * performed first and the fragment is only returned if the slave has | ||
295 | * access to it. | ||
296 | * @param first_fragment_id | ||
297 | * First fragment ID to retrieve. | ||
298 | * Use 0 to get the latest message fragment. | ||
299 | * @param last_fragment_id | ||
300 | * Last consecutive fragment ID to retrieve. | ||
301 | * Use 0 to get the latest message fragment. | ||
302 | * @param fragment_limit | ||
303 | * Maximum number of fragments to retrieve. | ||
304 | * @param fragment_cb | ||
305 | * Callback to call with the retrieved fragments. | ||
306 | * @param result_cb | ||
307 | * Callback to call with the result of the operation. | ||
308 | * @param cls | ||
309 | * Closure for the callbacks. | ||
310 | * | ||
311 | * @return Handle that can be used to cancel the operation. | ||
312 | */ | ||
313 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
314 | GNUNET_PSYCSTORE_fragment_get_latest (struct GNUNET_PSYCSTORE_Handle *h, | ||
315 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
316 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | ||
317 | uint64_t fragment_limit, | ||
318 | GNUNET_PSYCSTORE_FragmentCallback fragment_cb, | ||
319 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
320 | void *cls); | ||
321 | |||
322 | |||
323 | /** | ||
324 | * Retrieve all fragments of messages in a message ID range. | ||
325 | * | ||
326 | * @param h | ||
327 | * Handle for the PSYCstore. | ||
328 | * @param channel_key | ||
329 | * The channel we are interested in. | ||
330 | * @param slave_key | ||
331 | * The slave requesting the message. | ||
332 | * If not NULL, a membership test is performed first | ||
333 | * and the message is only returned if the slave has access to it. | ||
334 | * @param first_message_id | ||
335 | * First message ID to retrieve. | ||
336 | * @param last_message_id | ||
337 | * Last consecutive message ID to retrieve. | ||
338 | * @param fragment_limit | ||
339 | * Maximum number of fragments to retrieve. | ||
340 | * @param method_prefix | ||
341 | * Retrieve only messages with a matching method prefix. | ||
342 | * @param fragment_cb | ||
343 | * Callback to call with the retrieved fragments. | ||
344 | * @param result_cb | ||
345 | * Callback to call with the result of the operation. | ||
346 | * @param cls | ||
347 | * Closure for the callbacks. | ||
348 | * | ||
349 | * @return Handle that can be used to cancel the operation. | ||
350 | */ | ||
351 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
352 | GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h, | ||
353 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
354 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | ||
355 | uint64_t first_message_id, | ||
356 | uint64_t last_message_id, | ||
357 | uint64_t fragment_limit, | ||
358 | const char *method_prefix, | ||
359 | GNUNET_PSYCSTORE_FragmentCallback fragment_cb, | ||
360 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
361 | void *cls); | ||
362 | |||
363 | |||
364 | /** | ||
365 | * Retrieve all fragments of the latest messages. | ||
366 | * | ||
367 | * @param h | ||
368 | * Handle for the PSYCstore. | ||
369 | * @param channel_key | ||
370 | * The channel we are interested in. | ||
371 | * @param slave_key | ||
372 | * The slave requesting the message. | ||
373 | * If not NULL, a membership test is performed first | ||
374 | * and the message is only returned if the slave has access to it. | ||
375 | * @param message_limit | ||
376 | * Maximum number of messages to retrieve. | ||
377 | * @param method_prefix | ||
378 | * Retrieve only messages with a matching method prefix. | ||
379 | * @param fragment_cb | ||
380 | * Callback to call with the retrieved fragments. | ||
381 | * @param result_cb | ||
382 | * Callback to call with the result of the operation. | ||
383 | * @param cls | ||
384 | * Closure for the callbacks. | ||
385 | * | ||
386 | * @return Handle that can be used to cancel the operation. | ||
387 | */ | ||
388 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
389 | GNUNET_PSYCSTORE_message_get_latest (struct GNUNET_PSYCSTORE_Handle *h, | ||
390 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
391 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | ||
392 | uint64_t message_limit, | ||
393 | const char *method_prefix, | ||
394 | GNUNET_PSYCSTORE_FragmentCallback fragment_cb, | ||
395 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
396 | void *cls); | ||
397 | |||
398 | |||
399 | /** | ||
400 | * Retrieve a fragment of message specified by its message ID and fragment | ||
401 | * offset. | ||
402 | * | ||
403 | * @param h | ||
404 | * Handle for the PSYCstore. | ||
405 | * @param channel_key | ||
406 | * The channel we are interested in. | ||
407 | * @param slave_key | ||
408 | * The slave requesting the message fragment. If not NULL, a membership | ||
409 | * test is performed first and the message fragment is only returned | ||
410 | * if the slave has access to it. | ||
411 | * @param message_id | ||
412 | * Message ID to retrieve. Use 0 to get the latest message. | ||
413 | * @param fragment_offset | ||
414 | * Offset of the fragment to retrieve. | ||
415 | * @param fragment_cb | ||
416 | * Callback to call with the retrieved fragments. | ||
417 | * @param result_cb | ||
418 | * Callback to call with the result of the operation. | ||
419 | * @param cls | ||
420 | * Closure for the callbacks. | ||
421 | * | ||
422 | * @return Handle that can be used to cancel the operation. | ||
423 | */ | ||
424 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
425 | GNUNET_PSYCSTORE_message_get_fragment (struct GNUNET_PSYCSTORE_Handle *h, | ||
426 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
427 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | ||
428 | uint64_t message_id, | ||
429 | uint64_t fragment_offset, | ||
430 | GNUNET_PSYCSTORE_FragmentCallback fragment_cb, | ||
431 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
432 | void *cls); | ||
433 | |||
434 | |||
435 | /** | ||
436 | * Callback used to return the latest value of counters for the channel master. | ||
437 | * | ||
438 | * @see GNUNET_PSYCSTORE_counters_get() | ||
439 | * | ||
440 | * @param cls Closure. | ||
441 | * @param result_code | ||
442 | * Status code for the operation: | ||
443 | * #GNUNET_OK: success, counter values are returned. | ||
444 | * #GNUNET_NO: no message has been sent to the channel yet. | ||
445 | * #GNUNET_SYSERR: an error occurred. | ||
446 | * @param max_fragment_id | ||
447 | * Latest message fragment ID, used by multicast. | ||
448 | * @param max_message_id | ||
449 | * Latest message ID, used by PSYC. | ||
450 | * @param max_group_generation | ||
451 | * Latest group generation, used by PSYC. | ||
452 | * @param max_state_message_id | ||
453 | * Latest message ID containing state modifiers that | ||
454 | * was applied to the state store. Used for the state sync process. | ||
455 | */ | ||
456 | typedef void | ||
457 | (*GNUNET_PSYCSTORE_CountersCallback) (void *cls, | ||
458 | int result_code, | ||
459 | uint64_t max_fragment_id, | ||
460 | uint64_t max_message_id, | ||
461 | uint64_t max_group_generation, | ||
462 | uint64_t max_state_message_id); | ||
463 | |||
464 | |||
465 | /** | ||
466 | * Retrieve latest values of counters for a channel. | ||
467 | * | ||
468 | * The current value of counters are needed | ||
469 | * - when a channel master is restarted, so that it can continue incrementing | ||
470 | * the counters from their last value. | ||
471 | * - when a channel slave rejoins and starts the state synchronization process. | ||
472 | * | ||
473 | * @param h | ||
474 | * Handle for the PSYCstore. | ||
475 | * @param channel_key | ||
476 | * Public key that identifies the channel. | ||
477 | * @param counters_cb | ||
478 | * Callback to call with the result. | ||
479 | * @param cls | ||
480 | * Closure for the @a ccb callback. | ||
481 | * | ||
482 | * @return Handle that can be used to cancel the operation. | ||
483 | */ | ||
484 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
485 | GNUNET_PSYCSTORE_counters_get (struct GNUNET_PSYCSTORE_Handle *h, | ||
486 | struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
487 | GNUNET_PSYCSTORE_CountersCallback counters_cb, | ||
488 | void *cls); | ||
489 | |||
490 | |||
491 | /** | ||
492 | * Apply modifiers of a message to the current channel state. | ||
493 | * | ||
494 | * An error is returned if there are missing messages containing state | ||
495 | * operations before the current one. | ||
496 | * | ||
497 | * @param h | ||
498 | * Handle for the PSYCstore. | ||
499 | * @param channel_key | ||
500 | * The channel we are interested in. | ||
501 | * @param message_id | ||
502 | * ID of the message that contains the @a modifiers. | ||
503 | * @param state_delta | ||
504 | * Value of the @e state_delta PSYC header variable of the message. | ||
505 | * @param result_cb | ||
506 | * Callback to call with the result of the operation. | ||
507 | * @param cls | ||
508 | * Closure for the @a result_cb callback. | ||
509 | * | ||
510 | * @return Handle that can be used to cancel the operation. | ||
511 | */ | ||
512 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
513 | GNUNET_PSYCSTORE_state_modify (struct GNUNET_PSYCSTORE_Handle *h, | ||
514 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
515 | uint64_t message_id, | ||
516 | uint64_t state_delta, | ||
517 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
518 | void *cls); | ||
519 | |||
520 | |||
521 | /** | ||
522 | * Store synchronized state. | ||
523 | * | ||
524 | * @param h | ||
525 | * Handle for the PSYCstore. | ||
526 | * @param channel_key | ||
527 | * The channel we are interested in. | ||
528 | * @param max_state_message_id | ||
529 | * ID of the last stateful message before @a state_hash_message_id. | ||
530 | * @param state_hash_message_id | ||
531 | * ID of the message that contains the state_hash PSYC header variable. | ||
532 | * @param modifier_count | ||
533 | * Number of elements in the @a modifiers array. | ||
534 | * @param modifiers | ||
535 | * Full state to store. | ||
536 | * @param result_cb | ||
537 | * Callback to call with the result of the operation. | ||
538 | * @param cls | ||
539 | * Closure for the callback. | ||
540 | * | ||
541 | * @return Handle that can be used to cancel the operation. | ||
542 | */ | ||
543 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
544 | GNUNET_PSYCSTORE_state_sync (struct GNUNET_PSYCSTORE_Handle *h, | ||
545 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
546 | uint64_t max_state_message_id, | ||
547 | uint64_t state_hash_message_id, | ||
548 | size_t modifier_count, | ||
549 | const struct GNUNET_PSYC_Modifier *modifiers, | ||
550 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
551 | void *cls); | ||
552 | |||
553 | |||
554 | |||
555 | /** | ||
556 | * Reset the state of a channel. | ||
557 | * | ||
558 | * Delete all state variables stored for the given channel. | ||
559 | * | ||
560 | * @param h | ||
561 | * Handle for the PSYCstore. | ||
562 | * @param channel_key | ||
563 | * The channel we are interested in. | ||
564 | * @param result_cb | ||
565 | * Callback to call with the result of the operation. | ||
566 | * @param cls | ||
567 | * Closure for the callback. | ||
568 | * | ||
569 | * @return Handle that can be used to cancel the operation. | ||
570 | */ | ||
571 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
572 | GNUNET_PSYCSTORE_state_reset (struct GNUNET_PSYCSTORE_Handle *h, | ||
573 | const struct GNUNET_CRYPTO_EddsaPublicKey | ||
574 | *channel_key, | ||
575 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
576 | void *cls); | ||
577 | |||
578 | |||
579 | /** | ||
580 | * Update signed values of state variables in the state store. | ||
581 | * | ||
582 | * @param h | ||
583 | * Handle for the PSYCstore. | ||
584 | * @param channel_key | ||
585 | * The channel we are interested in. | ||
586 | * @param message_id | ||
587 | * Message ID that contained the state @a hash. | ||
588 | * @param hash | ||
589 | * Hash of the serialized full state. | ||
590 | * @param result_cb | ||
591 | * Callback to call with the result of the operation. | ||
592 | * @param cls | ||
593 | * Closure for the callback. | ||
594 | * | ||
595 | */ | ||
596 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
597 | GNUNET_PSYCSTORE_state_hash_update (struct GNUNET_PSYCSTORE_Handle *h, | ||
598 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
599 | uint64_t message_id, | ||
600 | const struct GNUNET_HashCode *hash, | ||
601 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
602 | void *cls); | ||
603 | |||
604 | |||
605 | /** | ||
606 | * Function called with the value of a state variable. | ||
607 | * | ||
608 | * @param cls | ||
609 | * Closure. | ||
610 | * @param name | ||
611 | * Name of the state variable. A NULL value indicates that there are no more | ||
612 | * state variables to be returned. | ||
613 | * @param value | ||
614 | * Value of the state variable. | ||
615 | * @param value_size | ||
616 | * Number of bytes in @a value. | ||
617 | * | ||
618 | * @return #GNUNET_NO to stop calling this callback with further variables, | ||
619 | * #GNUNET_YES to continue. | ||
620 | */; | ||
621 | typedef int | ||
622 | (*GNUNET_PSYCSTORE_StateCallback) (void *cls, const char *name, | ||
623 | const void *value, uint32_t value_size); | ||
624 | |||
625 | |||
626 | /** | ||
627 | * Retrieve the best matching state variable. | ||
628 | * | ||
629 | * @param h | ||
630 | * Handle for the PSYCstore. | ||
631 | * @param channel_key | ||
632 | * The channel we are interested in. | ||
633 | * @param name | ||
634 | * Name of variable to match, the returned variable might be less specific. | ||
635 | * @param state_cb | ||
636 | * Callback to return the matching state variable. | ||
637 | * @param result_cb | ||
638 | * Callback to call with the result of the operation. | ||
639 | * @param cls | ||
640 | * Closure for the callbacks. | ||
641 | * | ||
642 | * @return Handle that can be used to cancel the operation. | ||
643 | */ | ||
644 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
645 | GNUNET_PSYCSTORE_state_get (struct GNUNET_PSYCSTORE_Handle *h, | ||
646 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
647 | const char *name, | ||
648 | GNUNET_PSYCSTORE_StateCallback state_cb, | ||
649 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
650 | void *cls); | ||
651 | |||
652 | |||
653 | /** | ||
654 | * Retrieve all state variables for a channel with the given prefix. | ||
655 | * | ||
656 | * @param h | ||
657 | * Handle for the PSYCstore. | ||
658 | * @param channel_key | ||
659 | * The channel we are interested in. | ||
660 | * @param name_prefix | ||
661 | * Prefix of state variable names to match. | ||
662 | * @param state_cb | ||
663 | * Callback to return matching state variables. | ||
664 | * @param result_cb | ||
665 | * Callback to call with the result of the operation. | ||
666 | * @param cls | ||
667 | * Closure for the callbacks. | ||
668 | * | ||
669 | * @return Handle that can be used to cancel the operation. | ||
670 | */ | ||
671 | struct GNUNET_PSYCSTORE_OperationHandle * | ||
672 | GNUNET_PSYCSTORE_state_get_prefix (struct GNUNET_PSYCSTORE_Handle *h, | ||
673 | const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key, | ||
674 | const char *name_prefix, | ||
675 | GNUNET_PSYCSTORE_StateCallback state_cb, | ||
676 | GNUNET_PSYCSTORE_ResultCallback result_cb, | ||
677 | void *cls); | ||
678 | |||
679 | |||
680 | /** | ||
681 | * Cancel an operation. | ||
682 | * | ||
683 | * @param op Handle for the operation to cancel. | ||
684 | */ | ||
685 | int | ||
686 | GNUNET_PSYCSTORE_operation_cancel (struct GNUNET_PSYCSTORE_OperationHandle *op); | ||
687 | |||
688 | |||
689 | |||
690 | |||
691 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
692 | { | ||
693 | #endif | ||
694 | #ifdef __cplusplus | ||
695 | } | ||
696 | #endif | ||
697 | |||
698 | /* ifndef GNUNET_PSYCSTORE_SERVICE_H */ | ||
699 | #endif | ||
700 | |||
701 | /** @} */ /* end of group */ | ||
diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h new file mode 100644 index 0000000..7faa336 --- /dev/null +++ b/src/include/gnunet_social_service.h | |||
@@ -0,0 +1,1344 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2013 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Gabor X Toth | ||
23 | * @author Christian Grothoff | ||
24 | * | ||
25 | * @file | ||
26 | * Social service; implements social interactions through the PSYC service. | ||
27 | */ | ||
28 | |||
29 | /** @defgroup social Social service | ||
30 | Social interactions through the PSYC service. | ||
31 | |||
32 | # Overview | ||
33 | |||
34 | The social service provides an API for social interactions based on a one-to-many messaging model. | ||
35 | It manages subscriptions of applications to places, provides messaging functionality in places, | ||
36 | allows access to the local message history and manages the GNS zone of _egos_ (user identities). | ||
37 | |||
38 | The service stores private and public keys of subscribed places, as well as files received in subscribed places. | ||
39 | |||
40 | # Concepts and terminology | ||
41 | |||
42 | ## Ego, Nym | ||
43 | |||
44 | An _ego_ is an identity of a user, a private-public key pair. | ||
45 | A _nym_ is an identity of another user in the network, identified by its public key. | ||
46 | Each user can have multiple identities. | ||
47 | |||
48 | struct GNUNET_SOCIAL_Ego and struct GNUNET_SOCIAL_Nym represents one of these identities. | ||
49 | |||
50 | ## Place, Host, Guest | ||
51 | |||
52 | A _place_ is where social interactions happen. It is owned and created by an _ego_. | ||
53 | Creating a new place happens by an _ego_ entering a new place as a _host_, | ||
54 | where _guests_ can enter later to receive messages sent to the place. | ||
55 | |||
56 | A place is identified by its public key. | ||
57 | |||
58 | - struct GNUNET_SOCIAL_Host represents a place entered as host, | ||
59 | - struct GNUNET_SOCIAL_Guest is used for a place entered as guest. | ||
60 | - A struct GNUNET_SOCIAL_Place can be obtained for both a host and guest place | ||
61 | using GNUNET_SOCIAL_host_get_place() and GNUNET_SOCIAL_guest_get_place() | ||
62 | and can be used with API functions common to hosts and guests. | ||
63 | |||
64 | ## History | ||
65 | |||
66 | Messages sent to places are stored locally by the PSYCstore service, and can be queried any time. | ||
67 | GNUNET_SOCIAL_history_replay_latest() retrieves the latest N messages sent to the place, | ||
68 | while GNUNET_SOCIAL_history_replay() is used to query a given message ID range. | ||
69 | |||
70 | ## GNU Name System | ||
71 | |||
72 | The GNU Name System is used for assigning human-readable names to nyms and places. | ||
73 | There's a _GNS zone_ corresponding to each _nym_. | ||
74 | An _ego_ can publish PKEY and PLACE records in its own zone, pointing to nyms and places, respectively. | ||
75 | |||
76 | ## Announcement, talk request | ||
77 | |||
78 | The host can _announce_ messages to the place, using GNUNET_SOCIAL_host_announce(). | ||
79 | Guests can send _talk_ requests to the host, using GNUNET_SOCIAL_guest_talk(). | ||
80 | The host receives talk requests of guests and can _relay_ them to the place, | ||
81 | or process it using a message handler function. | ||
82 | |||
83 | # Using the API | ||
84 | |||
85 | ## Connecting to the service | ||
86 | |||
87 | A client first establishes an _application connection_ to the service using | ||
88 | GNUNET_SOCIAL_app_connect() providing its _application ID_, then receives the | ||
89 | public keys of subscribed places and available egos in response. | ||
90 | |||
91 | ## Reconnecting to places | ||
92 | |||
93 | Then the application can reconnect to its subscribed places by establishing | ||
94 | _place connections_ with GNUNET_SOCIAL_host_enter_reconnect() and | ||
95 | GNUNET_SOCIAL_guest_enter_reconnect(). | ||
96 | |||
97 | ## Subscribing to a place | ||
98 | |||
99 | Entering and subscribing a new host or guest place is done using | ||
100 | GNUNET_SOCIAL_host_enter() and GNUNET_SOCIAL_guest_enter(). | ||
101 | |||
102 | ## Disconnecting from a place | ||
103 | |||
104 | An application can disconnect from a place while the social service keeps its | ||
105 | network connection active, using GNUNET_SOCIAL_host_disconnect() and | ||
106 | GNUNET_SOCIAL_guest_disconnect(). | ||
107 | |||
108 | ## Leaving a place | ||
109 | |||
110 | To permanently leave a place, see GNUNET_SOCIAL_host_leave() and GNUNET_SOCIAL_guest_leave(). | ||
111 | When leaving a place its network connections are closed and all applications are unsubscribed from the place. | ||
112 | |||
113 | # Message methods | ||
114 | |||
115 | ## _converse | ||
116 | |||
117 | Human conversation in a private or public place. | ||
118 | |||
119 | ### Environment | ||
120 | |||
121 | #### _id_reply | ||
122 | Message ID this message is in reply to. | ||
123 | |||
124 | #### _id_thread | ||
125 | Thread ID, the first message ID in the thread. | ||
126 | |||
127 | #### _nym_author | ||
128 | Nym of the author. | ||
129 | |||
130 | FIXME: Are nyms a different data type from egos and person entities? | ||
131 | Do they have a different format than any other entity address? | ||
132 | Questions and thoughts on how to fix this in "questions.org" | ||
133 | |||
134 | #### _sig_author | ||
135 | Signature of the message body and its variables by the author. | ||
136 | |||
137 | ### Data | ||
138 | |||
139 | Message body. | ||
140 | |||
141 | ## _notice_place | ||
142 | |||
143 | Notification about a place. | ||
144 | |||
145 | TODO: Applications can decide to auto-subscribe to certain places, | ||
146 | e.g. files under a given size. | ||
147 | |||
148 | ### Environment | ||
149 | |||
150 | #### Using GNS | ||
151 | |||
152 | ##### _gns_place | ||
153 | GNS name of the place in a globally unique .zkey zone | ||
154 | |||
155 | FIXME: A custom _gns PSYC data type should be avoidable by parsing | ||
156 | and interpreting PSYC uniforms appropriately. | ||
157 | Thoughts on this in "questions.org" | ||
158 | |||
159 | #### Without GNS | ||
160 | |||
161 | ##### _key_pub_place | ||
162 | Public key of place | ||
163 | |||
164 | FIXME: _key_pub can't be the data type for GNUnet-specific cryptographic | ||
165 | addressing. Questions and thoughts on how to fix this in "questions.org" | ||
166 | |||
167 | ##### _peer_origin | ||
168 | Peer ID of origin | ||
169 | |||
170 | ##### _list_peer_relays | ||
171 | List of peer IDs of relays | ||
172 | |||
173 | ## _notice_place_file | ||
174 | |||
175 | Notification about a place hosting a file. | ||
176 | |||
177 | ### Environment | ||
178 | |||
179 | The environment of _notice_place above, plus the following: | ||
180 | |||
181 | #### _size_file | ||
182 | Size of file | ||
183 | |||
184 | #### _type_file | ||
185 | MIME type of file | ||
186 | |||
187 | #### _name_file | ||
188 | Name of file | ||
189 | |||
190 | #### _description_file | ||
191 | Description of file | ||
192 | |||
193 | ## _file | ||
194 | |||
195 | Messages with a _file method contain a file, | ||
196 | which is saved to disk upon reception at the following location: | ||
197 | $GNUNET_DATA_HOME/social/files/<H(place_pub)>/<H(message_id)> | ||
198 | |||
199 | ### Environment | ||
200 | |||
201 | #### _size_file | ||
202 | Size of file | ||
203 | |||
204 | #### _type_file | ||
205 | MIME type of file | ||
206 | |||
207 | #### _name_file | ||
208 | Name of file | ||
209 | |||
210 | #### _description_file | ||
211 | Description of file | ||
212 | |||
213 | @{ | ||
214 | */ | ||
215 | |||
216 | |||
217 | #ifndef GNUNET_SOCIAL_SERVICE_H | ||
218 | #define GNUNET_SOCIAL_SERVICE_H | ||
219 | |||
220 | #ifdef __cplusplus | ||
221 | extern "C" | ||
222 | { | ||
223 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
224 | } | ||
225 | #endif | ||
226 | #endif | ||
227 | |||
228 | #include <stdint.h> | ||
229 | #include "gnunet_util_lib.h" | ||
230 | #include "gnunet_psyc_util_lib.h" | ||
231 | #include "gnunet_identity_service.h" | ||
232 | #include "gnunet_namestore_service.h" | ||
233 | #include "gnunet_psyc_service.h" | ||
234 | |||
235 | |||
236 | /** | ||
237 | * Version number of GNUnet Social API. | ||
238 | */ | ||
239 | #define GNUNET_SOCIAL_VERSION 0x00000000 | ||
240 | |||
241 | /** | ||
242 | * Maximum size of client ID including '\0' terminator. | ||
243 | */ | ||
244 | #define GNUNET_SOCIAL_APP_MAX_ID_SIZE 256 | ||
245 | |||
246 | enum GNUNET_SOCIAL_MsgProcFlags { | ||
247 | GNUNET_SOCIAL_MSG_PROC_NONE = 0, | ||
248 | GNUNET_SOCIAL_MSG_PROC_RELAY = 1, | ||
249 | GNUNET_SOCIAL_MSG_PROC_SAVE= 2, | ||
250 | }; | ||
251 | |||
252 | /** | ||
253 | * Handle for an application. | ||
254 | */ | ||
255 | struct GNUNET_SOCIAL_App; | ||
256 | |||
257 | /** | ||
258 | * Handle for an ego (own identity) | ||
259 | */ | ||
260 | struct GNUNET_SOCIAL_Ego; | ||
261 | |||
262 | /** | ||
263 | * Handle for a pseudonym of another user in the network. | ||
264 | */ | ||
265 | struct GNUNET_SOCIAL_Nym; | ||
266 | |||
267 | /** | ||
268 | * Handle for a place where social interactions happen. | ||
269 | */ | ||
270 | struct GNUNET_SOCIAL_Place; | ||
271 | |||
272 | /** | ||
273 | * Host handle for a place that we entered. | ||
274 | */ | ||
275 | struct GNUNET_SOCIAL_Host; | ||
276 | |||
277 | /** | ||
278 | * Guest handle for place that we entered. | ||
279 | */ | ||
280 | struct GNUNET_SOCIAL_Guest; | ||
281 | |||
282 | /** | ||
283 | * Handle that can be used to reconnect to a place as host. | ||
284 | */ | ||
285 | struct GNUNET_SOCIAL_HostConnection; | ||
286 | |||
287 | /** | ||
288 | * Handle that can be used to reconnect to a place as guest. | ||
289 | */ | ||
290 | struct GNUNET_SOCIAL_GuestConnection; | ||
291 | |||
292 | /** | ||
293 | * Notification about an available identity. | ||
294 | * | ||
295 | * @param cls | ||
296 | * Closure. | ||
297 | * @param pub_key | ||
298 | * Public key of ego. | ||
299 | * @param name | ||
300 | * Name of ego. | ||
301 | */ | ||
302 | typedef void | ||
303 | (*GNUNET_SOCIAL_AppEgoCallback) (void *cls, | ||
304 | struct GNUNET_SOCIAL_Ego *ego, | ||
305 | const struct GNUNET_CRYPTO_EcdsaPublicKey *ego_pub_key, | ||
306 | const char *name); | ||
307 | |||
308 | |||
309 | /** | ||
310 | * Entry status of a place per application. | ||
311 | */ | ||
312 | enum GNUNET_SOCIAL_AppPlaceState | ||
313 | { | ||
314 | /** | ||
315 | * The place was once entered by the ego, but left since. | ||
316 | * It's possible to establish a local connection to the place | ||
317 | * without re-entering to fetch history from the PSYCstore. | ||
318 | * @see enum GNUNET_PSYC_SlaveJoinFlags and GNUNET_SOCIAL_guest_enter() | ||
319 | */ | ||
320 | GNUNET_SOCIAL_PLACE_STATE_ARCHIVED = 0, | ||
321 | |||
322 | /** | ||
323 | * The place is entered by the ego, | ||
324 | * but this application is not subscribed to it. | ||
325 | */ | ||
326 | GNUNET_SOCIAL_PLACE_STATE_ENTERED = 1, | ||
327 | |||
328 | /** | ||
329 | * The place is entered by the ego and | ||
330 | * and this application is subscribed to it. | ||
331 | */ | ||
332 | GNUNET_SOCIAL_PLACE_STATE_SUBSCRIBED = 2, | ||
333 | }; | ||
334 | |||
335 | |||
336 | /** | ||
337 | * Called after receiving initial list of egos and places. | ||
338 | */ | ||
339 | typedef void | ||
340 | (*GNUNET_SOCIAL_AppConnectedCallback) (void *cls); | ||
341 | |||
342 | |||
343 | /** | ||
344 | * Notification about a home. | ||
345 | * | ||
346 | * @param cls | ||
347 | * Closure. | ||
348 | * @param hconn | ||
349 | * Host connection, to be used with GNUNET_SOCIAL_host_enter_reconnect() | ||
350 | * @param ego | ||
351 | * Ego used to enter the place. | ||
352 | * @param place_pub_key | ||
353 | * Public key of the place. | ||
354 | * @param place_state | ||
355 | * @see enum GNUNET_SOCIAL_AppPlaceState | ||
356 | */ | ||
357 | typedef void | ||
358 | (*GNUNET_SOCIAL_AppHostPlaceCallback) (void *cls, | ||
359 | struct GNUNET_SOCIAL_HostConnection *hconn, | ||
360 | struct GNUNET_SOCIAL_Ego *ego, | ||
361 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
362 | enum GNUNET_SOCIAL_AppPlaceState place_state); | ||
363 | |||
364 | /** | ||
365 | * Notification about a place. | ||
366 | * | ||
367 | * @param cls | ||
368 | * Closure. | ||
369 | * @param gconn | ||
370 | * Guest connection, to be used with GNUNET_SOCIAL_guest_enter_reconnect() | ||
371 | * @param ego | ||
372 | * Ego used to enter the place. | ||
373 | * @param place_pub_key | ||
374 | * Public key of the place. | ||
375 | * @param place_state | ||
376 | * @see enum GNUNET_SOCIAL_AppPlaceState | ||
377 | */ | ||
378 | typedef void | ||
379 | (*GNUNET_SOCIAL_AppGuestPlaceCallback) (void *cls, | ||
380 | struct GNUNET_SOCIAL_GuestConnection *gconn, | ||
381 | struct GNUNET_SOCIAL_Ego *ego, | ||
382 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
383 | enum GNUNET_SOCIAL_AppPlaceState place_state); | ||
384 | |||
385 | |||
386 | /** | ||
387 | * Establish application connection to the social service. | ||
388 | * | ||
389 | * The @host_cb and @guest_cb functions are | ||
390 | * initially called for each entered places, | ||
391 | * then later each time a new place is entered with the current app ID. | ||
392 | * | ||
393 | * @param cfg | ||
394 | * Configuration. | ||
395 | * @param ego_cb | ||
396 | * Function to notify about an available ego. | ||
397 | * @param host_cb | ||
398 | * Function to notify about a place entered as host. | ||
399 | * @param guest_cb | ||
400 | * Function to notify about a place entered as guest. | ||
401 | * @param cls | ||
402 | * Closure for the callbacks. | ||
403 | * | ||
404 | * @return Handle that can be used to stop listening. | ||
405 | */ | ||
406 | struct GNUNET_SOCIAL_App * | ||
407 | GNUNET_SOCIAL_app_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
408 | const char *id, | ||
409 | GNUNET_SOCIAL_AppEgoCallback ego_cb, | ||
410 | GNUNET_SOCIAL_AppHostPlaceCallback host_cb, | ||
411 | GNUNET_SOCIAL_AppGuestPlaceCallback guest_cb, | ||
412 | GNUNET_SOCIAL_AppConnectedCallback connected_cb, | ||
413 | void *cls); | ||
414 | |||
415 | |||
416 | /** | ||
417 | * Disconnect app. | ||
418 | * | ||
419 | * @param app | ||
420 | * Application handle. | ||
421 | * @param disconnect_cb | ||
422 | * Disconnect callback. | ||
423 | * @param disconnect_cls | ||
424 | * Disconnect closure. | ||
425 | */ | ||
426 | void | ||
427 | GNUNET_SOCIAL_app_disconnect (struct GNUNET_SOCIAL_App *app, | ||
428 | GNUNET_ContinuationCallback disconnect_cb, | ||
429 | void *disconnect_cls); | ||
430 | |||
431 | |||
432 | /** | ||
433 | * Get the public key of @a ego. | ||
434 | * | ||
435 | * @param ego | ||
436 | * Ego. | ||
437 | * | ||
438 | * @return Public key of ego. | ||
439 | */ | ||
440 | const struct GNUNET_CRYPTO_EcdsaPublicKey * | ||
441 | GNUNET_SOCIAL_ego_get_pub_key (const struct GNUNET_SOCIAL_Ego *ego); | ||
442 | |||
443 | |||
444 | /** | ||
445 | * Get the name of @a ego. | ||
446 | * | ||
447 | * @param ego | ||
448 | * Ego. | ||
449 | * | ||
450 | * @return Public key of @a ego. | ||
451 | */ | ||
452 | const char * | ||
453 | GNUNET_SOCIAL_ego_get_name (const struct GNUNET_SOCIAL_Ego *ego); | ||
454 | |||
455 | |||
456 | /** | ||
457 | * Get the public key of a @a nym. | ||
458 | * | ||
459 | * Suitable, for example, to be used with GNUNET_SOCIAL_zone_add_nym(). | ||
460 | * | ||
461 | * @param nym | ||
462 | * Pseudonym to map to a cryptographic identifier. | ||
463 | * | ||
464 | * @return Public key of nym. | ||
465 | */ | ||
466 | const struct GNUNET_CRYPTO_EcdsaPublicKey * | ||
467 | GNUNET_SOCIAL_nym_get_pub_key (const struct GNUNET_SOCIAL_Nym *nym); | ||
468 | |||
469 | |||
470 | /** | ||
471 | * Get the hash of the public key of a @a nym. | ||
472 | * | ||
473 | * @param nym | ||
474 | * Pseudonym to map to a cryptographic identifier. | ||
475 | * | ||
476 | * @return Hash of the public key of nym. | ||
477 | */ | ||
478 | const struct GNUNET_HashCode * | ||
479 | GNUNET_SOCIAL_nym_get_pub_key_hash (const struct GNUNET_SOCIAL_Nym *nym); | ||
480 | |||
481 | |||
482 | /** | ||
483 | * Function called asking for nym to be admitted to the place. | ||
484 | * | ||
485 | * Should call either GNUNET_SOCIAL_host_admit() or | ||
486 | * GNUNET_SOCIAL_host_reject_entry() (possibly asynchronously). If this host | ||
487 | * cannot decide, it is fine to call neither function, in which case hopefully | ||
488 | * some other host of the place exists that will make the decision. The @a nym | ||
489 | * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked | ||
490 | * for it. | ||
491 | * | ||
492 | * @param cls | ||
493 | * Closure. | ||
494 | * @param nym | ||
495 | * Handle for the user who wants to enter. | ||
496 | * @param method_name | ||
497 | * Method name in the entry request. | ||
498 | * @param variable_count | ||
499 | * Number of elements in the @a variables array. | ||
500 | * @param variables | ||
501 | * Variables present in the message. | ||
502 | * @param data | ||
503 | * Payload given on enter (e.g. a password). | ||
504 | * @param data_size | ||
505 | * Number of bytes in @a data. | ||
506 | */ | ||
507 | typedef void | ||
508 | (*GNUNET_SOCIAL_AnswerDoorCallback) (void *cls, | ||
509 | struct GNUNET_SOCIAL_Nym *nym, | ||
510 | const char *method_name, | ||
511 | struct GNUNET_PSYC_Environment *env, | ||
512 | const void *data, | ||
513 | size_t data_size); | ||
514 | |||
515 | |||
516 | /** | ||
517 | * Function called when a @a nym leaves the place. | ||
518 | * | ||
519 | * This is also called if the @a nym was never given permission to enter | ||
520 | * (i.e. the @a nym stopped asking to get in). | ||
521 | * | ||
522 | * @param cls | ||
523 | * Closure. | ||
524 | * @param nym | ||
525 | * Handle for the user who left. | ||
526 | */ | ||
527 | typedef void | ||
528 | (*GNUNET_SOCIAL_FarewellCallback) (void *cls, | ||
529 | const struct GNUNET_SOCIAL_Nym *nym, | ||
530 | struct GNUNET_PSYC_Environment *env); | ||
531 | |||
532 | |||
533 | /** | ||
534 | * Function called after the host entered a home. | ||
535 | * | ||
536 | * @param cls | ||
537 | * Closure. | ||
538 | * @param result | ||
539 | * #GNUNET_OK on success, or | ||
540 | * #GNUNET_SYSERR on error. | ||
541 | * @param place_pub_key | ||
542 | * Public key of home. | ||
543 | * @param max_message_id | ||
544 | * Last message ID sent to the channel. | ||
545 | * Or 0 if no messages have been sent to the place yet. | ||
546 | */ | ||
547 | typedef void | ||
548 | (*GNUNET_SOCIAL_HostEnterCallback) (void *cls, int result, | ||
549 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
550 | uint64_t max_message_id); | ||
551 | |||
552 | |||
553 | /** | ||
554 | * Enter a place as host. | ||
555 | * | ||
556 | * A place is created upon first entering, and it is active until permanently | ||
557 | * left using GNUNET_SOCIAL_host_leave(). | ||
558 | * | ||
559 | * @param cfg | ||
560 | * Configuration to contact the social service. | ||
561 | * @param ego | ||
562 | * Identity of the host. | ||
563 | * @param place_key | ||
564 | * Private-public key pair of the place. | ||
565 | * NULL for ephemeral places. | ||
566 | * @param policy | ||
567 | * Policy specifying entry and history restrictions for the place. | ||
568 | * @param slicer | ||
569 | * Slicer to handle incoming messages. | ||
570 | * @param enter_cb | ||
571 | * Function called when the place is entered and ready to use. | ||
572 | * @param answer_door_cb | ||
573 | * Function to handle new nyms that want to enter. | ||
574 | * @param farewell_cb | ||
575 | * Function to handle departing nyms. | ||
576 | * @param cls | ||
577 | * Closure for the callbacks. | ||
578 | * | ||
579 | * @return Handle for the host. | ||
580 | */ | ||
581 | struct GNUNET_SOCIAL_Host * | ||
582 | GNUNET_SOCIAL_host_enter (const struct GNUNET_SOCIAL_App *app, | ||
583 | const struct GNUNET_SOCIAL_Ego *ego, | ||
584 | enum GNUNET_PSYC_Policy policy, | ||
585 | struct GNUNET_PSYC_Slicer *slicer, | ||
586 | GNUNET_SOCIAL_HostEnterCallback enter_cb, | ||
587 | GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb, | ||
588 | GNUNET_SOCIAL_FarewellCallback farewell_cb, | ||
589 | void *cls); | ||
590 | |||
591 | |||
592 | /** | ||
593 | * Reconnect to an already entered place as host. | ||
594 | * | ||
595 | * @param hconn | ||
596 | * Host connection handle. | ||
597 | * @see GNUNET_SOCIAL_app_connect() & GNUNET_SOCIAL_AppHostPlaceCallback() | ||
598 | * @param slicer | ||
599 | * Slicer to handle incoming messages. | ||
600 | * @param enter_cb | ||
601 | * Function called when the place is entered and ready to use. | ||
602 | * @param answer_door_cb | ||
603 | * Function to handle new nyms that want to enter. | ||
604 | * @param farewell_cb | ||
605 | * Function to handle departing nyms. | ||
606 | * @param cls | ||
607 | * Closure for the callbacks. | ||
608 | * | ||
609 | * @return Handle for the host. | ||
610 | */ | ||
611 | struct GNUNET_SOCIAL_Host * | ||
612 | GNUNET_SOCIAL_host_enter_reconnect (struct GNUNET_SOCIAL_HostConnection *hconn, | ||
613 | struct GNUNET_PSYC_Slicer *slicer, | ||
614 | GNUNET_SOCIAL_HostEnterCallback enter_cb, | ||
615 | GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb, | ||
616 | GNUNET_SOCIAL_FarewellCallback farewell_cb, | ||
617 | void *cls); | ||
618 | |||
619 | |||
620 | /** | ||
621 | * Decision whether to admit @a nym into the place or refuse entry. | ||
622 | * | ||
623 | * @param hst | ||
624 | * Host of the place. | ||
625 | * @param nym | ||
626 | * Handle for the entity that wanted to enter. | ||
627 | * @param is_admitted | ||
628 | * #GNUNET_YES if @a nym is admitted, | ||
629 | * #GNUNET_NO if @a nym is refused entry, | ||
630 | * #GNUNET_SYSERR if we cannot answer the request. | ||
631 | * @param entry_resp | ||
632 | * Entry response message, or NULL. | ||
633 | * @return #GNUNET_OK on success, | ||
634 | * #GNUNET_SYSERR if the message is too large. | ||
635 | */ | ||
636 | int | ||
637 | GNUNET_SOCIAL_host_entry_decision (struct GNUNET_SOCIAL_Host *hst, | ||
638 | struct GNUNET_SOCIAL_Nym *nym, | ||
639 | int is_admitted, | ||
640 | const struct GNUNET_PSYC_Message *entry_resp); | ||
641 | |||
642 | |||
643 | /** | ||
644 | * Throw @a nym out of the place. | ||
645 | * | ||
646 | * Sends a _notice_place_leave announcement to the home. | ||
647 | * | ||
648 | * The @a nym reference will remain valid until the | ||
649 | * #GNUNET_SOCIAL_FarewellCallback is invoked, | ||
650 | * which should be very soon after this call. | ||
651 | * | ||
652 | * @param host | ||
653 | * Host of the place. | ||
654 | * @param nym | ||
655 | * Handle for the entity to be ejected. | ||
656 | * @param env | ||
657 | * Environment for the message or NULL. | ||
658 | * _nym is set to @e nym regardless whether an @e env is provided. | ||
659 | */ | ||
660 | void | ||
661 | GNUNET_SOCIAL_host_eject (struct GNUNET_SOCIAL_Host *host, | ||
662 | const struct GNUNET_SOCIAL_Nym *nym, | ||
663 | struct GNUNET_PSYC_Environment *env); | ||
664 | |||
665 | |||
666 | /** | ||
667 | * Flags for announcements by a host. | ||
668 | */ | ||
669 | enum GNUNET_SOCIAL_AnnounceFlags | ||
670 | { | ||
671 | GNUNET_SOCIAL_ANNOUNCE_NONE = 0, | ||
672 | |||
673 | /** | ||
674 | * Whether this announcement removes all objects from the place. | ||
675 | * | ||
676 | * New objects can be still added to the now empty place using the @e env | ||
677 | * parameter of the same announcement. | ||
678 | */ | ||
679 | GNUNET_SOCIAL_ANNOUNCE_CLEAR_OBJECTS = 1 << 0 | ||
680 | }; | ||
681 | |||
682 | |||
683 | /** | ||
684 | * Handle for an announcement request. | ||
685 | */ | ||
686 | struct GNUNET_SOCIAL_Announcement; | ||
687 | |||
688 | |||
689 | /** | ||
690 | * Send a message to all nyms that are present in the place. | ||
691 | * | ||
692 | * This function is restricted to the host. Nyms can only send requests | ||
693 | * to the host who can decide to relay it to everyone in the place. | ||
694 | * | ||
695 | * @param host | ||
696 | * Host of the place. | ||
697 | * @param method_name | ||
698 | * Method to use for the announcement. | ||
699 | * @param env | ||
700 | * Environment containing variables for the message and operations | ||
701 | * on objects of the place. | ||
702 | * Has to remain available until the first call to @a notify_data. | ||
703 | * Can be NULL. | ||
704 | * @param notify_data | ||
705 | * Function to call to get the payload of the announcement. | ||
706 | * @param notify_data_cls | ||
707 | * Closure for @a notify. | ||
708 | * @param flags | ||
709 | * Flags for this announcement. | ||
710 | * | ||
711 | * @return NULL on error (another announcement already in progress?). | ||
712 | */ | ||
713 | struct GNUNET_SOCIAL_Announcement * | ||
714 | GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host, | ||
715 | const char *method_name, | ||
716 | const struct GNUNET_PSYC_Environment *env, | ||
717 | GNUNET_PSYC_TransmitNotifyData notify_data, | ||
718 | void *notify_data_cls, | ||
719 | enum GNUNET_SOCIAL_AnnounceFlags flags); | ||
720 | |||
721 | |||
722 | /** | ||
723 | * Resume transmitting announcement. | ||
724 | * | ||
725 | * @param a | ||
726 | * The announcement to resume. | ||
727 | */ | ||
728 | void | ||
729 | GNUNET_SOCIAL_host_announce_resume (struct GNUNET_SOCIAL_Announcement *a); | ||
730 | |||
731 | |||
732 | /** | ||
733 | * Cancel announcement. | ||
734 | * | ||
735 | * @param a | ||
736 | * The announcement to cancel. | ||
737 | */ | ||
738 | void | ||
739 | GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a); | ||
740 | |||
741 | |||
742 | /** | ||
743 | * Allow relaying messages from guests matching a given @a method_prefix. | ||
744 | * | ||
745 | * @param host | ||
746 | * The host. | ||
747 | * @param method_prefix | ||
748 | * Method prefix to allow. | ||
749 | */ | ||
750 | void | ||
751 | GNUNET_SOCIAL_host_relay_allow_method (struct GNUNET_SOCIAL_Host *host, | ||
752 | const char *method_prefix); | ||
753 | |||
754 | |||
755 | /** | ||
756 | * Allow relaying changes to objects of the place. | ||
757 | * | ||
758 | * Only applies to messages with an allowed method name. | ||
759 | * @see GNUNET_SCOIAL_host_relay_allow_method() | ||
760 | * | ||
761 | * @param host | ||
762 | * The host. | ||
763 | * @param object_prefix | ||
764 | * Object prefix to allow modifying. | ||
765 | */ | ||
766 | void | ||
767 | GNUNET_SOCIAL_host_relay_allow_method (struct GNUNET_SOCIAL_Host *host, | ||
768 | const char *object_prefix); | ||
769 | |||
770 | |||
771 | /** | ||
772 | * Stop relaying messages from guests. | ||
773 | * | ||
774 | * Remove all allowed relay rules. | ||
775 | * | ||
776 | * | ||
777 | * | ||
778 | */ | ||
779 | void | ||
780 | GNUNET_SOCIAL_host_relay_stop (struct GNUNET_SOCIAL_Host *host); | ||
781 | |||
782 | |||
783 | /** | ||
784 | * Obtain handle for a hosted place. | ||
785 | * | ||
786 | * The returned handle can be used to access the place API. | ||
787 | * | ||
788 | * @param host | ||
789 | * Handle for the host. | ||
790 | * | ||
791 | * @return Handle for the hosted place, valid as long as @a host is valid. | ||
792 | */ | ||
793 | struct GNUNET_SOCIAL_Place * | ||
794 | GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host); | ||
795 | |||
796 | |||
797 | /** | ||
798 | * Disconnect from a home. | ||
799 | * | ||
800 | * Invalidates host handle. | ||
801 | * | ||
802 | * @param hst | ||
803 | * The host to disconnect. | ||
804 | * @param disconnect_cb | ||
805 | * Function called after disconnected from the service. | ||
806 | * @param cls | ||
807 | * Closure for @a disconnect_cb. | ||
808 | */ | ||
809 | void | ||
810 | GNUNET_SOCIAL_host_disconnect (struct GNUNET_SOCIAL_Host *hst, | ||
811 | GNUNET_ContinuationCallback disconnect_cb, | ||
812 | void *cls); | ||
813 | |||
814 | |||
815 | /** | ||
816 | * Stop hosting a home. | ||
817 | * | ||
818 | * Sends a _notice_place_closing announcement to the home. | ||
819 | * Invalidates host handle. | ||
820 | * | ||
821 | * @param hst | ||
822 | * Host leaving. | ||
823 | * @param env | ||
824 | * Environment for the message or NULL. | ||
825 | * @param disconnect_cb | ||
826 | * Function called after the host left the place | ||
827 | * and disconnected from the service. | ||
828 | * @param cls | ||
829 | * Closure for @a disconnect_cb. | ||
830 | */ | ||
831 | void | ||
832 | GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *hst, | ||
833 | const struct GNUNET_PSYC_Environment *env, | ||
834 | GNUNET_ContinuationCallback disconnect_cb, | ||
835 | void *cls); | ||
836 | |||
837 | |||
838 | /** | ||
839 | * Function called after the guest entered the local copy of the place. | ||
840 | * | ||
841 | * History and object query functions can be used after this call, | ||
842 | * but new messages can't be sent or received. | ||
843 | * | ||
844 | * @param cls | ||
845 | * Closure. | ||
846 | * @param result | ||
847 | * #GNUNET_OK on success, or | ||
848 | * #GNUNET_SYSERR on error, e.g. could not connect to the service, or | ||
849 | * could not resolve GNS name. | ||
850 | * @param place_pub_key | ||
851 | * Public key of place. | ||
852 | * @param max_message_id | ||
853 | * Last message ID sent to the place. | ||
854 | * Or 0 if no messages have been sent to the place yet. | ||
855 | */ | ||
856 | typedef void | ||
857 | (*GNUNET_SOCIAL_GuestEnterCallback) (void *cls, int result, | ||
858 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
859 | uint64_t max_message_id); | ||
860 | |||
861 | |||
862 | /** | ||
863 | * Function called upon a guest receives a decision about entry to the place. | ||
864 | * | ||
865 | * @param is_admitted | ||
866 | * Is the guest admitted to the place? | ||
867 | * #GNUNET_YES if admitted, | ||
868 | * #GNUNET_NO if refused entry, | ||
869 | * #GNUNET_SYSERR if the request could not be answered. | ||
870 | * @param data | ||
871 | * Entry response message. | ||
872 | */ | ||
873 | typedef void | ||
874 | (*GNUNET_SOCIAL_EntryDecisionCallback) (void *cls, | ||
875 | int is_admitted, | ||
876 | const struct GNUNET_PSYC_Message *entry_resp); | ||
877 | |||
878 | |||
879 | /** | ||
880 | * Request entry to a place as a guest. | ||
881 | * | ||
882 | * @param app | ||
883 | * Application handle. | ||
884 | * @param ego | ||
885 | * Identity of the guest. | ||
886 | * @param place_pub_key | ||
887 | * Public key of the place to enter. | ||
888 | * @param flags | ||
889 | * Flags for the entry. | ||
890 | * @param origin | ||
891 | * Peer identity of the origin of the underlying multicast group. | ||
892 | * @param relay_count | ||
893 | * Number of elements in the @a relays array. | ||
894 | * @param relays | ||
895 | * Relays for the underlying multicast group. | ||
896 | * @param entry_msg | ||
897 | * Entry message. | ||
898 | * @param slicer | ||
899 | * Slicer to use for processing incoming requests from guests. | ||
900 | * | ||
901 | * @return NULL on errors, otherwise handle for the guest. | ||
902 | */ | ||
903 | struct GNUNET_SOCIAL_Guest * | ||
904 | GNUNET_SOCIAL_guest_enter (const struct GNUNET_SOCIAL_App *app, | ||
905 | const struct GNUNET_SOCIAL_Ego *ego, | ||
906 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
907 | enum GNUNET_PSYC_SlaveJoinFlags flags, | ||
908 | const struct GNUNET_PeerIdentity *origin, | ||
909 | uint32_t relay_count, | ||
910 | const struct GNUNET_PeerIdentity *relays, | ||
911 | const struct GNUNET_PSYC_Message *entry_msg, | ||
912 | struct GNUNET_PSYC_Slicer *slicer, | ||
913 | GNUNET_SOCIAL_GuestEnterCallback local_enter_cb, | ||
914 | GNUNET_SOCIAL_EntryDecisionCallback entry_dcsn_cb, | ||
915 | void *cls); | ||
916 | |||
917 | |||
918 | /** | ||
919 | * Request entry to a place by name as a guest. | ||
920 | * | ||
921 | * @param app | ||
922 | * Application handle. | ||
923 | * @param ego | ||
924 | * Identity of the guest. | ||
925 | * @param gns_name | ||
926 | * GNS name of the place to enter. Either in the form of | ||
927 | * 'room.friend.gnu', or 'NYMPUBKEY.zkey'. This latter case refers to | ||
928 | * the 'PLACE' record of the empty label ("+") in the GNS zone with the | ||
929 | * nym's public key 'NYMPUBKEY', and can be used to request entry to a | ||
930 | * pseudonym's place directly. | ||
931 | * @param password | ||
932 | * Password to decrypt the record, or NULL for cleartext records. | ||
933 | * @param join_msg | ||
934 | * Entry request message. | ||
935 | * @param slicer | ||
936 | * Slicer to use for processing incoming requests from guests. | ||
937 | * @param local_enter_cb | ||
938 | * Called upon connection established to the social service. | ||
939 | * @param entry_decision_cb | ||
940 | * Called upon receiving entry decision. | ||
941 | * | ||
942 | * @return NULL on errors, otherwise handle for the guest. | ||
943 | */ | ||
944 | struct GNUNET_SOCIAL_Guest * | ||
945 | GNUNET_SOCIAL_guest_enter_by_name (const struct GNUNET_SOCIAL_App *app, | ||
946 | const struct GNUNET_SOCIAL_Ego *ego, | ||
947 | const char *gns_name, | ||
948 | const char *password, | ||
949 | const struct GNUNET_PSYC_Message *join_msg, | ||
950 | struct GNUNET_PSYC_Slicer *slicer, | ||
951 | GNUNET_SOCIAL_GuestEnterCallback local_enter_cb, | ||
952 | GNUNET_SOCIAL_EntryDecisionCallback entry_decision_cb, | ||
953 | void *cls); | ||
954 | |||
955 | |||
956 | /** | ||
957 | * Reconnect to an already entered place as guest. | ||
958 | * | ||
959 | * @param gconn | ||
960 | * Guest connection handle. | ||
961 | * @see GNUNET_SOCIAL_app_connect() & GNUNET_SOCIAL_AppGuestPlaceCallback() | ||
962 | * @param flags | ||
963 | * Flags for the entry. | ||
964 | * @param slicer | ||
965 | * Slicer to use for processing incoming requests from guests. | ||
966 | * @param local_enter_cb | ||
967 | * Called upon connection established to the social service. | ||
968 | * @param entry_decision_cb | ||
969 | * Called upon receiving entry decision. | ||
970 | * | ||
971 | * @return NULL on errors, otherwise handle for the guest. | ||
972 | */ | ||
973 | struct GNUNET_SOCIAL_Guest * | ||
974 | GNUNET_SOCIAL_guest_enter_reconnect (struct GNUNET_SOCIAL_GuestConnection *gconn, | ||
975 | enum GNUNET_PSYC_SlaveJoinFlags flags, | ||
976 | struct GNUNET_PSYC_Slicer *slicer, | ||
977 | GNUNET_SOCIAL_GuestEnterCallback local_enter_cb, | ||
978 | void *cls); | ||
979 | |||
980 | |||
981 | /** | ||
982 | * Flags for talking to the host of a place. | ||
983 | */ | ||
984 | enum GNUNET_SOCIAL_TalkFlags | ||
985 | { | ||
986 | GNUNET_SOCIAL_TALK_NONE = 0 | ||
987 | }; | ||
988 | |||
989 | |||
990 | /** | ||
991 | * A talk request. | ||
992 | */ | ||
993 | struct GNUNET_SOCIAL_TalkRequest; | ||
994 | |||
995 | |||
996 | /** | ||
997 | * Talk to the host of the place. | ||
998 | * | ||
999 | * @param place | ||
1000 | * Place where we want to talk to the host. | ||
1001 | * @param method_name | ||
1002 | * Method to invoke on the host. | ||
1003 | * @param env | ||
1004 | * Environment containing variables for the message, or NULL. | ||
1005 | * @param notify_data | ||
1006 | * Function to use to get the payload for the method. | ||
1007 | * @param notify_data_cls | ||
1008 | * Closure for @a notify_data. | ||
1009 | * @param flags | ||
1010 | * Flags for the message being sent. | ||
1011 | * | ||
1012 | * @return NULL if we are already trying to talk to the host, | ||
1013 | * otherwise handle to cancel the request. | ||
1014 | */ | ||
1015 | struct GNUNET_SOCIAL_TalkRequest * | ||
1016 | GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Guest *guest, | ||
1017 | const char *method_name, | ||
1018 | const struct GNUNET_PSYC_Environment *env, | ||
1019 | GNUNET_PSYC_TransmitNotifyData notify_data, | ||
1020 | void *notify_data_cls, | ||
1021 | enum GNUNET_SOCIAL_TalkFlags flags); | ||
1022 | |||
1023 | |||
1024 | /** | ||
1025 | * Resume talking to the host of the place. | ||
1026 | * | ||
1027 | * @param tr | ||
1028 | * Talk request to resume. | ||
1029 | */ | ||
1030 | void | ||
1031 | GNUNET_SOCIAL_guest_talk_resume (struct GNUNET_SOCIAL_TalkRequest *tr); | ||
1032 | |||
1033 | |||
1034 | /** | ||
1035 | * Cancel talking to the host of the place. | ||
1036 | * | ||
1037 | * @param tr | ||
1038 | * Talk request to cancel. | ||
1039 | */ | ||
1040 | void | ||
1041 | GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr); | ||
1042 | |||
1043 | |||
1044 | /** | ||
1045 | * Disconnect from a place. | ||
1046 | * | ||
1047 | * Invalidates guest handle. | ||
1048 | * | ||
1049 | * @param gst | ||
1050 | * The guest to disconnect. | ||
1051 | * @param disconnect_cb | ||
1052 | * Function called after disconnected from the service. | ||
1053 | * @param cls | ||
1054 | * Closure for @a disconnect_cb. | ||
1055 | */ | ||
1056 | void | ||
1057 | GNUNET_SOCIAL_guest_disconnect (struct GNUNET_SOCIAL_Guest *gst, | ||
1058 | GNUNET_ContinuationCallback disconnect_cb, | ||
1059 | void *cls); | ||
1060 | |||
1061 | |||
1062 | /** | ||
1063 | * Leave a place temporarily or permanently. | ||
1064 | * | ||
1065 | * Notifies the owner of the place about leaving, and destroys the place handle. | ||
1066 | * | ||
1067 | * @param place | ||
1068 | * Place to leave. | ||
1069 | * @param env | ||
1070 | * Optional environment for the leave message if @a keep_active | ||
1071 | * is #GNUNET_NO. NULL if not needed. | ||
1072 | * @param disconnect_cb | ||
1073 | * Called upon disconnecting from the social service. | ||
1074 | */ | ||
1075 | void | ||
1076 | GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Guest *gst, | ||
1077 | struct GNUNET_PSYC_Environment *env, | ||
1078 | GNUNET_ContinuationCallback disconnect_cb, | ||
1079 | void *leave_cls); | ||
1080 | |||
1081 | |||
1082 | /** | ||
1083 | * Obtain handle for a place entered as guest. | ||
1084 | * | ||
1085 | * The returned handle can be used to access the place API. | ||
1086 | * | ||
1087 | * @param guest Handle for the guest. | ||
1088 | * | ||
1089 | * @return Handle for the place, valid as long as @a guest is valid. | ||
1090 | */ | ||
1091 | struct GNUNET_SOCIAL_Place * | ||
1092 | GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Guest *guest); | ||
1093 | |||
1094 | |||
1095 | /** | ||
1096 | * A history request. | ||
1097 | */ | ||
1098 | struct GNUNET_SOCIAL_HistoryRequest; | ||
1099 | |||
1100 | |||
1101 | /** | ||
1102 | * Get the public key of a place. | ||
1103 | * | ||
1104 | * @param plc | ||
1105 | * Place. | ||
1106 | * | ||
1107 | * @return Public key of the place. | ||
1108 | */ | ||
1109 | const struct GNUNET_CRYPTO_EddsaPublicKey * | ||
1110 | GNUNET_SOCIAL_place_get_pub_key (const struct GNUNET_SOCIAL_Place *plc); | ||
1111 | |||
1112 | |||
1113 | /** | ||
1114 | * Set message processing @a flags for a @a method_prefix. | ||
1115 | * | ||
1116 | * @param plc | ||
1117 | * Place. | ||
1118 | * @param method_prefix | ||
1119 | * Method prefix @a flags apply to. | ||
1120 | * @param flags | ||
1121 | * The flags that apply to a matching @a method_prefix. | ||
1122 | */ | ||
1123 | void | ||
1124 | GNUNET_SOCIAL_place_msg_proc_set (struct GNUNET_SOCIAL_Place *plc, | ||
1125 | const char *method_prefix, | ||
1126 | enum GNUNET_SOCIAL_MsgProcFlags flags); | ||
1127 | |||
1128 | /** | ||
1129 | * Clear all message processing flags previously set for this place. | ||
1130 | */ | ||
1131 | void | ||
1132 | GNUNET_SOCIAL_place_msg_proc_clear (struct GNUNET_SOCIAL_Place *plc); | ||
1133 | |||
1134 | |||
1135 | /** | ||
1136 | * Learn about the history of a place. | ||
1137 | * | ||
1138 | * Messages are returned through the @a slicer function | ||
1139 | * and have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set. | ||
1140 | * | ||
1141 | * @param place | ||
1142 | * Place we want to learn more about. | ||
1143 | * @param start_message_id | ||
1144 | * First historic message we are interested in. | ||
1145 | * @param end_message_id | ||
1146 | * Last historic message we are interested in (inclusive). | ||
1147 | * @param method_prefix | ||
1148 | * Only retrieve messages with this method prefix. | ||
1149 | * @param flags | ||
1150 | * OR'ed GNUNET_PSYC_HistoryReplayFlags | ||
1151 | * @param slicer | ||
1152 | * Slicer to use for retrieved messages. | ||
1153 | * Can be the same as the slicer of the place. | ||
1154 | * @param result_cb | ||
1155 | * Function called after all messages retrieved. | ||
1156 | * NULL if not needed. | ||
1157 | * @param cls Closure for @a result_cb. | ||
1158 | */ | ||
1159 | struct GNUNET_SOCIAL_HistoryRequest * | ||
1160 | GNUNET_SOCIAL_place_history_replay (struct GNUNET_SOCIAL_Place *plc, | ||
1161 | uint64_t start_message_id, | ||
1162 | uint64_t end_message_id, | ||
1163 | const char *method_prefix, | ||
1164 | uint32_t flags, | ||
1165 | struct GNUNET_PSYC_Slicer *slicer, | ||
1166 | GNUNET_ResultCallback result_cb, | ||
1167 | void *cls); | ||
1168 | |||
1169 | |||
1170 | /** | ||
1171 | * Learn about the history of a place. | ||
1172 | * | ||
1173 | * Sends messages through the slicer function of the place where | ||
1174 | * start_message_id <= message_id <= end_message_id. | ||
1175 | * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set. | ||
1176 | * | ||
1177 | * To get the latest message, use 0 for both the start and end message ID. | ||
1178 | * | ||
1179 | * @param place | ||
1180 | * Place we want to learn more about. | ||
1181 | * @param message_limit | ||
1182 | * Maximum number of historic messages we are interested in. | ||
1183 | * @param result_cb | ||
1184 | * Function called after all messages retrieved. | ||
1185 | * NULL if not needed. | ||
1186 | * @param cls Closure for @a result_cb. | ||
1187 | */ | ||
1188 | struct GNUNET_SOCIAL_HistoryRequest * | ||
1189 | GNUNET_SOCIAL_place_history_replay_latest (struct GNUNET_SOCIAL_Place *plc, | ||
1190 | uint64_t message_limit, | ||
1191 | const char *method_prefix, | ||
1192 | uint32_t flags, | ||
1193 | struct GNUNET_PSYC_Slicer *slicer, | ||
1194 | GNUNET_ResultCallback result_cb, | ||
1195 | void *cls); | ||
1196 | |||
1197 | /** | ||
1198 | * Cancel learning about the history of a place. | ||
1199 | * | ||
1200 | * @param hist | ||
1201 | * History lesson to cancel. | ||
1202 | */ | ||
1203 | void | ||
1204 | GNUNET_SOCIAL_place_history_replay_cancel (struct GNUNET_SOCIAL_HistoryRequest *hist); | ||
1205 | |||
1206 | |||
1207 | struct GNUNET_SOCIAL_LookHandle; | ||
1208 | |||
1209 | |||
1210 | /** | ||
1211 | * Look at a particular object in the place. | ||
1212 | * | ||
1213 | * The best matching object is returned (its name might be less specific than | ||
1214 | * what was requested). | ||
1215 | * | ||
1216 | * @param place | ||
1217 | * The place to look the object at. | ||
1218 | * @param full_name | ||
1219 | * Full name of the object. | ||
1220 | * | ||
1221 | * @return NULL if there is no such object at this place. | ||
1222 | */ | ||
1223 | struct GNUNET_SOCIAL_LookHandle * | ||
1224 | GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *plc, | ||
1225 | const char *full_name, | ||
1226 | GNUNET_PSYC_StateVarCallback var_cb, | ||
1227 | GNUNET_ResultCallback result_cb, | ||
1228 | void *cls); | ||
1229 | |||
1230 | /** | ||
1231 | * Look for objects in the place with a matching name prefix. | ||
1232 | * | ||
1233 | * @param place | ||
1234 | * The place to look its objects at. | ||
1235 | * @param name_prefix | ||
1236 | * Look at objects with names beginning with this value. | ||
1237 | * @param var_cb | ||
1238 | * Function to call for each object found. | ||
1239 | * @param cls | ||
1240 | * Closure for callback function. | ||
1241 | * | ||
1242 | * @return Handle that can be used to stop looking at objects. | ||
1243 | */ | ||
1244 | struct GNUNET_SOCIAL_LookHandle * | ||
1245 | GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *plc, | ||
1246 | const char *name_prefix, | ||
1247 | GNUNET_PSYC_StateVarCallback var_cb, | ||
1248 | GNUNET_ResultCallback result_cb, | ||
1249 | void *cls); | ||
1250 | |||
1251 | |||
1252 | /** | ||
1253 | * Stop looking at objects. | ||
1254 | * | ||
1255 | * @param lh Look handle to stop. | ||
1256 | */ | ||
1257 | void | ||
1258 | GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh); | ||
1259 | |||
1260 | |||
1261 | /** | ||
1262 | * Advertise a @e place in the GNS zone of @a ego. | ||
1263 | * | ||
1264 | * @param app | ||
1265 | * Application handle. | ||
1266 | * @param ego | ||
1267 | * Ego. | ||
1268 | * @param place_pub_key | ||
1269 | * Public key of place to add. | ||
1270 | * @param name | ||
1271 | * The name for the PLACE record to put in the zone. | ||
1272 | * @param password | ||
1273 | * Password used to encrypt the record or NULL to keep it cleartext. | ||
1274 | * @param relay_count | ||
1275 | * Number of elements in the @a relays array. | ||
1276 | * @param relays | ||
1277 | * List of relays to put in the PLACE record to advertise | ||
1278 | * as entry points to the place in addition to the origin. | ||
1279 | * @param expiration_time | ||
1280 | * Expiration time of the record, use 0 to remove the record. | ||
1281 | * @param result_cb | ||
1282 | * Function called with the result of the operation. | ||
1283 | * @param result_cls | ||
1284 | * Closure for @a result_cb | ||
1285 | * | ||
1286 | * @return #GNUNET_OK if the request was sent, | ||
1287 | * #GNUNET_SYSERR on error, e.g. the name/password is too long. | ||
1288 | */ | ||
1289 | int | ||
1290 | GNUNET_SOCIAL_zone_add_place (const struct GNUNET_SOCIAL_App *app, | ||
1291 | const struct GNUNET_SOCIAL_Ego *ego, | ||
1292 | const char *name, | ||
1293 | const char *password, | ||
1294 | const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, | ||
1295 | const struct GNUNET_PeerIdentity *origin, | ||
1296 | uint32_t relay_count, | ||
1297 | const struct GNUNET_PeerIdentity *relays, | ||
1298 | struct GNUNET_TIME_Absolute expiration_time, | ||
1299 | GNUNET_ResultCallback result_cb, | ||
1300 | void *result_cls); | ||
1301 | |||
1302 | |||
1303 | /** | ||
1304 | * Add public key to the GNS zone of the @e ego. | ||
1305 | * | ||
1306 | * @param cfg | ||
1307 | * Configuration. | ||
1308 | * @param ego | ||
1309 | * Ego. | ||
1310 | * @param name | ||
1311 | * The name for the PKEY record to put in the zone. | ||
1312 | * @param nym_pub_key | ||
1313 | * Public key of nym to add. | ||
1314 | * @param expiration_time | ||
1315 | * Expiration time of the record, use 0 to remove the record. | ||
1316 | * @param result_cb | ||
1317 | * Function called with the result of the operation. | ||
1318 | * @param result_cls | ||
1319 | * Closure for @a result_cb | ||
1320 | * | ||
1321 | * @return #GNUNET_OK if the request was sent, | ||
1322 | * #GNUNET_SYSERR on error, e.g. the name is too long. | ||
1323 | */ | ||
1324 | int | ||
1325 | GNUNET_SOCIAL_zone_add_nym (const struct GNUNET_SOCIAL_App *app, | ||
1326 | const struct GNUNET_SOCIAL_Ego *ego, | ||
1327 | const char *name, | ||
1328 | const struct GNUNET_CRYPTO_EcdsaPublicKey *nym_pub_key, | ||
1329 | struct GNUNET_TIME_Absolute expiration_time, | ||
1330 | GNUNET_ResultCallback result_cb, | ||
1331 | void *result_cls); | ||
1332 | |||
1333 | |||
1334 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
1335 | { | ||
1336 | #endif | ||
1337 | #ifdef __cplusplus | ||
1338 | } | ||
1339 | #endif | ||
1340 | |||
1341 | /* ifndef GNUNET_SOCIAL_SERVICE_H */ | ||
1342 | #endif | ||
1343 | |||
1344 | /** @} */ /* end of group */ | ||