diff options
Diffstat (limited to 'src/include/gnunet_messenger_service.h')
-rw-r--r-- | src/include/gnunet_messenger_service.h | 332 |
1 files changed, 259 insertions, 73 deletions
diff --git a/src/include/gnunet_messenger_service.h b/src/include/gnunet_messenger_service.h index f8bbc7398..1bc68b87b 100644 --- a/src/include/gnunet_messenger_service.h +++ b/src/include/gnunet_messenger_service.h | |||
@@ -1,6 +1,6 @@ | |||
1 | /* | 1 | /* |
2 | This file is part of GNUnet. | 2 | This file is part of GNUnet. |
3 | Copyright (C) 2020--2022 GNUnet e.V. | 3 | Copyright (C) 2020--2024 GNUnet e.V. |
4 | 4 | ||
5 | GNUnet is free software: you can redistribute it and/or modify it | 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 | 6 | under the terms of the GNU Affero General Public License as published |
@@ -39,21 +39,21 @@ extern "C" { | |||
39 | #endif | 39 | #endif |
40 | #endif | 40 | #endif |
41 | 41 | ||
42 | #include "platform.h" | 42 | #include "gnunet_common.h" |
43 | #include "gnunet_configuration_lib.h" | 43 | #include "gnunet_configuration_lib.h" |
44 | #include "gnunet_crypto_lib.h" | ||
45 | #include "gnunet_identity_service.h" | 44 | #include "gnunet_identity_service.h" |
46 | #include "gnunet_mq_lib.h" | 45 | #include "gnunet_reclaim_lib.h" |
47 | #include "gnunet_protocols.h" | 46 | #include "gnunet_reclaim_service.h" |
48 | #include "gnunet_scheduler_lib.h" | 47 | #include "gnunet_scheduler_lib.h" |
49 | #include "gnunet_time_lib.h" | 48 | #include "gnunet_time_lib.h" |
49 | #include "gnunet_util_lib.h" | ||
50 | 50 | ||
51 | /** | 51 | /** |
52 | * Version number of GNUnet Messenger API. | 52 | * Version number of GNUnet Messenger API. |
53 | * | 53 | * |
54 | * Current version of the Messenger: 0.1 | 54 | * Current version of the Messenger: 0.3 |
55 | */ | 55 | */ |
56 | #define GNUNET_MESSENGER_VERSION 0x00000001 | 56 | #define GNUNET_MESSENGER_VERSION 0x00000003 |
57 | 57 | ||
58 | /** | 58 | /** |
59 | * Identifier of GNUnet MESSENGER Service. | 59 | * Identifier of GNUnet MESSENGER Service. |
@@ -96,7 +96,7 @@ struct GNUNET_MESSENGER_RoomEntryRecord | |||
96 | 96 | ||
97 | GNUNET_NETWORK_STRUCT_END | 97 | GNUNET_NETWORK_STRUCT_END |
98 | 98 | ||
99 | GNUNET_NETWORK_STRUCT_BEGIN | 99 | GNUNET_NETWORK_STRUCT_BEGIN |
100 | 100 | ||
101 | /** | 101 | /** |
102 | * A room details record specifies a custom name for a given room and | 102 | * A room details record specifies a custom name for a given room and |
@@ -107,7 +107,7 @@ struct GNUNET_MESSENGER_RoomDetailsRecord | |||
107 | /** | 107 | /** |
108 | * The custom name for the room. | 108 | * The custom name for the room. |
109 | */ | 109 | */ |
110 | char name [256]; | 110 | char name[256]; |
111 | 111 | ||
112 | /** | 112 | /** |
113 | * The flags of the room. | 113 | * The flags of the room. |
@@ -198,6 +198,26 @@ enum GNUNET_MESSENGER_MessageKind | |||
198 | GNUNET_MESSENGER_KIND_DELETE = 15, | 198 | GNUNET_MESSENGER_KIND_DELETE = 15, |
199 | 199 | ||
200 | /** | 200 | /** |
201 | * The connection kind. The message contains a #GNUNET_MESSENGER_MessageConnection body. | ||
202 | */ | ||
203 | GNUNET_MESSENGER_KIND_CONNECTION = 16, | ||
204 | |||
205 | /** | ||
206 | * The ticket kind. The message contains a #GNUNET_MESSENGER_MessageTicket body. | ||
207 | */ | ||
208 | GNUNET_MESSENGER_KIND_TICKET = 17, | ||
209 | |||
210 | /** | ||
211 | * The transcript kind. The message contains a #GNUNET_MESSENGER_MessageTranscript body. | ||
212 | */ | ||
213 | GNUNET_MESSENGER_KIND_TRANSCRIPT = 18, | ||
214 | |||
215 | /** | ||
216 | * The tag kind. The message contains a #GNUNET_MESSENGER_MessageTag body. | ||
217 | */ | ||
218 | GNUNET_MESSENGER_KIND_TAG = 19, | ||
219 | |||
220 | /** | ||
201 | * The unknown kind. The message contains an unknown body. | 221 | * The unknown kind. The message contains an unknown body. |
202 | */ | 222 | */ |
203 | GNUNET_MESSENGER_KIND_UNKNOWN = 0 | 223 | GNUNET_MESSENGER_KIND_UNKNOWN = 0 |
@@ -225,7 +245,7 @@ struct GNUNET_MESSENGER_MessageHeader | |||
225 | /** | 245 | /** |
226 | * The signature of the senders private key. | 246 | * The signature of the senders private key. |
227 | */ | 247 | */ |
228 | struct GNUNET_IDENTITY_Signature signature; | 248 | struct GNUNET_CRYPTO_Signature signature; |
229 | 249 | ||
230 | /** | 250 | /** |
231 | * The timestamp of the message. | 251 | * The timestamp of the message. |
@@ -257,11 +277,6 @@ struct GNUNET_MESSENGER_MessageHeader | |||
257 | struct GNUNET_MESSENGER_MessageInfo | 277 | struct GNUNET_MESSENGER_MessageInfo |
258 | { | 278 | { |
259 | /** | 279 | /** |
260 | * The senders key to verify its signatures. | ||
261 | */ | ||
262 | struct GNUNET_IDENTITY_PublicKey host_key; | ||
263 | |||
264 | /** | ||
265 | * The version of GNUnet Messenger API. | 280 | * The version of GNUnet Messenger API. |
266 | * | 281 | * |
267 | * The sixteen lower bits represent the lower version number while the sixteen higher bits | 282 | * The sixteen lower bits represent the lower version number while the sixteen higher bits |
@@ -282,7 +297,7 @@ struct GNUNET_MESSENGER_MessageJoin | |||
282 | /** | 297 | /** |
283 | * The senders public key to verify its signatures. | 298 | * The senders public key to verify its signatures. |
284 | */ | 299 | */ |
285 | struct GNUNET_IDENTITY_PublicKey key; | 300 | struct GNUNET_CRYPTO_PublicKey key; |
286 | }; | 301 | }; |
287 | 302 | ||
288 | /** | 303 | /** |
@@ -320,7 +335,7 @@ struct GNUNET_MESSENGER_MessageKey | |||
320 | /** | 335 | /** |
321 | * The new public key which replaces the current senders public key. | 336 | * The new public key which replaces the current senders public key. |
322 | */ | 337 | */ |
323 | struct GNUNET_IDENTITY_PublicKey key; | 338 | struct GNUNET_CRYPTO_PublicKey key; |
324 | }; | 339 | }; |
325 | 340 | ||
326 | /** | 341 | /** |
@@ -499,6 +514,87 @@ struct GNUNET_MESSENGER_MessageDelete | |||
499 | }; | 514 | }; |
500 | 515 | ||
501 | /** | 516 | /** |
517 | * A connection message body | ||
518 | * This allows to tell others about connection information about a peer. | ||
519 | * | ||
520 | * Message-body-size: 8 bytes | ||
521 | */ | ||
522 | struct GNUNET_MESSENGER_MessageConnection | ||
523 | { | ||
524 | /** | ||
525 | * The amount of connections of a peer. | ||
526 | */ | ||
527 | uint32_t amount; | ||
528 | |||
529 | /** | ||
530 | * The flags about the connections of a peer. | ||
531 | */ | ||
532 | uint32_t flags; | ||
533 | }; | ||
534 | |||
535 | /** | ||
536 | * A ticket message body | ||
537 | * This allows to exchange ticket identifiers with an audience. | ||
538 | * | ||
539 | * Message-body-size: 32 bytes | ||
540 | */ | ||
541 | struct GNUNET_MESSENGER_MessageTicket | ||
542 | { | ||
543 | /** | ||
544 | * The identifier of a RECLAIM ticket. | ||
545 | */ | ||
546 | struct GNUNET_RECLAIM_Identifier identifier; | ||
547 | }; | ||
548 | |||
549 | /** | ||
550 | * A transcript message body | ||
551 | * This allows reading the content of a sent private message. | ||
552 | * | ||
553 | * Message-body-size: 68+ | ||
554 | */ | ||
555 | struct GNUNET_MESSENGER_MessageTranscript | ||
556 | { | ||
557 | /** | ||
558 | * The hash of the original message. | ||
559 | */ | ||
560 | struct GNUNET_HashCode hash; | ||
561 | |||
562 | /** | ||
563 | * The key from the recipient of the original message. | ||
564 | */ | ||
565 | struct GNUNET_CRYPTO_PublicKey key; | ||
566 | |||
567 | /** | ||
568 | * The length of the transcribed message. | ||
569 | */ | ||
570 | uint16_t length; | ||
571 | |||
572 | /** | ||
573 | * The data of the transcribed message. | ||
574 | */ | ||
575 | char *data; | ||
576 | }; | ||
577 | |||
578 | /** | ||
579 | * A tag message body | ||
580 | * This allows tagging a message with a custom tag. | ||
581 | * | ||
582 | * Message-body-size: 32+ | ||
583 | */ | ||
584 | struct GNUNET_MESSENGER_MessageTag | ||
585 | { | ||
586 | /** | ||
587 | * The hash of the message to tag. | ||
588 | */ | ||
589 | struct GNUNET_HashCode hash; | ||
590 | |||
591 | /** | ||
592 | * The custom tag. | ||
593 | */ | ||
594 | char *tag; | ||
595 | }; | ||
596 | |||
597 | /** | ||
502 | * The unified body of a #GNUNET_MESSENGER_Message. | 598 | * The unified body of a #GNUNET_MESSENGER_Message. |
503 | */ | 599 | */ |
504 | struct GNUNET_MESSENGER_MessageBody | 600 | struct GNUNET_MESSENGER_MessageBody |
@@ -520,6 +616,10 @@ struct GNUNET_MESSENGER_MessageBody | |||
520 | struct GNUNET_MESSENGER_MessageFile file; | 616 | struct GNUNET_MESSENGER_MessageFile file; |
521 | struct GNUNET_MESSENGER_MessagePrivate privacy; | 617 | struct GNUNET_MESSENGER_MessagePrivate privacy; |
522 | struct GNUNET_MESSENGER_MessageDelete deletion; | 618 | struct GNUNET_MESSENGER_MessageDelete deletion; |
619 | struct GNUNET_MESSENGER_MessageConnection connection; | ||
620 | struct GNUNET_MESSENGER_MessageTicket ticket; | ||
621 | struct GNUNET_MESSENGER_MessageTranscript transcript; | ||
622 | struct GNUNET_MESSENGER_MessageTag tag; | ||
523 | }; | 623 | }; |
524 | }; | 624 | }; |
525 | 625 | ||
@@ -540,7 +640,7 @@ struct GNUNET_MESSENGER_Message | |||
540 | }; | 640 | }; |
541 | 641 | ||
542 | /** | 642 | /** |
543 | * Enum for the different supported flags used by message handling | 643 | * Enum for the different supported flags used by message handling. |
544 | * Compatible flags can be OR'ed together. | 644 | * Compatible flags can be OR'ed together. |
545 | */ | 645 | */ |
546 | enum GNUNET_MESSENGER_MessageFlags | 646 | enum GNUNET_MESSENGER_MessageFlags |
@@ -559,18 +659,44 @@ enum GNUNET_MESSENGER_MessageFlags | |||
559 | * The private flag. The flag indicates that the message was privately encrypted. | 659 | * The private flag. The flag indicates that the message was privately encrypted. |
560 | */ | 660 | */ |
561 | GNUNET_MESSENGER_FLAG_PRIVATE = 2, | 661 | GNUNET_MESSENGER_FLAG_PRIVATE = 2, |
662 | |||
663 | /** | ||
664 | * The peer flag. The flag indicates that the message was sent by a peer and not a member. | ||
665 | */ | ||
666 | GNUNET_MESSENGER_FLAG_PEER = 4, | ||
667 | |||
668 | /** | ||
669 | * The recent flag. The flag indicates that the message was recently handled by the service. | ||
670 | */ | ||
671 | GNUNET_MESSENGER_FLAG_RECENT = 8, | ||
672 | |||
673 | /** | ||
674 | * The update flag. The flag indicates that the message was updated by the client. | ||
675 | */ | ||
676 | GNUNET_MESSENGER_FLAG_UPDATE = 16, | ||
677 | |||
678 | /** | ||
679 | * The delete flag. The flag indicates that the message was deleted by the service. | ||
680 | */ | ||
681 | GNUNET_MESSENGER_FLAG_DELETE = 32, | ||
562 | }; | 682 | }; |
563 | 683 | ||
564 | /** | 684 | /** |
565 | * Method called whenever the EGO of a <i>handle</i> changes or if the first connection fails | 685 | * Enum for the different supported flags used to specify connection handling. |
566 | * to load a valid EGO and the anonymous key pair will be used instead. | 686 | * Compatible flags can be OR'ed together. |
567 | * | ||
568 | * @param[in/out] cls Closure from #GNUNET_MESSENGER_connect | ||
569 | * @param[in/out] handle Messenger handle | ||
570 | */ | 687 | */ |
571 | typedef void | 688 | enum GNUNET_MESSENGER_ConnectionFlags |
572 | (*GNUNET_MESSENGER_IdentityCallback) (void *cls, | 689 | { |
573 | struct GNUNET_MESSENGER_Handle *handle); | 690 | /** |
691 | * The none flag. The flag indicates that the connection is not affected by any modifications. | ||
692 | */ | ||
693 | GNUNET_MESSENGER_FLAG_CONNECTION_NONE = 0,/**< GNUNET_MESSENGER_FLAG_CONNECTION_NONE */ | ||
694 | |||
695 | /** | ||
696 | * The auto flag. The flag indicates that a peer will automatically handle routing. | ||
697 | */ | ||
698 | GNUNET_MESSENGER_FLAG_CONNECTION_AUTO = 1,/**< GNUNET_MESSENGER_FLAG_CONNECTION_AUTO */ | ||
699 | }; | ||
574 | 700 | ||
575 | /** | 701 | /** |
576 | * Method called whenever a message is sent or received from a <i>room</i>. | 702 | * Method called whenever a message is sent or received from a <i>room</i>. |
@@ -581,6 +707,7 @@ typedef void | |||
581 | * @param[in/out] cls Closure from #GNUNET_MESSENGER_connect | 707 | * @param[in/out] cls Closure from #GNUNET_MESSENGER_connect |
582 | * @param[in] room Room handle | 708 | * @param[in] room Room handle |
583 | * @param[in] sender Sender of message | 709 | * @param[in] sender Sender of message |
710 | * @param[in] recipient Recipient of message | ||
584 | * @param[in] message Newly received or sent message | 711 | * @param[in] message Newly received or sent message |
585 | * @param[in] hash Hash identifying the message | 712 | * @param[in] hash Hash identifying the message |
586 | * @param[in] flags Flags of the message | 713 | * @param[in] flags Flags of the message |
@@ -588,8 +715,12 @@ typedef void | |||
588 | typedef void | 715 | typedef void |
589 | (*GNUNET_MESSENGER_MessageCallback) (void *cls, | 716 | (*GNUNET_MESSENGER_MessageCallback) (void *cls, |
590 | struct GNUNET_MESSENGER_Room *room, | 717 | struct GNUNET_MESSENGER_Room *room, |
591 | const struct GNUNET_MESSENGER_Contact *sender, | 718 | const struct |
592 | const struct GNUNET_MESSENGER_Message *message, | 719 | GNUNET_MESSENGER_Contact *sender, |
720 | const struct | ||
721 | GNUNET_MESSENGER_Contact *recipient, | ||
722 | const struct | ||
723 | GNUNET_MESSENGER_Message *message, | ||
593 | const struct GNUNET_HashCode *hash, | 724 | const struct GNUNET_HashCode *hash, |
594 | enum GNUNET_MESSENGER_MessageFlags flags); | 725 | enum GNUNET_MESSENGER_MessageFlags flags); |
595 | 726 | ||
@@ -601,49 +732,34 @@ typedef void | |||
601 | * @param[in] room Room handle | 732 | * @param[in] room Room handle |
602 | * @param[in] contact Contact handle | 733 | * @param[in] contact Contact handle |
603 | */ | 734 | */ |
604 | typedef int | 735 | typedef enum GNUNET_GenericReturnValue |
605 | (*GNUNET_MESSENGER_MemberCallback) (void* cls, | 736 | (*GNUNET_MESSENGER_MemberCallback) (void *cls, |
606 | struct GNUNET_MESSENGER_Room *room, | 737 | struct GNUNET_MESSENGER_Room *room, |
607 | const struct GNUNET_MESSENGER_Contact *contact); | 738 | const struct |
739 | GNUNET_MESSENGER_Contact *contact); | ||
608 | 740 | ||
609 | /** | 741 | /** |
610 | * Set up a handle for the messenger related functions and connects to all necessary services. It will look up the ego | 742 | * Set up a handle for the messenger related functions and connects to all necessary services. It will use the |
611 | * key identified by its <i>name</i> and use it for signing all messages from the handle. | 743 | * a custom name in combination of a private key provided for signing all messages from the handle. |
612 | * | 744 | * |
613 | * @param[in] cfg Configuration to use | 745 | * @param[in] cfg Configuration to use |
614 | * @param[in] name Name to look up an ego or NULL to stay anonymous | 746 | * @param[in] name Name or NULL |
615 | * @param[in] identity_callback Function called when the EGO of the handle changes | 747 | * @param[in] key Private key or NULL to stay anonymous |
616 | * @param[in/out] identity_cls Closure for the <i>identity_callback</i> handler | ||
617 | * @param[in] msg_callback Function called when a new message is sent or received | 748 | * @param[in] msg_callback Function called when a new message is sent or received |
618 | * @param[in/out] msg_cls Closure for the <i>msg_callback</i> handler | 749 | * @param[in,out] msg_cls Closure for the <i>msg_callback</i> handler |
619 | * @return Messenger handle to use, NULL on error | 750 | * @return Messenger handle to use, NULL on error |
620 | */ | 751 | */ |
621 | struct GNUNET_MESSENGER_Handle* | 752 | struct GNUNET_MESSENGER_Handle* |
622 | GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | 753 | GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, |
623 | const char *name, | 754 | const char *name, |
624 | GNUNET_MESSENGER_IdentityCallback identity_callback, | 755 | const struct GNUNET_CRYPTO_PrivateKey *key, |
625 | void *identity_cls, | ||
626 | GNUNET_MESSENGER_MessageCallback msg_callback, | 756 | GNUNET_MESSENGER_MessageCallback msg_callback, |
627 | void *msg_cls); | 757 | void *msg_cls); |
628 | 758 | ||
629 | /** | 759 | /** |
630 | * Update a handle of the messenger to use a different ego key and replace the old one with a newly generated one. All | ||
631 | * participated rooms get informed about the key renewal. The handle requires a set name for this function to work and | ||
632 | * it needs to be unused by other egos. | ||
633 | * | ||
634 | * Keep in mind that this will fully delete the old ego key (if any is used) even if any other service wants to use it | ||
635 | * as default. | ||
636 | * | ||
637 | * @param[in/out] handle Messenger handle to use | ||
638 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | ||
639 | */ | ||
640 | int | ||
641 | GNUNET_MESSENGER_update (struct GNUNET_MESSENGER_Handle *handle); | ||
642 | |||
643 | /** | ||
644 | * Disconnect all of the messengers used services and clears up its used memory. | 760 | * Disconnect all of the messengers used services and clears up its used memory. |
645 | * | 761 | * |
646 | * @param[in/out] handle Messenger handle to use | 762 | * @param[in,out] handle Messenger handle to use |
647 | */ | 763 | */ |
648 | void | 764 | void |
649 | GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); | 765 | GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); |
@@ -658,15 +774,14 @@ const char* | |||
658 | GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle); | 774 | GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle); |
659 | 775 | ||
660 | /** | 776 | /** |
661 | * Set the name for the messenger. This will rename the currently used ego and move all stored files related to the current | 777 | * Set the name for the messenger handle and sends messages renaming your contact in currently |
662 | * name to its new directory. If anything fails during this process the function returns #GNUNET_NO and the name for | 778 | * open rooms. |
663 | * the messenger won't change as specified. | ||
664 | * | 779 | * |
665 | * @param[in/out] handle Messenger handle to use | 780 | * @param[in,out] handle Messenger handle to use |
666 | * @param[in] name Name for the messenger to change to | 781 | * @param[in] name Name for the messenger to change to |
667 | * @return #GNUNET_YES on success, #GNUNET_NO on failure and #GNUNET_SYSERR if <i>handle</i> is NULL | 782 | * @return #GNUNET_YES on success, #GNUNET_NO on failure and #GNUNET_SYSERR if <i>handle</i> is NULL |
668 | */ | 783 | */ |
669 | int | 784 | enum GNUNET_GenericReturnValue |
670 | GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, | 785 | GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, |
671 | const char *name); | 786 | const char *name); |
672 | 787 | ||
@@ -674,12 +789,25 @@ GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, | |||
674 | * Get the public key used by the messenger or NULL if the anonymous key was used. | 789 | * Get the public key used by the messenger or NULL if the anonymous key was used. |
675 | * | 790 | * |
676 | * @param[in] handle Messenger handle to use | 791 | * @param[in] handle Messenger handle to use |
677 | * @return Used ego's public key or NULL | 792 | * @return Used public key or NULL |
678 | */ | 793 | */ |
679 | const struct GNUNET_IDENTITY_PublicKey* | 794 | const struct GNUNET_CRYPTO_PublicKey* |
680 | GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); | 795 | GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); |
681 | 796 | ||
682 | /** | 797 | /** |
798 | * Set the private key used by the messenger or NULL if the anonymous key should be | ||
799 | * used instead. The currently used key will be replaced and the change will get signed | ||
800 | * accordingly to be verified by all contacts. | ||
801 | * | ||
802 | * @param[in,out] handle Messenger handle to use | ||
803 | * @param[in] key Private key to change to or NULL | ||
804 | * @return #GNUNET_YES on success, #GNUNET_NO on failure and #GNUNET_SYSERR if <i>handle</i> is NULL | ||
805 | */ | ||
806 | enum GNUNET_GenericReturnValue | ||
807 | GNUNET_MESSENGER_set_key (struct GNUNET_MESSENGER_Handle *handle, | ||
808 | const struct GNUNET_CRYPTO_PrivateKey *key); | ||
809 | |||
810 | /** | ||
683 | * Open a room to send and receive messages. The room will use the specified <i>key</i> as port for the underlying cadet | 811 | * Open a room to send and receive messages. The room will use the specified <i>key</i> as port for the underlying cadet |
684 | * service. Opening a room results in opening the port for incoming connections as possible <b>door</b>. | 812 | * service. Opening a room results in opening the port for incoming connections as possible <b>door</b>. |
685 | * | 813 | * |
@@ -691,7 +819,7 @@ GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); | |||
691 | * | 819 | * |
692 | * ( All <b>doors</b> form a ring structured network to shorten the latency sending and receiving messages. ) | 820 | * ( All <b>doors</b> form a ring structured network to shorten the latency sending and receiving messages. ) |
693 | * | 821 | * |
694 | * @param[in/out] handle Messenger handle to use | 822 | * @param[in,out] handle Messenger handle to use |
695 | * @param[in] key Hash identifying the port | 823 | * @param[in] key Hash identifying the port |
696 | * @return Room handle, NULL on error | 824 | * @return Room handle, NULL on error |
697 | */ | 825 | */ |
@@ -712,7 +840,7 @@ GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, | |||
712 | * | 840 | * |
713 | * ( All <b>doors</b> form a ring structured network to shorten the latency sending and receiving messages. ) | 841 | * ( All <b>doors</b> form a ring structured network to shorten the latency sending and receiving messages. ) |
714 | * | 842 | * |
715 | * @param[in/out] handle Messenger handle to use | 843 | * @param[in,out] handle Messenger handle to use |
716 | * @param[in] door Peer identity of an open <b>door</b> | 844 | * @param[in] door Peer identity of an open <b>door</b> |
717 | * @param[in] key Hash identifying the port | 845 | * @param[in] key Hash identifying the port |
718 | * @return Room handle, NULL on error | 846 | * @return Room handle, NULL on error |
@@ -729,7 +857,7 @@ GNUNET_MESSENGER_enter_room (struct GNUNET_MESSENGER_Handle *handle, | |||
729 | * ( After a member closes a <b>door</b>, all members entered through that specific <b>door</b> have to use another one | 857 | * ( After a member closes a <b>door</b>, all members entered through that specific <b>door</b> have to use another one |
730 | * or open the room on their own. ) | 858 | * or open the room on their own. ) |
731 | * | 859 | * |
732 | * @param[in/out] room Room handle | 860 | * @param[in,out] room Room handle |
733 | */ | 861 | */ |
734 | void | 862 | void |
735 | GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); | 863 | GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); |
@@ -774,25 +902,51 @@ GNUNET_MESSENGER_get_sender (const struct GNUNET_MESSENGER_Room *room, | |||
774 | const struct GNUNET_HashCode *hash); | 902 | const struct GNUNET_HashCode *hash); |
775 | 903 | ||
776 | /** | 904 | /** |
905 | * Get the contact of a member in a <i>room</i> which has been targeted as recipient of a specific message identified | ||
906 | * with a given <i>hash</i>. | ||
907 | * | ||
908 | * Notice that contacts are independent of rooms but will be removed if all rooms containing these contacts get closed. | ||
909 | * | ||
910 | * @param[in] room Room handle | ||
911 | * @param[in] hash Hash identifying a message | ||
912 | * @return Contact handle, NULL otherwise | ||
913 | */ | ||
914 | const struct GNUNET_MESSENGER_Contact* | ||
915 | GNUNET_MESSENGER_get_recipient (const struct GNUNET_MESSENGER_Room *room, | ||
916 | const struct GNUNET_HashCode *hash); | ||
917 | |||
918 | /** | ||
777 | * Get the name used by the <i>contact</i>. | 919 | * Get the name used by the <i>contact</i>. |
778 | * | 920 | * |
779 | * @param[in] contact Contact handle | 921 | * @param[in] contact Contact handle |
780 | * @return Name of <i>contact</i> or NULL | 922 | * @return Name of <i>contact</i> or NULL |
781 | */ | 923 | */ |
782 | const char* | 924 | const char* |
783 | GNUNET_MESSENGER_contact_get_name (const struct GNUNET_MESSENGER_Contact *contact); | 925 | GNUNET_MESSENGER_contact_get_name (const struct |
926 | GNUNET_MESSENGER_Contact *contact); | ||
784 | 927 | ||
785 | /** | 928 | /** |
786 | * Get the public key used by the <i>contact</i> or NULL if the anonymous key was used. | 929 | * Get the public key used by the <i>contact</i> or NULL if the anonymous key was used. |
787 | * | 930 | * |
788 | * @param[in] contact Contact handle | 931 | * @param[in] contact Contact handle |
789 | * @return Public key of the ego used by <i>contact</i> or NULL | 932 | * @return Public key used by <i>contact</i> or NULL |
790 | */ | 933 | */ |
791 | const struct GNUNET_IDENTITY_PublicKey* | 934 | const struct GNUNET_CRYPTO_PublicKey* |
792 | GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact); | 935 | GNUNET_MESSENGER_contact_get_key (const struct |
936 | GNUNET_MESSENGER_Contact *contact); | ||
793 | 937 | ||
794 | /** | 938 | /** |
795 | * Send a <i>message</i> into a </i>room</i>. If you opened the <i>room</i> all entered members will receive the | 939 | * Get the locally unique id of the <i>contact</i>. |
940 | * | ||
941 | * @param[in] contact Contact handle | ||
942 | * @return Locally unique contact id or zero | ||
943 | */ | ||
944 | size_t | ||
945 | GNUNET_MESSENGER_contact_get_id (const struct | ||
946 | GNUNET_MESSENGER_Contact *contact); | ||
947 | |||
948 | /** | ||
949 | * Send a <i>message</i> into a <i>room</i>. If you opened the <i>room</i> all entered members will receive the | ||
796 | * <i>message</i>. If you entered the <i>room</i> through a <b>door</b> all so entered <b>doors</b> will receive the | 950 | * <i>message</i>. If you entered the <i>room</i> through a <b>door</b> all so entered <b>doors</b> will receive the |
797 | * <i>message</i> as well. All members receiving the <i>message</i> will also propagate this <i>message</i> recursively | 951 | * <i>message</i> as well. All members receiving the <i>message</i> will also propagate this <i>message</i> recursively |
798 | * as long as the <i>message</i> is unknown to them. | 952 | * as long as the <i>message</i> is unknown to them. |
@@ -805,14 +959,30 @@ GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact | |||
805 | * | 959 | * |
806 | * Sending a message to all members in a given room can be done by providing NULL as contact. | 960 | * Sending a message to all members in a given room can be done by providing NULL as contact. |
807 | * | 961 | * |
808 | * @param[in/out] room Room handle | 962 | * @param[in,out] room Room handle |
809 | * @param[in] message New message to send | 963 | * @param[in,out] message New message to send |
810 | * @param[in] contact Contact or NULL | 964 | * @param[in] contact Contact or NULL |
811 | */ | 965 | */ |
812 | void | 966 | void |
813 | GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, | 967 | GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, |
814 | const struct GNUNET_MESSENGER_Message *message, | 968 | const struct GNUNET_MESSENGER_Message *message, |
815 | const struct GNUNET_MESSENGER_Contact* contact); | 969 | const struct GNUNET_MESSENGER_Contact *contact); |
970 | |||
971 | /** | ||
972 | * Delete a message identified by its <i>hash</i> from a <i>room</i>. A deletion will be propagated to all members | ||
973 | * of the room as with any other sent message. Notice that a deletion will only request other members of the room | ||
974 | * to delete the selected message. If you are not permitted to delete the message, the deletion will be ignored. | ||
975 | * | ||
976 | * Depending on the implementation other clients may also ignore your deletion request in other circumstances. | ||
977 | * | ||
978 | * @param[in,out] room Room handle | ||
979 | * @param[in] message Message to delete | ||
980 | * @param[in] delay Delay to delete the message | ||
981 | */ | ||
982 | void | ||
983 | GNUNET_MESSENGER_delete_message (struct GNUNET_MESSENGER_Room *room, | ||
984 | const struct GNUNET_HashCode *hash, | ||
985 | const struct GNUNET_TIME_Relative delay); | ||
816 | 986 | ||
817 | /** | 987 | /** |
818 | * Get the message in a <i>room</i> identified by its <i>hash</i>. | 988 | * Get the message in a <i>room</i> identified by its <i>hash</i>. |
@@ -838,7 +1008,23 @@ GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, | |||
838 | int | 1008 | int |
839 | GNUNET_MESSENGER_iterate_members (struct GNUNET_MESSENGER_Room *room, | 1009 | GNUNET_MESSENGER_iterate_members (struct GNUNET_MESSENGER_Room *room, |
840 | GNUNET_MESSENGER_MemberCallback callback, | 1010 | GNUNET_MESSENGER_MemberCallback callback, |
841 | void* cls); | 1011 | void *cls); |
1012 | |||
1013 | /** | ||
1014 | * Send a <i>ticket</i> into a <i>room</i>. The ticket will automatically be converted | ||
1015 | * into a message to be sent only to its audience as a private message. | ||
1016 | * | ||
1017 | * A ticket can only be sent with this function if its issuer's public key is the one | ||
1018 | * being used by the messenger. The audience's public key is not allowed to be the | ||
1019 | * anonymous public key. The room needs to contain a member using the audience's public | ||
1020 | * key. | ||
1021 | * | ||
1022 | * @param[in,out] room Room handle | ||
1023 | * @param[in] ticket Ticket to send | ||
1024 | */ | ||
1025 | void | ||
1026 | GNUNET_MESSENGER_send_ticket (struct GNUNET_MESSENGER_Room *room, | ||
1027 | const struct GNUNET_RECLAIM_Ticket *ticket); | ||
842 | 1028 | ||
843 | #if 0 /* keep Emacsens' auto-indent happy */ | 1029 | #if 0 /* keep Emacsens' auto-indent happy */ |
844 | { | 1030 | { |