diff options
author | Gabor X Toth <*@tg-x.net> | 2015-09-26 17:10:03 +0000 |
---|---|---|
committer | Gabor X Toth <*@tg-x.net> | 2015-09-26 17:10:03 +0000 |
commit | e990039b4ddf89d37a8771dc5aca791e52df45ed (patch) | |
tree | 171afe7526839c62423ab6efc023ea3b53d48073 /src/include/gnunet_multicast_service.h | |
parent | 5a042e00e06de726a21d9db05ddeb2ac16ca7c0c (diff) | |
download | gnunet-e990039b4ddf89d37a8771dc5aca791e52df45ed.tar.gz gnunet-e990039b4ddf89d37a8771dc5aca791e52df45ed.zip |
multicast: doc formatting
Diffstat (limited to 'src/include/gnunet_multicast_service.h')
-rw-r--r-- | src/include/gnunet_multicast_service.h | 324 |
1 files changed, 215 insertions, 109 deletions
diff --git a/src/include/gnunet_multicast_service.h b/src/include/gnunet_multicast_service.h index c618f3dd5..bc4d0f970 100644 --- a/src/include/gnunet_multicast_service.h +++ b/src/include/gnunet_multicast_service.h | |||
@@ -242,19 +242,24 @@ struct GNUNET_MULTICAST_JoinHandle; | |||
242 | * Must be called once and only once in response to an invocation of the | 242 | * Must be called once and only once in response to an invocation of the |
243 | * #GNUNET_MULTICAST_JoinRequestCallback. | 243 | * #GNUNET_MULTICAST_JoinRequestCallback. |
244 | * | 244 | * |
245 | * @param jh Join request handle. | 245 | * @param jh |
246 | * @param is_admitted #GNUNET_YES if the join is approved, | 246 | * Join request handle. |
247 | * #GNUNET_NO if it is disapproved, | 247 | * @param is_admitted |
248 | * #GNUNET_SYSERR if we cannot answer the request. | 248 | * #GNUNET_YES if the join is approved, |
249 | * @param relay_count Number of relays given. | 249 | * #GNUNET_NO if it is disapproved, |
250 | * @param relays Array of suggested peers that might be useful relays to use | 250 | * #GNUNET_SYSERR if we cannot answer the request. |
251 | * @param relay_count | ||
252 | * Number of relays given. | ||
253 | * @param relays | ||
254 | * Array of suggested peers that might be useful relays to use | ||
251 | * when joining the multicast group (essentially a list of peers that | 255 | * when joining the multicast group (essentially a list of peers that |
252 | * are already part of the multicast group and might thus be willing | 256 | * are already part of the multicast group and might thus be willing |
253 | * to help with routing). If empty, only this local peer (which must | 257 | * to help with routing). If empty, only this local peer (which must |
254 | * be the multicast origin) is a good candidate for building the | 258 | * be the multicast origin) is a good candidate for building the |
255 | * multicast tree. Note that it is unnecessary to specify our own | 259 | * multicast tree. Note that it is unnecessary to specify our own |
256 | * peer identity in this array. | 260 | * peer identity in this array. |
257 | * @param join_resp Message to send in response to the joining peer; | 261 | * @param join_resp |
262 | * Message to send in response to the joining peer; | ||
258 | * can also be used to redirect the peer to a different group at the | 263 | * can also be used to redirect the peer to a different group at the |
259 | * application layer; this response is to be transmitted to the | 264 | * application layer; this response is to be transmitted to the |
260 | * peer that issued the request even if admission is denied. | 265 | * peer that issued the request even if admission is denied. |
@@ -273,10 +278,14 @@ GNUNET_MULTICAST_join_decision (struct GNUNET_MULTICAST_JoinHandle *jh, | |||
273 | * Implementations of this function must call GNUNET_MULTICAST_join_decision() | 278 | * Implementations of this function must call GNUNET_MULTICAST_join_decision() |
274 | * with the decision. | 279 | * with the decision. |
275 | * | 280 | * |
276 | * @param cls Closure. | 281 | * @param cls |
277 | * @param member_key Public key of the member requesting join. | 282 | * Closure. |
278 | * @param join_msg Application-dependent join message from the new member. | 283 | * @param member_key |
279 | * @param jh Join handle to pass to GNUNET_MULTICAST_join_decison(). | 284 | * Public key of the member requesting join. |
285 | * @param join_msg | ||
286 | * Application-dependent join message from the new member. | ||
287 | * @param jh | ||
288 | * Join handle to pass to GNUNET_MULTICAST_join_decison(). | ||
280 | */ | 289 | */ |
281 | typedef void | 290 | typedef void |
282 | (*GNUNET_MULTICAST_JoinRequestCallback) (void *cls, | 291 | (*GNUNET_MULTICAST_JoinRequestCallback) (void *cls, |
@@ -292,14 +301,20 @@ typedef void | |||
292 | * the client and the multicast member handle returned by | 301 | * the client and the multicast member handle returned by |
293 | * GNUNET_MULTICAST_member_join() is invalidated. | 302 | * GNUNET_MULTICAST_member_join() is invalidated. |
294 | * | 303 | * |
295 | * @param cls Closure. | 304 | * @param cls |
296 | * @param is_admitted #GNUNET_YES or #GNUNET_NO or #GNUNET_SYSERR | 305 | * Closure. |
297 | * @param peer The peer we are connected to and the join decision is from. | 306 | * @param is_admitted |
298 | * @param relay_count Number of peers in the @a relays array. | 307 | * #GNUNET_YES or #GNUNET_NO or #GNUNET_SYSERR |
299 | * @param relays Peer identities of members of the group, which serve as relays | 308 | * @param peer |
309 | * The peer we are connected to and the join decision is from. | ||
310 | * @param relay_count | ||
311 | * Number of peers in the @a relays array. | ||
312 | * @param relays | ||
313 | * Peer identities of members of the group, which serve as relays | ||
300 | * and can be used to join the group at. If empty, only the origin can | 314 | * and can be used to join the group at. If empty, only the origin can |
301 | * be used to connect to the group. | 315 | * be used to connect to the group. |
302 | * @param join_msg Application-dependent join message from the origin. | 316 | * @param join_msg |
317 | * Application-dependent join message from the origin. | ||
303 | */ | 318 | */ |
304 | typedef void | 319 | typedef void |
305 | (*GNUNET_MULTICAST_JoinDecisionCallback) (void *cls, | 320 | (*GNUNET_MULTICAST_JoinDecisionCallback) (void *cls, |
@@ -319,8 +334,10 @@ struct GNUNET_MULTICAST_MembershipTestHandle; | |||
319 | /** | 334 | /** |
320 | * Call informing multicast about the decision taken for a membership test. | 335 | * Call informing multicast about the decision taken for a membership test. |
321 | * | 336 | * |
322 | * @param mth Handle that was given for the query. | 337 | * @param mth |
323 | * @param result #GNUNET_YES if peer was a member, #GNUNET_NO if peer was not a member, | 338 | * Handle that was given for the query. |
339 | * @param result | ||
340 | * #GNUNET_YES if peer was a member, #GNUNET_NO if peer was not a member, | ||
324 | * #GNUNET_SYSERR if we cannot answer the membership test. | 341 | * #GNUNET_SYSERR if we cannot answer the membership test. |
325 | */ | 342 | */ |
326 | void | 343 | void |
@@ -334,13 +351,18 @@ GNUNET_MULTICAST_membership_test_result (struct GNUNET_MULTICAST_MembershipTestH | |||
334 | * It is called when a replay request is received to determine if the requested | 351 | * It is called when a replay request is received to determine if the requested |
335 | * message can be replayed. | 352 | * message can be replayed. |
336 | * | 353 | * |
337 | * @param cls Closure. | 354 | * @param cls |
338 | * @param member_key Identity of the member that we want to test. | 355 | * Closure. |
339 | * @param message_id Message ID for which to perform the test. | 356 | * @param member_key |
340 | * @param group_generation Group generation of the message. It has relevance if | 357 | * Identity of the member that we want to test. |
358 | * @param message_id | ||
359 | * Message ID for which to perform the test. | ||
360 | * @param group_generation | ||
361 | * Group generation of the message. It has relevance if | ||
341 | * the message consists of multiple fragments with different group | 362 | * the message consists of multiple fragments with different group |
342 | * generations. | 363 | * generations. |
343 | * @param mth Handle to give to GNUNET_MULTICAST_membership_test_answer(). | 364 | * @param mth |
365 | * Handle to give to GNUNET_MULTICAST_membership_test_answer(). | ||
344 | */ | 366 | */ |
345 | typedef void | 367 | typedef void |
346 | (*GNUNET_MULTICAST_MembershipTestCallback) (void *cls, | 368 | (*GNUNET_MULTICAST_MembershipTestCallback) (void *cls, |
@@ -361,10 +383,14 @@ typedef void | |||
361 | * GNUNET_MULTICAST_member_to_origin_cancel() are not clear here. Maybe we | 383 | * GNUNET_MULTICAST_member_to_origin_cancel() are not clear here. Maybe we |
362 | * should do something with the flags in this case? | 384 | * should do something with the flags in this case? |
363 | * | 385 | * |
364 | * @param cls Closure (set from GNUNET_MULTICAST_origin_start). | 386 | * @param cls |
365 | * @param sender Identity of the sender. | 387 | * Closure (set from GNUNET_MULTICAST_origin_start). |
366 | * @param req Request to the origin. | 388 | * @param sender |
367 | * @param flags Flags for the request. | 389 | * Identity of the sender. |
390 | * @param req | ||
391 | * Request to the origin. | ||
392 | * @param flags | ||
393 | * Flags for the request. | ||
368 | */ | 394 | */ |
369 | typedef void | 395 | typedef void |
370 | (*GNUNET_MULTICAST_RequestCallback) (void *cls, | 396 | (*GNUNET_MULTICAST_RequestCallback) (void *cls, |
@@ -385,8 +411,10 @@ typedef void | |||
385 | * So the semantics from the receiver side of | 411 | * So the semantics from the receiver side of |
386 | * GNUNET_MULTICAST_origin_to_all_cancel() are not clear here. | 412 | * GNUNET_MULTICAST_origin_to_all_cancel() are not clear here. |
387 | * | 413 | * |
388 | * @param cls Closure (set from GNUNET_MULTICAST_member_join()) | 414 | * @param cls |
389 | * @param msg Message from the origin, NULL if the origin shut down | 415 | * Closure (set from GNUNET_MULTICAST_member_join()) |
416 | * @param msg | ||
417 | * Message from the origin, NULL if the origin shut down | ||
390 | * (or we were kicked out, and we should thus call | 418 | * (or we were kicked out, and we should thus call |
391 | * GNUNET_MULTICAST_member_part() next) | 419 | * GNUNET_MULTICAST_member_part() next) |
392 | */ | 420 | */ |
@@ -400,7 +428,8 @@ typedef void | |||
400 | * | 428 | * |
401 | * @see GNUNET_MULTICAST_replay_fragment() | 429 | * @see GNUNET_MULTICAST_replay_fragment() |
402 | * | 430 | * |
403 | * @param result Result of the operation. | 431 | * @param result |
432 | * Result of the operation. | ||
404 | */ | 433 | */ |
405 | typedef void | 434 | typedef void |
406 | (*GNUNET_MULTICAST_ResultCallback) (void *cls, | 435 | (*GNUNET_MULTICAST_ResultCallback) (void *cls, |
@@ -421,12 +450,17 @@ struct GNUNET_MULTICAST_ReplayHandle; | |||
421 | * (with a message or an error); however, if the origin is destroyed or the | 450 | * (with a message or an error); however, if the origin is destroyed or the |
422 | * group is left, the replay handle must no longer be used. | 451 | * group is left, the replay handle must no longer be used. |
423 | * | 452 | * |
424 | * @param cls Closure (set from GNUNET_MULTICAST_origin_start() | 453 | * @param cls |
454 | * Closure (set from GNUNET_MULTICAST_origin_start() | ||
425 | * or GNUNET_MULTICAST_member_join()). | 455 | * or GNUNET_MULTICAST_member_join()). |
426 | * @param member_key The member requesting replay. | 456 | * @param member_key |
427 | * @param fragment_id Which message fragment should be replayed. | 457 | * The member requesting replay. |
428 | * @param flags Flags for the replay. | 458 | * @param fragment_id |
429 | * @param rh Handle to pass to message transmit function. | 459 | * Which message fragment should be replayed. |
460 | * @param flags | ||
461 | * Flags for the replay. | ||
462 | * @param rh | ||
463 | * Handle to pass to message transmit function. | ||
430 | */ | 464 | */ |
431 | typedef void | 465 | typedef void |
432 | (*GNUNET_MULTICAST_ReplayFragmentCallback) (void *cls, | 466 | (*GNUNET_MULTICAST_ReplayFragmentCallback) (void *cls, |
@@ -443,13 +477,19 @@ typedef void | |||
443 | * (with a message or an error); however, if the origin is destroyed or the | 477 | * (with a message or an error); however, if the origin is destroyed or the |
444 | * group is left, the replay handle must no longer be used. | 478 | * group is left, the replay handle must no longer be used. |
445 | * | 479 | * |
446 | * @param cls Closure (set from GNUNET_MULTICAST_origin_start() | 480 | * @param cls |
481 | * Closure (set from GNUNET_MULTICAST_origin_start() | ||
447 | * or GNUNET_MULTICAST_member_join()). | 482 | * or GNUNET_MULTICAST_member_join()). |
448 | * @param member_key The member requesting replay. | 483 | * @param member_key |
449 | * @param message_id Which message should be replayed. | 484 | * The member requesting replay. |
450 | * @param fragment_offset Offset of the fragment within of @a message_id to be replayed. | 485 | * @param message_id |
451 | * @param flags Flags for the replay. | 486 | * Which message should be replayed. |
452 | * @param rh Handle to pass to message transmit function. | 487 | * @param fragment_offset |
488 | * Offset of the fragment within of @a message_id to be replayed. | ||
489 | * @param flags | ||
490 | * Flags for the replay. | ||
491 | * @param rh | ||
492 | * Handle to pass to message transmit function. | ||
453 | */ | 493 | */ |
454 | typedef void | 494 | typedef void |
455 | (*GNUNET_MULTICAST_ReplayMessageCallback) (void *cls, | 495 | (*GNUNET_MULTICAST_ReplayMessageCallback) (void *cls, |
@@ -505,9 +545,13 @@ enum GNUNET_MULTICAST_ReplayErrorCode | |||
505 | /** | 545 | /** |
506 | * Replay a message fragment for the multicast group. | 546 | * Replay a message fragment for the multicast group. |
507 | * | 547 | * |
508 | * @param rh Replay handle identifying which replay operation was requested. | 548 | * @param rh |
509 | * @param msg Replayed message fragment, NULL if unknown/error. | 549 | * Replay handle identifying which replay operation was requested. |
510 | * @param ec Error code. | 550 | * @param msg |
551 | * Replayed message fragment, NULL if not found / an error occurred. | ||
552 | * @param ec | ||
553 | * Error code. See enum GNUNET_MULTICAST_ReplayErrorCode | ||
554 | * If not #GNUNET_MULTICAST_REC_OK, the replay handle is invalidated. | ||
511 | */ | 555 | */ |
512 | void | 556 | void |
513 | GNUNET_MULTICAST_replay_response (struct GNUNET_MULTICAST_ReplayHandle *rh, | 557 | GNUNET_MULTICAST_replay_response (struct GNUNET_MULTICAST_ReplayHandle *rh, |
@@ -540,9 +584,12 @@ typedef int | |||
540 | /** | 584 | /** |
541 | * Replay a message for the multicast group. | 585 | * Replay a message for the multicast group. |
542 | * | 586 | * |
543 | * @param rh Replay handle identifying which replay operation was requested. | 587 | * @param rh |
544 | * @param notify Function to call to get the message. | 588 | * Replay handle identifying which replay operation was requested. |
545 | * @param notify_cls Closure for @a notify. | 589 | * @param notify |
590 | * Function to call to get the message. | ||
591 | * @param notify_cls | ||
592 | * Closure for @a notify. | ||
546 | */ | 593 | */ |
547 | void | 594 | void |
548 | GNUNET_MULTICAST_replay_response2 (struct GNUNET_MULTICAST_ReplayHandle *rh, | 595 | GNUNET_MULTICAST_replay_response2 (struct GNUNET_MULTICAST_ReplayHandle *rh, |
@@ -562,20 +609,31 @@ GNUNET_MULTICAST_replay_response2 (struct GNUNET_MULTICAST_ReplayHandle *rh, | |||
562 | * candidate will be given a response. Members in the group can send messages | 609 | * candidate will be given a response. Members in the group can send messages |
563 | * to the origin (one at a time). | 610 | * to the origin (one at a time). |
564 | * | 611 | * |
565 | * @param cfg Configuration to use. | 612 | * @param cfg |
566 | * @param priv_key ECC key that will be used to sign messages for this | 613 | * Configuration to use. |
614 | * @param priv_key | ||
615 | * ECC key that will be used to sign messages for this | ||
567 | * multicast session; public key is used to identify the multicast group; | 616 | * multicast session; public key is used to identify the multicast group; |
568 | * @param max_fragment_id Maximum fragment ID already sent to the group. | 617 | * @param max_fragment_id |
618 | * Maximum fragment ID already sent to the group. | ||
569 | * 0 for a new group. | 619 | * 0 for a new group. |
570 | * @param join_request_cb Function called to approve / disapprove joining of a peer. | 620 | * @param join_request_cb |
571 | * @param member_test_cb Function multicast can use to test group membership. | 621 | * Function called to approve / disapprove joining of a peer. |
572 | * @param replay_frag_cb Function that can be called to replay a message fragment. | 622 | * @param member_test_cb |
573 | * @param replay_msg_cb Function that can be called to replay a message. | 623 | * Function multicast can use to test group membership. |
574 | * @param request_cb Function called with message fragments from group members. | 624 | * @param replay_frag_cb |
575 | * @param message_cb Function called with the message fragments sent to the | 625 | * Function that can be called to replay a message fragment. |
626 | * @param replay_msg_cb | ||
627 | * Function that can be called to replay a message. | ||
628 | * @param request_cb | ||
629 | * Function called with message fragments from group members. | ||
630 | * @param message_cb | ||
631 | * Function called with the message fragments sent to the | ||
576 | * network by GNUNET_MULTICAST_origin_to_all(). These message fragments | 632 | * network by GNUNET_MULTICAST_origin_to_all(). These message fragments |
577 | * should be stored for answering replay requests later. | 633 | * should be stored for answering replay requests later. |
578 | * @param cls Closure for the various callbacks that follow. | 634 | * @param cls |
635 | * Closure for the various callbacks that follow. | ||
636 | * | ||
579 | * @return Handle for the origin, NULL on error. | 637 | * @return Handle for the origin, NULL on error. |
580 | */ | 638 | */ |
581 | struct GNUNET_MULTICAST_Origin * | 639 | struct GNUNET_MULTICAST_Origin * |
@@ -597,11 +655,15 @@ GNUNET_MULTICAST_origin_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
597 | * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) | 655 | * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) |
598 | * invalidates the respective transmission handle. | 656 | * invalidates the respective transmission handle. |
599 | * | 657 | * |
600 | * @param cls Closure. | 658 | * @param cls |
601 | * @param[in,out] data_size Initially set to the number of bytes available in | 659 | * Closure. |
660 | * @param[in,out] data_size | ||
661 | * Initially set to the number of bytes available in | ||
602 | * @a data, should be set to the number of bytes written to data. | 662 | * @a data, should be set to the number of bytes written to data. |
603 | * @param[out] data Where to write the body of the message to give to the | 663 | * @param[out] data |
664 | * Where to write the body of the message to give to the | ||
604 | * method. The function must copy at most @a data_size bytes to @a data. | 665 | * method. The function must copy at most @a data_size bytes to @a data. |
666 | * | ||
605 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) | 667 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) |
606 | * #GNUNET_NO on success, if more data is to be transmitted later. | 668 | * #GNUNET_NO on success, if more data is to be transmitted later. |
607 | * Should be used if @a data_size was not big enough to take all the | 669 | * Should be used if @a data_size was not big enough to take all the |
@@ -625,12 +687,18 @@ struct GNUNET_MULTICAST_OriginTransmitHandle; | |||
625 | /** | 687 | /** |
626 | * Send a message to the multicast group. | 688 | * Send a message to the multicast group. |
627 | * | 689 | * |
628 | * @param origin Handle to the multicast group. | 690 | * @param origin |
629 | * @param message_id Application layer ID for the message. Opaque to multicast. | 691 | * Handle to the multicast group. |
630 | * @param group_generation Group generation of the message. Documented in | 692 | * @param message_id |
631 | * GNUNET_MULTICAST_MessageHeader. | 693 | * Application layer ID for the message. Opaque to multicast. |
632 | * @param notify Function to call to get the message. | 694 | * @param group_generation |
633 | * @param notify_cls Closure for @a notify. | 695 | * Group generation of the message. Documented in |
696 | * struct GNUNET_MULTICAST_MessageHeader. | ||
697 | * @param notify | ||
698 | * Function to call to get the message. | ||
699 | * @param notify_cls | ||
700 | * Closure for @a notify. | ||
701 | * | ||
634 | * @return NULL on error (i.e. request already pending). | 702 | * @return NULL on error (i.e. request already pending). |
635 | */ | 703 | */ |
636 | struct GNUNET_MULTICAST_OriginTransmitHandle * | 704 | struct GNUNET_MULTICAST_OriginTransmitHandle * |
@@ -683,32 +751,46 @@ GNUNET_MULTICAST_origin_stop (struct GNUNET_MULTICAST_Origin *origin, | |||
683 | * anytime by the multicast service to support relaying messages to other | 751 | * anytime by the multicast service to support relaying messages to other |
684 | * members of the group. | 752 | * members of the group. |
685 | * | 753 | * |
686 | * @param cfg Configuration to use. | 754 | * @param cfg |
687 | * @param group_key ECC public key that identifies the group to join. | 755 | * Configuration to use. |
688 | * @param member_key ECC key that identifies the member and used to sign | 756 | * @param group_key |
689 | * requests sent to the origin. | 757 | * ECC public key that identifies the group to join. |
690 | * @param origin Peer ID of the origin to send unicast requsets to. If NULL, | 758 | * @param member_key |
759 | * ECC key that identifies the member | ||
760 | * and used to sign requests sent to the origin. | ||
761 | * @param origin | ||
762 | * Peer ID of the origin to send unicast requsets to. If NULL, | ||
691 | * unicast requests are sent back via multiple hops on the reverse path | 763 | * unicast requests are sent back via multiple hops on the reverse path |
692 | * of multicast messages. | 764 | * of multicast messages. |
693 | * @param relay_count Number of peers in the @a relays array. | 765 | * @param relay_count |
694 | * @param relays Peer identities of members of the group, which serve as relays | 766 | * Number of peers in the @a relays array. |
695 | * and can be used to join the group at and send the @a join_request to. | 767 | * @param relays |
768 | * Peer identities of members of the group, which serve as relays | ||
769 | * and can be used to join the group at. and send the @a join_request to. | ||
696 | * If empty, the @a join_request is sent directly to the @a origin. | 770 | * If empty, the @a join_request is sent directly to the @a origin. |
697 | * @param join_msg Application-dependent join message to be passed to the | 771 | * @param join_msg |
698 | * @a origin. | 772 | * Application-dependent join message to be passed to the peer @a origin. |
699 | * @param join_request_cb Function called to approve / disapprove joining of a peer. | 773 | * @param join_request_cb |
700 | * @param join_decision_cb Function called to inform about the join decision. | 774 | * Function called to approve / disapprove joining of a peer. |
701 | * @param mem_test_cb Function multicast can use to test group membership. | 775 | * @param join_decision_cb |
702 | * @param replay_frag_cb Function that can be called to replay message fragments | 776 | * Function called to inform about the join decision. |
777 | * @param member_test_cb | ||
778 | * Function multicast can use to test group membership. | ||
779 | * @param replay_frag_cb | ||
780 | * Function that can be called to replay message fragments | ||
703 | * this peer already knows from this group. NULL if this | 781 | * this peer already knows from this group. NULL if this |
704 | * client is unable to support replay. | 782 | * client is unable to support replay. |
705 | * @param replay_msg_cb Function that can be called to replay message fragments | 783 | * @param replay_msg_cb |
784 | * Function that can be called to replay message fragments | ||
706 | * this peer already knows from this group. NULL if this | 785 | * this peer already knows from this group. NULL if this |
707 | * client is unable to support replay. | 786 | * client is unable to support replay. |
708 | * @param message_cb Function to be called for all message fragments we | 787 | * @param message_cb |
788 | * Function to be called for all message fragments we | ||
709 | * receive from the group, excluding those our @a replay_cb | 789 | * receive from the group, excluding those our @a replay_cb |
710 | * already has. | 790 | * already has. |
711 | * @param cls Closure for callbacks. | 791 | * @param cls |
792 | * Closure for callbacks. | ||
793 | * | ||
712 | * @return Handle for the member, NULL on error. | 794 | * @return Handle for the member, NULL on error. |
713 | */ | 795 | */ |
714 | struct GNUNET_MULTICAST_Member * | 796 | struct GNUNET_MULTICAST_Member * |
@@ -739,12 +821,18 @@ struct GNUNET_MULTICAST_MemberReplayHandle; | |||
739 | * Useful if messages below the @e max_known_fragment_id given when joining are | 821 | * Useful if messages below the @e max_known_fragment_id given when joining are |
740 | * needed and not known to the client. | 822 | * needed and not known to the client. |
741 | * | 823 | * |
742 | * @param member Membership handle. | 824 | * @param member |
743 | * @param fragment_id ID of a message fragment that this client would like to | 825 | * Membership handle. |
744 | see replayed. | 826 | * @param fragment_id |
745 | * @param flags Additional flags for the replay request. It is used and defined | 827 | * ID of a message fragment that this client would like to see replayed. |
746 | * by the replay callback. FIXME: which replay callback? FIXME: use enum? | 828 | * @param flags |
747 | * FIXME: why not pass reply cb here? | 829 | * Additional flags for the replay request. |
830 | * It is used and defined by GNUNET_MULTICAST_ReplayFragmentCallback | ||
831 | * @param result_cb | ||
832 | * Function to call when the replayed message fragment arrives. | ||
833 | * @param result_cls | ||
834 | * Closure for @a result_cb. | ||
835 | * | ||
748 | * @return Replay request handle, NULL on error. | 836 | * @return Replay request handle, NULL on error. |
749 | */ | 837 | */ |
750 | struct GNUNET_MULTICAST_MemberReplayHandle * | 838 | struct GNUNET_MULTICAST_MemberReplayHandle * |
@@ -761,13 +849,20 @@ GNUNET_MULTICAST_member_replay_fragment (struct GNUNET_MULTICAST_Member *member, | |||
761 | * Useful if messages below the @e max_known_fragment_id given when joining are | 849 | * Useful if messages below the @e max_known_fragment_id given when joining are |
762 | * needed and not known to the client. | 850 | * needed and not known to the client. |
763 | * | 851 | * |
764 | * @param member Membership handle. | 852 | * @param member |
765 | * @param message_id ID of the message this client would like to see replayed. | 853 | * Membership handle. |
766 | * @param fragment_offset Offset of the fragment within the message to replay. | 854 | * @param message_id |
767 | * @param flags Additional flags for the replay request. It is used & defined | 855 | * ID of the message this client would like to see replayed. |
768 | * by the replay callback. | 856 | * @param fragment_offset |
769 | * @param result_cb Function to be called for the replayed message. | 857 | * Offset of the fragment within the message to replay. |
770 | * @param result_cb_cls Closure for @a result_cb. | 858 | * @param flags |
859 | * Additional flags for the replay request. | ||
860 | * It is used & defined by GNUNET_MULTICAST_ReplayMessageCallback | ||
861 | * @param result_cb | ||
862 | * Function to call for each replayed message fragment. | ||
863 | * @param result_cls | ||
864 | * Closure for @a result_cb. | ||
865 | * | ||
771 | * @return Replay request handle, NULL on error. | 866 | * @return Replay request handle, NULL on error. |
772 | */ | 867 | */ |
773 | struct GNUNET_MULTICAST_MemberReplayHandle * | 868 | struct GNUNET_MULTICAST_MemberReplayHandle * |
@@ -782,7 +877,8 @@ GNUNET_MULTICAST_member_replay_message (struct GNUNET_MULTICAST_Member *member, | |||
782 | /** | 877 | /** |
783 | * Cancel a replay request. | 878 | * Cancel a replay request. |
784 | * | 879 | * |
785 | * @param rh Request to cancel. | 880 | * @param rh |
881 | * Request to cancel. | ||
786 | */ | 882 | */ |
787 | void | 883 | void |
788 | GNUNET_MULTICAST_member_replay_cancel (struct GNUNET_MULTICAST_MemberReplayHandle *rh); | 884 | GNUNET_MULTICAST_member_replay_cancel (struct GNUNET_MULTICAST_MemberReplayHandle *rh); |
@@ -796,7 +892,8 @@ GNUNET_MULTICAST_member_replay_cancel (struct GNUNET_MULTICAST_MemberReplayHandl | |||
796 | * An application-dependent part message can be transmitted beforehand using | 892 | * An application-dependent part message can be transmitted beforehand using |
797 | * #GNUNET_MULTICAST_member_to_origin()) | 893 | * #GNUNET_MULTICAST_member_to_origin()) |
798 | * | 894 | * |
799 | * @param member Membership handle. | 895 | * @param member |
896 | * Membership handle. | ||
800 | */ | 897 | */ |
801 | void | 898 | void |
802 | GNUNET_MULTICAST_member_part (struct GNUNET_MULTICAST_Member *member, | 899 | GNUNET_MULTICAST_member_part (struct GNUNET_MULTICAST_Member *member, |
@@ -810,11 +907,14 @@ GNUNET_MULTICAST_member_part (struct GNUNET_MULTICAST_Member *member, | |||
810 | * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) | 907 | * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) |
811 | * invalidates the respective transmission handle. | 908 | * invalidates the respective transmission handle. |
812 | * | 909 | * |
813 | * @param cls Closure. | 910 | * @param cls |
814 | * @param[in,out] data_size Initially set to the number of bytes available in | 911 | * Closure. |
912 | * @param[in,out] data_size | ||
913 | * Initially set to the number of bytes available in | ||
815 | * @a data, should be set to the number of bytes written to data. | 914 | * @a data, should be set to the number of bytes written to data. |
816 | * @param[out] data Where to write the body of the message to give to the | 915 | * @param[out] data |
817 | * method. The function must copy at most @a data_size bytes to @a data. | 916 | * Where to write the body of the message to give to the |
917 | * method. The function must copy at most @a data_size bytes to @a data. | ||
818 | * | 918 | * |
819 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) | 919 | * @return #GNUNET_SYSERR on error (fatal, aborts transmission) |
820 | * #GNUNET_NO on success, if more data is to be transmitted later. | 920 | * #GNUNET_NO on success, if more data is to be transmitted later. |
@@ -838,10 +938,14 @@ struct GNUNET_MULTICAST_MemberTransmitHandle; | |||
838 | /** | 938 | /** |
839 | * Send a message to the origin of the multicast group. | 939 | * Send a message to the origin of the multicast group. |
840 | * | 940 | * |
841 | * @param member Membership handle. | 941 | * @param member |
842 | * @param request_id Application layer ID for the request. Opaque to multicast. | 942 | * Membership handle. |
843 | * @param notify Callback to call to get the message. | 943 | * @param request_id |
844 | * @param notify_cls Closure for @a notify. | 944 | * Application layer ID for the request. Opaque to multicast. |
945 | * @param notify | ||
946 | * Callback to call to get the message. | ||
947 | * @param notify_cls | ||
948 | * Closure for @a notify. | ||
845 | * | 949 | * |
846 | * @return Handle to cancel request, NULL on error (i.e. request already pending). | 950 | * @return Handle to cancel request, NULL on error (i.e. request already pending). |
847 | */ | 951 | */ |
@@ -855,7 +959,8 @@ GNUNET_MULTICAST_member_to_origin (struct GNUNET_MULTICAST_Member *member, | |||
855 | /** | 959 | /** |
856 | * Resume message transmission to origin. | 960 | * Resume message transmission to origin. |
857 | * | 961 | * |
858 | * @param th Transmission to cancel. | 962 | * @param th |
963 | * Transmission to cancel. | ||
859 | */ | 964 | */ |
860 | void | 965 | void |
861 | GNUNET_MULTICAST_member_to_origin_resume (struct GNUNET_MULTICAST_MemberTransmitHandle *th); | 966 | GNUNET_MULTICAST_member_to_origin_resume (struct GNUNET_MULTICAST_MemberTransmitHandle *th); |
@@ -864,7 +969,8 @@ GNUNET_MULTICAST_member_to_origin_resume (struct GNUNET_MULTICAST_MemberTransmit | |||
864 | /** | 969 | /** |
865 | * Cancel request for message transmission to origin. | 970 | * Cancel request for message transmission to origin. |
866 | * | 971 | * |
867 | * @param th Transmission to cancel. | 972 | * @param th |
973 | * Transmission to cancel. | ||
868 | */ | 974 | */ |
869 | void | 975 | void |
870 | GNUNET_MULTICAST_member_to_origin_cancel (struct GNUNET_MULTICAST_MemberTransmitHandle *th); | 976 | GNUNET_MULTICAST_member_to_origin_cancel (struct GNUNET_MULTICAST_MemberTransmitHandle *th); |