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.h332
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
97GNUNET_NETWORK_STRUCT_END 97GNUNET_NETWORK_STRUCT_END
98 98
99GNUNET_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
257struct GNUNET_MESSENGER_MessageInfo 277struct 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 */
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/**
502 * The unified body of a #GNUNET_MESSENGER_Message. 598 * The unified body of a #GNUNET_MESSENGER_Message.
503 */ 599 */
504struct GNUNET_MESSENGER_MessageBody 600struct 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 */
546enum GNUNET_MESSENGER_MessageFlags 646enum 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 */
571typedef void 688enum 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
588typedef void 715typedef 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 */
604typedef int 735typedef 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 */
621struct GNUNET_MESSENGER_Handle* 752struct GNUNET_MESSENGER_Handle*
622GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, 753GNUNET_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 */
640int
641GNUNET_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 */
648void 764void
649GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); 765GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle);
@@ -658,15 +774,14 @@ const char*
658GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle); 774GNUNET_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 */
669int 784enum GNUNET_GenericReturnValue
670GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, 785GNUNET_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 */
679const struct GNUNET_IDENTITY_PublicKey* 794const struct GNUNET_CRYPTO_PublicKey*
680GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); 795GNUNET_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 */
806enum GNUNET_GenericReturnValue
807GNUNET_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 */
734void 862void
735GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); 863GNUNET_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 */
914const struct GNUNET_MESSENGER_Contact*
915GNUNET_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 */
782const char* 924const char*
783GNUNET_MESSENGER_contact_get_name (const struct GNUNET_MESSENGER_Contact *contact); 925GNUNET_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 */
791const struct GNUNET_IDENTITY_PublicKey* 934const struct GNUNET_CRYPTO_PublicKey*
792GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact); 935GNUNET_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 */
944size_t
945GNUNET_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 */
812void 966void
813GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, 967GNUNET_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 */
982void
983GNUNET_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,
838int 1008int
839GNUNET_MESSENGER_iterate_members (struct GNUNET_MESSENGER_Room *room, 1009GNUNET_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 */
1025void
1026GNUNET_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{