diff options
Diffstat (limited to 'src/include/gnunet_multicast_service.h')
-rw-r--r-- | src/include/gnunet_multicast_service.h | 925 |
1 files changed, 0 insertions, 925 deletions
diff --git a/src/include/gnunet_multicast_service.h b/src/include/gnunet_multicast_service.h deleted file mode 100644 index 58fca0b2e..000000000 --- a/src/include/gnunet_multicast_service.h +++ /dev/null | |||
@@ -1,925 +0,0 @@ | |||
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 */ | ||