aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_messenger_service.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_messenger_service.h')
-rw-r--r--src/include/gnunet_messenger_service.h405
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 */
76struct GNUNET_MESSENGER_Contact; 76struct GNUNET_MESSENGER_Contact;
77 77
78GNUNET_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 */
84struct 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
97GNUNET_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 */
105struct 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
118GNUNET_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
215struct GNUNET_MESSENGER_MessageInfo 277struct 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 */
522struct 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 */
541struct 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 */
555struct 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 */
584struct 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 */
462struct GNUNET_MESSENGER_MessageBody 600struct 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 */
504enum GNUNET_MESSENGER_MessageFlags 646enum 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 */
529typedef void 688enum 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 */
545typedef void 715typedef 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 */
560typedef int 735typedef 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 */
576struct GNUNET_MESSENGER_Handle* 752struct GNUNET_MESSENGER_Handle*
577GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *name, 753GNUNET_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 */
592int
593GNUNET_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 */
600void 764void
601GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); 765GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle);
@@ -610,27 +774,40 @@ const char*
610GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle); 774GNUNET_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 */
621int 784enum GNUNET_GenericReturnValue
622GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, const char *name); 785GNUNET_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 */
630const struct GNUNET_IDENTITY_PublicKey* 794const struct GNUNET_CRYPTO_PublicKey*
631GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); 795GNUNET_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 */
806enum GNUNET_GenericReturnValue
807GNUNET_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 */
649struct GNUNET_MESSENGER_Room* 826struct GNUNET_MESSENGER_Room*
650GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_HashCode *key); 827GNUNET_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 */
670struct GNUNET_MESSENGER_Room* 848struct GNUNET_MESSENGER_Room*
671GNUNET_MESSENGER_enter_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_PeerIdentity *door, 849GNUNET_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 */
683void 862void
684GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); 863GNUNET_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 */
697int 876int
698GNUNET_MESSENGER_find_rooms (const struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_MESSENGER_Contact *contact, 877GNUNET_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 */
719const struct GNUNET_MESSENGER_Contact* 900const struct GNUNET_MESSENGER_Contact*
720GNUNET_MESSENGER_get_sender (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); 901GNUNET_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 */
914const struct GNUNET_MESSENGER_Contact*
915GNUNET_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 */
728const char* 924const char*
729GNUNET_MESSENGER_contact_get_name (const struct GNUNET_MESSENGER_Contact *contact); 925GNUNET_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 */
934const struct GNUNET_CRYPTO_PublicKey*
935GNUNET_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 */
737const struct GNUNET_IDENTITY_PublicKey* 944size_t
738GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact); 945GNUNET_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 */
758void 966void
759GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, const struct GNUNET_MESSENGER_Message *message, 967GNUNET_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 */
982void
983GNUNET_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 */
769const struct GNUNET_MESSENGER_Message* 994const struct GNUNET_MESSENGER_Message*
770GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); 995GNUNET_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 */
782int 1008int
783GNUNET_MESSENGER_iterate_members (struct GNUNET_MESSENGER_Room *room, GNUNET_MESSENGER_MemberCallback callback, 1009GNUNET_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 */
1025void
1026GNUNET_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{