diff options
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/gnunet_multicast_service.h | 137 |
1 files changed, 107 insertions, 30 deletions
diff --git a/src/include/gnunet_multicast_service.h b/src/include/gnunet_multicast_service.h index 66b17c6e3..f1c4813a4 100644 --- a/src/include/gnunet_multicast_service.h +++ b/src/include/gnunet_multicast_service.h | |||
@@ -121,14 +121,6 @@ struct GNUNET_MULTICAST_MessageHeader | |||
121 | uint64_t fragment_id GNUNET_PACKED; | 121 | uint64_t fragment_id GNUNET_PACKED; |
122 | 122 | ||
123 | /** | 123 | /** |
124 | * Number of fragments before the current one that has the same @a message_id. | ||
125 | * | ||
126 | * 0 for the first fragment of a message. | ||
127 | * This allows replaying a message with all of its fragments. | ||
128 | */ | ||
129 | uint64_t fragment_delta GNUNET_PACKED; | ||
130 | |||
131 | /** | ||
132 | * Byte offset of this @e fragment of the @e message. | 124 | * Byte offset of this @e fragment of the @e message. |
133 | */ | 125 | */ |
134 | uint64_t fragment_offset GNUNET_PACKED; | 126 | uint64_t fragment_offset GNUNET_PACKED; |
@@ -398,7 +390,19 @@ typedef void | |||
398 | */ | 390 | */ |
399 | typedef void | 391 | typedef void |
400 | (*GNUNET_MULTICAST_MessageCallback) (void *cls, | 392 | (*GNUNET_MULTICAST_MessageCallback) (void *cls, |
401 | const struct GNUNET_MULTICAST_MessageHeader *msg); | 393 | const struct GNUNET_MessageHeader *msg); |
394 | |||
395 | |||
396 | /** | ||
397 | * Function called with the result of an asynchronous operation. | ||
398 | * | ||
399 | * @see GNUNET_MULTICAST_replay_fragment() | ||
400 | * | ||
401 | * @param result Result of the operation. | ||
402 | */ | ||
403 | typedef void | ||
404 | (*GNUNET_MULTICAST_ResultCallback) (void *cls, | ||
405 | int result); | ||
402 | 406 | ||
403 | 407 | ||
404 | /** | 408 | /** |
@@ -417,17 +421,41 @@ struct GNUNET_MULTICAST_ReplayHandle; | |||
417 | * | 421 | * |
418 | * @param cls Closure (set from GNUNET_MULTICAST_origin_start() | 422 | * @param cls Closure (set from GNUNET_MULTICAST_origin_start() |
419 | * or GNUNET_MULTICAST_member_join()). | 423 | * or GNUNET_MULTICAST_member_join()). |
424 | * @param member_key The member requesting replay. | ||
420 | * @param fragment_id Which message fragment should be replayed. | 425 | * @param fragment_id Which message fragment should be replayed. |
426 | * @param flags Flags for the replay. | ||
427 | * @param rh Handle to pass to message transmit function. | ||
428 | */ | ||
429 | typedef void | ||
430 | (*GNUNET_MULTICAST_ReplayFragmentCallback) (void *cls, | ||
431 | const struct GNUNET_CRYPTO_EccPublicKey *member_key, | ||
432 | uint64_t fragment_id, | ||
433 | uint64_t flags, | ||
434 | struct GNUNET_MULTICAST_ReplayHandle *rh); | ||
435 | |||
436 | /** | ||
437 | * Functions with this signature are called whenever the multicast service needs | ||
438 | * a message to be replayed. | ||
439 | * | ||
440 | * Implementations of this function MUST call GNUNET_MULTICAST_replay() ONCE | ||
441 | * (with a message or an error); however, if the origin is destroyed or the | ||
442 | * group is left, the replay handle must no longer be used. | ||
443 | * | ||
444 | * @param cls Closure (set from GNUNET_MULTICAST_origin_start() | ||
445 | * or GNUNET_MULTICAST_member_join()). | ||
446 | * @param member_key The member requesting replay. | ||
421 | * @param message_id Which message should be replayed. | 447 | * @param message_id Which message should be replayed. |
448 | * @param fragment_offset Offset of the fragment within of @a message_id to be replayed. | ||
422 | * @param flags Flags for the replay. | 449 | * @param flags Flags for the replay. |
423 | * @param rh Handle to pass to message transmit function. | 450 | * @param rh Handle to pass to message transmit function. |
424 | */ | 451 | */ |
425 | typedef void | 452 | typedef void |
426 | (*GNUNET_MULTICAST_ReplayCallback) (void *cls, | 453 | (*GNUNET_MULTICAST_ReplayMessageCallback) (void *cls, |
427 | uint64_t fragment_id, | 454 | const struct GNUNET_CRYPTO_EccPublicKey *member_key, |
428 | uint64_t message_id, | 455 | uint64_t message_id, |
429 | uint64_t flags, | 456 | uint64_t fragment_offset, |
430 | struct GNUNET_MULTICAST_ReplayHandle *rh); | 457 | uint64_t flags, |
458 | struct GNUNET_MULTICAST_ReplayHandle *rh); | ||
431 | 459 | ||
432 | 460 | ||
433 | /** | 461 | /** |
@@ -442,31 +470,38 @@ enum GNUNET_MULTICAST_ReplayErrorCode | |||
442 | GNUNET_MULTICAST_REC_OK = 0, | 470 | GNUNET_MULTICAST_REC_OK = 0, |
443 | 471 | ||
444 | /** | 472 | /** |
445 | * Message fragment has been discarded (likely transient message that was too old). | 473 | * Message fragment not found in the message store. |
474 | * | ||
475 | * Either discarded if it is too old, or not arrived yet if this member has | ||
476 | * missed some messages. | ||
446 | */ | 477 | */ |
447 | GNUNET_MULTICAST_REC_TRANSIENT_LOST = 1, | 478 | GNUNET_MULTICAST_REC_NOT_FOUND = 1, |
448 | 479 | ||
449 | /** | 480 | /** |
450 | * Fragment ID counter was larger than the highest counter this | 481 | * Fragment ID counter was larger than the highest counter this |
451 | * replay function has ever encountered; thus it is likely the | 482 | * replay function has ever encountered; thus it is likely the |
452 | * origin never sent it and we're at the HEAD of the multicast | 483 | * origin never sent it and we're at the HEAD of the multicast |
453 | * stream as far as this node is concerned. | 484 | * stream as far as this node is concerned. |
485 | * | ||
486 | * FIXME: needed? | ||
454 | */ | 487 | */ |
455 | GNUNET_MULTICAST_REC_PAST_HEAD = 2, | 488 | GNUNET_MULTICAST_REC_PAST_HEAD = 2, |
456 | 489 | ||
457 | /** | 490 | /** |
491 | * Access is denied to the requested fragment, membership test did not pass. | ||
492 | */ | ||
493 | GNUNET_MULTICAST_REC_ACCESS_DENIED = 3, | ||
494 | |||
495 | /** | ||
458 | * Internal error (i.e. database error). Try some other peer. | 496 | * Internal error (i.e. database error). Try some other peer. |
459 | */ | 497 | */ |
460 | GNUNET_MULTICAST_REC_INTERNAL_ERROR = 3 | 498 | GNUNET_MULTICAST_REC_INTERNAL_ERROR = 4 |
461 | 499 | ||
462 | }; | 500 | }; |
463 | 501 | ||
464 | 502 | ||
465 | /** | 503 | /** |
466 | * Replay a message from the multicast group. | 504 | * Replay a message fragment for the multicast group. |
467 | * | ||
468 | * FIXME: use notify callbacks here too (or in a replay2() function), | ||
469 | * to be able to use the replay functionality for state sync as well. | ||
470 | * | 505 | * |
471 | * @param rh Replay handle identifying which replay operation was requested. | 506 | * @param rh Replay handle identifying which replay operation was requested. |
472 | * @param msg Replayed message fragment, NULL if unknown/error. | 507 | * @param msg Replayed message fragment, NULL if unknown/error. |
@@ -474,9 +509,31 @@ enum GNUNET_MULTICAST_ReplayErrorCode | |||
474 | */ | 509 | */ |
475 | void | 510 | void |
476 | GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh, | 511 | GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh, |
477 | const struct GNUNET_MULTICAST_MessageHeader *msg, | 512 | const struct GNUNET_MessageHeader *msg, |
478 | enum GNUNET_MULTICAST_ReplayErrorCode ec); | 513 | enum GNUNET_MULTICAST_ReplayErrorCode ec); |
479 | 514 | ||
515 | /** | ||
516 | * Function called to provide data for a transmission for a replay. | ||
517 | * | ||
518 | * @see GNUNET_MULTICAST_replay2() | ||
519 | */ | ||
520 | typedef int | ||
521 | (*GNUNET_MULTICAST_ReplayTransmitNotify)(void *cls, | ||
522 | size_t *data_size, | ||
523 | void *data); | ||
524 | |||
525 | /** | ||
526 | * Replay a message for the multicast group. | ||
527 | * | ||
528 | * @param rh Replay handle identifying which replay operation was requested. | ||
529 | * @param notify Function to call to get the message. | ||
530 | * @param notify_cls Closure for @a notify. | ||
531 | */ | ||
532 | void | ||
533 | GNUNET_MULTICAST_replay2 (struct GNUNET_MULTICAST_ReplayHandle *rh, | ||
534 | GNUNET_MULTICAST_ReplayTransmitNotify notify, | ||
535 | void *notify_cls); | ||
536 | |||
480 | 537 | ||
481 | /** | 538 | /** |
482 | * Start a multicast group. | 539 | * Start a multicast group. |
@@ -640,7 +697,27 @@ struct GNUNET_MULTICAST_MemberReplayHandle; | |||
640 | 697 | ||
641 | 698 | ||
642 | /** | 699 | /** |
643 | * Request a message to be replayed. | 700 | * Request a fragment to be replayed by fragment ID. |
701 | * | ||
702 | * Useful if messages below the @e max_known_fragment_id given when joining are | ||
703 | * needed and not known to the client. | ||
704 | * | ||
705 | * @param member Membership handle. | ||
706 | * @param fragment_id ID of a message fragment that this client would like to | ||
707 | see replayed. | ||
708 | * @param flags Additional flags for the replay request. It is used & defined | ||
709 | * by the replay callback. | ||
710 | * @param message_cb Function to be called for the replayed message. | ||
711 | * @param message_cb_cls Closure for @a message_cb. | ||
712 | * @return Replay request handle, NULL on error. | ||
713 | */ | ||
714 | struct GNUNET_MULTICAST_MemberReplayHandle * | ||
715 | GNUNET_MULTICAST_member_replay_fragment (struct GNUNET_MULTICAST_Member *member, | ||
716 | uint64_t fragment_id, | ||
717 | uint64_t flags) | ||
718 | |||
719 | /** | ||
720 | * Request a message fr to be replayed. | ||
644 | * | 721 | * |
645 | * Useful if messages below the @e max_known_fragment_id given when joining are | 722 | * Useful if messages below the @e max_known_fragment_id given when joining are |
646 | * needed and not known to the client. | 723 | * needed and not known to the client. |
@@ -656,17 +733,17 @@ struct GNUNET_MULTICAST_MemberReplayHandle; | |||
656 | * @param flags Additional flags for the replay request. It is used & defined | 733 | * @param flags Additional flags for the replay request. It is used & defined |
657 | * by the replay callback. E.g. the PSYC service would use this to | 734 | * by the replay callback. E.g. the PSYC service would use this to |
658 | * implement state synchronization. | 735 | * implement state synchronization. |
659 | * @param message_cb Function to be called for the replayed message. | 736 | * @param result_cb Function to be called for the replayed message. |
660 | * @param message_cb_cls Closure for @a message_cb. | 737 | * @param result_cb_cls Closure for @a message_cb. |
661 | * @return Replay request handle, NULL on error. | 738 | * @return Replay request handle, NULL on error. |
662 | */ | 739 | */ |
663 | struct GNUNET_MULTICAST_MemberReplayHandle * | 740 | struct GNUNET_MULTICAST_MemberReplayHandle * |
664 | GNUNET_MULTICAST_member_request_replay (struct GNUNET_MULTICAST_Member *member, | 741 | GNUNET_MULTICAST_member_replay_message (struct GNUNET_MULTICAST_Member *member, |
665 | uint64_t fragment_id, | ||
666 | uint64_t message_id, | 742 | uint64_t message_id, |
743 | uint64_t fragment_offset, | ||
667 | uint64_t flags, | 744 | uint64_t flags, |
668 | GNUNET_MULTICAST_MessageCallback message_cb, | 745 | GNUNET_MULTICAST_ResultCallback result_cb, |
669 | void *message_cb_cls); | 746 | void *result_cb_cls); |
670 | 747 | ||
671 | 748 | ||
672 | /** | 749 | /** |
@@ -675,7 +752,7 @@ GNUNET_MULTICAST_member_request_replay (struct GNUNET_MULTICAST_Member *member, | |||
675 | * @param rh Request to cancel. | 752 | * @param rh Request to cancel. |
676 | */ | 753 | */ |
677 | void | 754 | void |
678 | GNUNET_MULTICAST_member_request_replay_cancel (struct GNUNET_MULTICAST_MemberReplayHandle *rh); | 755 | GNUNET_MULTICAST_member_replay_cancel (struct GNUNET_MULTICAST_MemberReplayHandle *rh); |
679 | 756 | ||
680 | 757 | ||
681 | /** | 758 | /** |