diff options
Diffstat (limited to 'src/include/gnunet_messenger_service.h')
-rw-r--r-- | src/include/gnunet_messenger_service.h | 405 |
1 files changed, 324 insertions, 81 deletions
diff --git a/src/include/gnunet_messenger_service.h b/src/include/gnunet_messenger_service.h index 5d7155a3d..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 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. |
@@ -75,6 +75,48 @@ struct GNUNET_MESSENGER_Room; | |||
75 | */ | 75 | */ |
76 | struct GNUNET_MESSENGER_Contact; | 76 | struct GNUNET_MESSENGER_Contact; |
77 | 77 | ||
78 | GNUNET_NETWORK_STRUCT_BEGIN | ||
79 | |||
80 | /** | ||
81 | * A room entry record specifies which peer is hosting a given room and | ||
82 | * may also specify the key to enter it. | ||
83 | */ | ||
84 | struct GNUNET_MESSENGER_RoomEntryRecord | ||
85 | { | ||
86 | /** | ||
87 | * The peer identity of an open door to a room. | ||
88 | */ | ||
89 | struct GNUNET_PeerIdentity door; | ||
90 | |||
91 | /** | ||
92 | * The hash identifying the port of the room. | ||
93 | */ | ||
94 | struct GNUNET_HashCode key; | ||
95 | }; | ||
96 | |||
97 | GNUNET_NETWORK_STRUCT_END | ||
98 | |||
99 | GNUNET_NETWORK_STRUCT_BEGIN | ||
100 | |||
101 | /** | ||
102 | * A room details record specifies a custom name for a given room and | ||
103 | * some additional space for flags. | ||
104 | */ | ||
105 | struct GNUNET_MESSENGER_RoomDetailsRecord | ||
106 | { | ||
107 | /** | ||
108 | * The custom name for the room. | ||
109 | */ | ||
110 | char name[256]; | ||
111 | |||
112 | /** | ||
113 | * The flags of the room. | ||
114 | */ | ||
115 | uint32_t flags; | ||
116 | }; | ||
117 | |||
118 | GNUNET_NETWORK_STRUCT_END | ||
119 | |||
78 | /** | 120 | /** |
79 | * Enum for the different supported kinds of messages | 121 | * Enum for the different supported kinds of messages |
80 | */ | 122 | */ |
@@ -156,6 +198,26 @@ enum GNUNET_MESSENGER_MessageKind | |||
156 | GNUNET_MESSENGER_KIND_DELETE = 15, | 198 | GNUNET_MESSENGER_KIND_DELETE = 15, |
157 | 199 | ||
158 | /** | 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 | /** | ||
159 | * The unknown kind. The message contains an unknown body. | 221 | * The unknown kind. The message contains an unknown body. |
160 | */ | 222 | */ |
161 | GNUNET_MESSENGER_KIND_UNKNOWN = 0 | 223 | GNUNET_MESSENGER_KIND_UNKNOWN = 0 |
@@ -183,7 +245,7 @@ struct GNUNET_MESSENGER_MessageHeader | |||
183 | /** | 245 | /** |
184 | * The signature of the senders private key. | 246 | * The signature of the senders private key. |
185 | */ | 247 | */ |
186 | struct GNUNET_IDENTITY_Signature signature; | 248 | struct GNUNET_CRYPTO_Signature signature; |
187 | 249 | ||
188 | /** | 250 | /** |
189 | * The timestamp of the message. | 251 | * The timestamp of the message. |
@@ -215,11 +277,6 @@ struct GNUNET_MESSENGER_MessageHeader | |||
215 | struct GNUNET_MESSENGER_MessageInfo | 277 | struct GNUNET_MESSENGER_MessageInfo |
216 | { | 278 | { |
217 | /** | 279 | /** |
218 | * The senders key to verify its signatures. | ||
219 | */ | ||
220 | struct GNUNET_IDENTITY_PublicKey host_key; | ||
221 | |||
222 | /** | ||
223 | * The version of GNUnet Messenger API. | 280 | * The version of GNUnet Messenger API. |
224 | * | 281 | * |
225 | * 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 |
@@ -240,7 +297,7 @@ struct GNUNET_MESSENGER_MessageJoin | |||
240 | /** | 297 | /** |
241 | * The senders public key to verify its signatures. | 298 | * The senders public key to verify its signatures. |
242 | */ | 299 | */ |
243 | struct GNUNET_IDENTITY_PublicKey key; | 300 | struct GNUNET_CRYPTO_PublicKey key; |
244 | }; | 301 | }; |
245 | 302 | ||
246 | /** | 303 | /** |
@@ -278,7 +335,7 @@ struct GNUNET_MESSENGER_MessageKey | |||
278 | /** | 335 | /** |
279 | * The new public key which replaces the current senders public key. | 336 | * The new public key which replaces the current senders public key. |
280 | */ | 337 | */ |
281 | struct GNUNET_IDENTITY_PublicKey key; | 338 | struct GNUNET_CRYPTO_PublicKey key; |
282 | }; | 339 | }; |
283 | 340 | ||
284 | /** | 341 | /** |
@@ -457,6 +514,87 @@ struct GNUNET_MESSENGER_MessageDelete | |||
457 | }; | 514 | }; |
458 | 515 | ||
459 | /** | 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 | /** | ||
460 | * The unified body of a #GNUNET_MESSENGER_Message. | 598 | * The unified body of a #GNUNET_MESSENGER_Message. |
461 | */ | 599 | */ |
462 | struct GNUNET_MESSENGER_MessageBody | 600 | struct GNUNET_MESSENGER_MessageBody |
@@ -478,6 +616,10 @@ struct GNUNET_MESSENGER_MessageBody | |||
478 | struct GNUNET_MESSENGER_MessageFile file; | 616 | struct GNUNET_MESSENGER_MessageFile file; |
479 | struct GNUNET_MESSENGER_MessagePrivate privacy; | 617 | struct GNUNET_MESSENGER_MessagePrivate privacy; |
480 | 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; | ||
481 | }; | 623 | }; |
482 | }; | 624 | }; |
483 | 625 | ||
@@ -498,7 +640,7 @@ struct GNUNET_MESSENGER_Message | |||
498 | }; | 640 | }; |
499 | 641 | ||
500 | /** | 642 | /** |
501 | * Enum for the different supported flags used by message handling | 643 | * Enum for the different supported flags used by message handling. |
502 | * Compatible flags can be OR'ed together. | 644 | * Compatible flags can be OR'ed together. |
503 | */ | 645 | */ |
504 | enum GNUNET_MESSENGER_MessageFlags | 646 | enum GNUNET_MESSENGER_MessageFlags |
@@ -517,17 +659,44 @@ enum GNUNET_MESSENGER_MessageFlags | |||
517 | * 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. |
518 | */ | 660 | */ |
519 | 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, | ||
520 | }; | 682 | }; |
521 | 683 | ||
522 | /** | 684 | /** |
523 | * 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. |
524 | * to load a valid EGO and the anonymous key pair will be used instead. | 686 | * Compatible flags can be OR'ed together. |
525 | * | ||
526 | * @param[in/out] cls Closure from #GNUNET_MESSENGER_connect | ||
527 | * @param[in/out] handle Messenger handle | ||
528 | */ | 687 | */ |
529 | typedef void | 688 | enum GNUNET_MESSENGER_ConnectionFlags |
530 | (*GNUNET_MESSENGER_IdentityCallback) (void *cls, struct GNUNET_MESSENGER_Handle *handle); | 689 | { |
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 | }; | ||
531 | 700 | ||
532 | /** | 701 | /** |
533 | * 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>. |
@@ -538,14 +707,20 @@ typedef void | |||
538 | * @param[in/out] cls Closure from #GNUNET_MESSENGER_connect | 707 | * @param[in/out] cls Closure from #GNUNET_MESSENGER_connect |
539 | * @param[in] room Room handle | 708 | * @param[in] room Room handle |
540 | * @param[in] sender Sender of message | 709 | * @param[in] sender Sender of message |
710 | * @param[in] recipient Recipient of message | ||
541 | * @param[in] message Newly received or sent message | 711 | * @param[in] message Newly received or sent message |
542 | * @param[in] hash Hash identifying the message | 712 | * @param[in] hash Hash identifying the message |
543 | * @param[in] flags Flags of the message | 713 | * @param[in] flags Flags of the message |
544 | */ | 714 | */ |
545 | typedef void | 715 | typedef void |
546 | (*GNUNET_MESSENGER_MessageCallback) (void *cls, struct GNUNET_MESSENGER_Room *room, | 716 | (*GNUNET_MESSENGER_MessageCallback) (void *cls, |
547 | const struct GNUNET_MESSENGER_Contact *sender, | 717 | struct GNUNET_MESSENGER_Room *room, |
548 | const struct GNUNET_MESSENGER_Message *message, | 718 | const struct |
719 | GNUNET_MESSENGER_Contact *sender, | ||
720 | const struct | ||
721 | GNUNET_MESSENGER_Contact *recipient, | ||
722 | const struct | ||
723 | GNUNET_MESSENGER_Message *message, | ||
549 | const struct GNUNET_HashCode *hash, | 724 | const struct GNUNET_HashCode *hash, |
550 | enum GNUNET_MESSENGER_MessageFlags flags); | 725 | enum GNUNET_MESSENGER_MessageFlags flags); |
551 | 726 | ||
@@ -557,45 +732,34 @@ typedef void | |||
557 | * @param[in] room Room handle | 732 | * @param[in] room Room handle |
558 | * @param[in] contact Contact handle | 733 | * @param[in] contact Contact handle |
559 | */ | 734 | */ |
560 | typedef int | 735 | typedef enum GNUNET_GenericReturnValue |
561 | (*GNUNET_MESSENGER_MemberCallback) (void* cls, struct GNUNET_MESSENGER_Room *room, | 736 | (*GNUNET_MESSENGER_MemberCallback) (void *cls, |
562 | const struct GNUNET_MESSENGER_Contact *contact); | 737 | struct GNUNET_MESSENGER_Room *room, |
738 | const struct | ||
739 | GNUNET_MESSENGER_Contact *contact); | ||
563 | 740 | ||
564 | /** | 741 | /** |
565 | * 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 |
566 | * 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. |
567 | * | 744 | * |
568 | * @param[in] cfg Configuration to use | 745 | * @param[in] cfg Configuration to use |
569 | * @param[in] name Name to look up an ego or NULL to stay anonymous | 746 | * @param[in] name Name or NULL |
570 | * @param[in] identity_callback Function called when the EGO of the handle changes | 747 | * @param[in] key Private key or NULL to stay anonymous |
571 | * @param[in/out] identity_cls Closure for the <i>identity_callback</i> handler | ||
572 | * @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 |
573 | * @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 |
574 | * @return Messenger handle to use, NULL on error | 750 | * @return Messenger handle to use, NULL on error |
575 | */ | 751 | */ |
576 | struct GNUNET_MESSENGER_Handle* | 752 | struct GNUNET_MESSENGER_Handle* |
577 | GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *name, | 753 | GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, |
578 | GNUNET_MESSENGER_IdentityCallback identity_callback, void *identity_cls, | 754 | const char *name, |
579 | GNUNET_MESSENGER_MessageCallback msg_callback, void *msg_cls); | 755 | const struct GNUNET_CRYPTO_PrivateKey *key, |
580 | 756 | GNUNET_MESSENGER_MessageCallback msg_callback, | |
581 | /** | 757 | void *msg_cls); |
582 | * Update a handle of the messenger to use a different ego key and replace the old one with a newly generated one. All | ||
583 | * participated rooms get informed about the key renewal. The handle requires a set name for this function to work and | ||
584 | * it needs to be unused by other egos. | ||
585 | * | ||
586 | * 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 | ||
587 | * as default. | ||
588 | * | ||
589 | * @param[in/out] handle Messenger handle to use | ||
590 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | ||
591 | */ | ||
592 | int | ||
593 | GNUNET_MESSENGER_update (struct GNUNET_MESSENGER_Handle *handle); | ||
594 | 758 | ||
595 | /** | 759 | /** |
596 | * 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. |
597 | * | 761 | * |
598 | * @param[in/out] handle Messenger handle to use | 762 | * @param[in,out] handle Messenger handle to use |
599 | */ | 763 | */ |
600 | void | 764 | void |
601 | GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); | 765 | GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); |
@@ -610,27 +774,40 @@ const char* | |||
610 | GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle); | 774 | GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle); |
611 | 775 | ||
612 | /** | 776 | /** |
613 | * 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 |
614 | * name to its new directory. If anything fails during this process the function returns #GNUNET_NO and the name for | 778 | * open rooms. |
615 | * the messenger won't change as specified. | ||
616 | * | 779 | * |
617 | * @param[in/out] handle Messenger handle to use | 780 | * @param[in,out] handle Messenger handle to use |
618 | * @param[in] name Name for the messenger to change to | 781 | * @param[in] name Name for the messenger to change to |
619 | * @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 |
620 | */ | 783 | */ |
621 | int | 784 | enum GNUNET_GenericReturnValue |
622 | GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, const char *name); | 785 | GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, |
786 | const char *name); | ||
623 | 787 | ||
624 | /** | 788 | /** |
625 | * 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. |
626 | * | 790 | * |
627 | * @param[in] handle Messenger handle to use | 791 | * @param[in] handle Messenger handle to use |
628 | * @return Used ego's public key or NULL | 792 | * @return Used public key or NULL |
629 | */ | 793 | */ |
630 | const struct GNUNET_IDENTITY_PublicKey* | 794 | const struct GNUNET_CRYPTO_PublicKey* |
631 | GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); | 795 | GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); |
632 | 796 | ||
633 | /** | 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 | /** | ||
634 | * 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 |
635 | * 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>. |
636 | * | 813 | * |
@@ -642,12 +819,13 @@ GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); | |||
642 | * | 819 | * |
643 | * ( 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. ) |
644 | * | 821 | * |
645 | * @param[in/out] handle Messenger handle to use | 822 | * @param[in,out] handle Messenger handle to use |
646 | * @param[in] key Hash identifying the port | 823 | * @param[in] key Hash identifying the port |
647 | * @return Room handle, NULL on error | 824 | * @return Room handle, NULL on error |
648 | */ | 825 | */ |
649 | struct GNUNET_MESSENGER_Room* | 826 | struct GNUNET_MESSENGER_Room* |
650 | GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_HashCode *key); | 827 | GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, |
828 | const struct GNUNET_HashCode *key); | ||
651 | 829 | ||
652 | /** | 830 | /** |
653 | * Enter a room to send and receive messages through a <b>door</b> opened using #GNUNET_MESSENGER_open_room. | 831 | * Enter a room to send and receive messages through a <b>door</b> opened using #GNUNET_MESSENGER_open_room. |
@@ -662,13 +840,14 @@ GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, const struct | |||
662 | * | 840 | * |
663 | * ( 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. ) |
664 | * | 842 | * |
665 | * @param[in/out] handle Messenger handle to use | 843 | * @param[in,out] handle Messenger handle to use |
666 | * @param[in] door Peer identity of an open <b>door</b> | 844 | * @param[in] door Peer identity of an open <b>door</b> |
667 | * @param[in] key Hash identifying the port | 845 | * @param[in] key Hash identifying the port |
668 | * @return Room handle, NULL on error | 846 | * @return Room handle, NULL on error |
669 | */ | 847 | */ |
670 | struct GNUNET_MESSENGER_Room* | 848 | struct GNUNET_MESSENGER_Room* |
671 | GNUNET_MESSENGER_enter_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_PeerIdentity *door, | 849 | GNUNET_MESSENGER_enter_room (struct GNUNET_MESSENGER_Handle *handle, |
850 | const struct GNUNET_PeerIdentity *door, | ||
672 | const struct GNUNET_HashCode *key); | 851 | const struct GNUNET_HashCode *key); |
673 | 852 | ||
674 | /** | 853 | /** |
@@ -678,7 +857,7 @@ GNUNET_MESSENGER_enter_room (struct GNUNET_MESSENGER_Handle *handle, const struc | |||
678 | * ( 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 |
679 | * or open the room on their own. ) | 858 | * or open the room on their own. ) |
680 | * | 859 | * |
681 | * @param[in/out] room Room handle | 860 | * @param[in,out] room Room handle |
682 | */ | 861 | */ |
683 | void | 862 | void |
684 | GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); | 863 | GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); |
@@ -695,8 +874,10 @@ GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); | |||
695 | * @return Amount of rooms iterated | 874 | * @return Amount of rooms iterated |
696 | */ | 875 | */ |
697 | int | 876 | int |
698 | GNUNET_MESSENGER_find_rooms (const struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_MESSENGER_Contact *contact, | 877 | GNUNET_MESSENGER_find_rooms (const struct GNUNET_MESSENGER_Handle *handle, |
699 | GNUNET_MESSENGER_MemberCallback callback, void *cls); | 878 | const struct GNUNET_MESSENGER_Contact *contact, |
879 | GNUNET_MESSENGER_MemberCallback callback, | ||
880 | void *cls); | ||
700 | 881 | ||
701 | /** | 882 | /** |
702 | * Get the key of a given <i>room</i>. | 883 | * Get the key of a given <i>room</i>. |
@@ -717,7 +898,22 @@ GNUNET_MESSENGER_room_get_key (const struct GNUNET_MESSENGER_Room *room); | |||
717 | * @return Contact handle, NULL otherwise | 898 | * @return Contact handle, NULL otherwise |
718 | */ | 899 | */ |
719 | const struct GNUNET_MESSENGER_Contact* | 900 | const struct GNUNET_MESSENGER_Contact* |
720 | GNUNET_MESSENGER_get_sender (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); | 901 | GNUNET_MESSENGER_get_sender (const struct GNUNET_MESSENGER_Room *room, |
902 | const struct GNUNET_HashCode *hash); | ||
903 | |||
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); | ||
721 | 917 | ||
722 | /** | 918 | /** |
723 | * Get the name used by the <i>contact</i>. | 919 | * Get the name used by the <i>contact</i>. |
@@ -726,19 +922,31 @@ GNUNET_MESSENGER_get_sender (const struct GNUNET_MESSENGER_Room *room, const str | |||
726 | * @return Name of <i>contact</i> or NULL | 922 | * @return Name of <i>contact</i> or NULL |
727 | */ | 923 | */ |
728 | const char* | 924 | const char* |
729 | GNUNET_MESSENGER_contact_get_name (const struct GNUNET_MESSENGER_Contact *contact); | 925 | GNUNET_MESSENGER_contact_get_name (const struct |
926 | GNUNET_MESSENGER_Contact *contact); | ||
730 | 927 | ||
731 | /** | 928 | /** |
732 | * 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. |
733 | * | 930 | * |
734 | * @param[in] contact Contact handle | 931 | * @param[in] contact Contact handle |
735 | * @return Public key of the ego used by <i>contact</i> or NULL | 932 | * @return Public key used by <i>contact</i> or NULL |
933 | */ | ||
934 | const struct GNUNET_CRYPTO_PublicKey* | ||
935 | GNUNET_MESSENGER_contact_get_key (const struct | ||
936 | GNUNET_MESSENGER_Contact *contact); | ||
937 | |||
938 | /** | ||
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 | ||
736 | */ | 943 | */ |
737 | const struct GNUNET_IDENTITY_PublicKey* | 944 | size_t |
738 | GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact); | 945 | GNUNET_MESSENGER_contact_get_id (const struct |
946 | GNUNET_MESSENGER_Contact *contact); | ||
739 | 947 | ||
740 | /** | 948 | /** |
741 | * Send a <i>message</i> into a </i>room</i>. If you opened the <i>room</i> all entered members will receive the | 949 | * Send a <i>message</i> into a <i>room</i>. If you opened the <i>room</i> all entered members will receive the |
742 | * <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 |
743 | * <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 |
744 | * as long as the <i>message</i> is unknown to them. | 952 | * as long as the <i>message</i> is unknown to them. |
@@ -751,13 +959,30 @@ GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact | |||
751 | * | 959 | * |
752 | * 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. |
753 | * | 961 | * |
754 | * @param[in/out] room Room handle | 962 | * @param[in,out] room Room handle |
755 | * @param[in] message New message to send | 963 | * @param[in,out] message New message to send |
756 | * @param[in] contact Contact or NULL | 964 | * @param[in] contact Contact or NULL |
757 | */ | 965 | */ |
758 | void | 966 | void |
759 | GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, const struct GNUNET_MESSENGER_Message *message, | 967 | GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, |
760 | const struct GNUNET_MESSENGER_Contact* contact); | 968 | const struct GNUNET_MESSENGER_Message *message, |
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); | ||
761 | 986 | ||
762 | /** | 987 | /** |
763 | * 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>. |
@@ -767,7 +992,8 @@ GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, const struct | |||
767 | * @return Message struct or NULL if no message with that hash is known | 992 | * @return Message struct or NULL if no message with that hash is known |
768 | */ | 993 | */ |
769 | const struct GNUNET_MESSENGER_Message* | 994 | const struct GNUNET_MESSENGER_Message* |
770 | GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); | 995 | GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, |
996 | const struct GNUNET_HashCode *hash); | ||
771 | 997 | ||
772 | /** | 998 | /** |
773 | * Iterates through all members of a given <i>room</i> and calls a selected <i>callback</i> | 999 | * Iterates through all members of a given <i>room</i> and calls a selected <i>callback</i> |
@@ -780,8 +1006,25 @@ GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, const st | |||
780 | * @return Amount of members iterated | 1006 | * @return Amount of members iterated |
781 | */ | 1007 | */ |
782 | int | 1008 | int |
783 | GNUNET_MESSENGER_iterate_members (struct GNUNET_MESSENGER_Room *room, GNUNET_MESSENGER_MemberCallback callback, | 1009 | GNUNET_MESSENGER_iterate_members (struct GNUNET_MESSENGER_Room *room, |
784 | void* cls); | 1010 | GNUNET_MESSENGER_MemberCallback callback, |
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); | ||
785 | 1028 | ||
786 | #if 0 /* keep Emacsens' auto-indent happy */ | 1029 | #if 0 /* keep Emacsens' auto-indent happy */ |
787 | { | 1030 | { |