2 This file is part of GNUnet.
3 (C) 2009, 2011 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_chat_service.h
23 * @brief API for chatting via GNUnet
24 * @author Christian Grothoff
25 * @author Nathan Evans
26 * @author Vitaly Minko
29 #ifndef GNUNET_CHAT_SERVICE_H
30 #define GNUNET_CHAT_SERVICE_H
32 #include "gnunet_util_lib.h"
37 #if 0 /* keep Emacsens' auto-indent happy */
43 #define GNUNET_CHAT_VERSION 0x00000003
44 #define MAX_MESSAGE_LENGTH (32 * 1024)
47 * Options for messaging. Compatible options can be OR'ed together.
49 enum GNUNET_CHAT_MsgOptions
54 GNUNET_CHAT_MSG_OPTION_NONE = 0,
57 * Encrypt the message so that only the receiver can decrypt it.
59 GNUNET_CHAT_MSG_PRIVATE = 1,
62 * Hide the identity of the sender.
64 GNUNET_CHAT_MSG_ANONYMOUS = 2,
67 * Sign the content, authenticating the sender (using the provided private
68 * key, which may represent a pseudonym).
70 GNUNET_CHAT_MSG_AUTHENTICATED = 4,
73 * Require signed acknowledgment before completing delivery (and of course,
74 * only acknowledge if delivery is guaranteed).
76 GNUNET_CHAT_MSG_ACKNOWLEDGED = 8,
79 * Authenticate for the receiver, but ensure that receiver cannot prove
80 * authenticity to third parties later. (not yet implemented)
82 GNUNET_CHAT_MSG_OFF_THE_RECORD = 16,
87 * Handle for a (joined) chat room.
89 struct GNUNET_CHAT_Room;
92 * Callback used for notification that we have joined the room.
97 typedef int (*GNUNET_CHAT_JoinCallback) (void *cls);
100 * Callback used for notification about incoming messages.
103 * @param room in which room was the message received?
104 * @param sender what is the ID of the sender? (maybe NULL)
105 * @param member_info information about the joining member
106 * @param message the message text
107 * @param timestamp when was the message sent?
108 * @param options options for the message
109 * @return GNUNET_OK to accept the message now, GNUNET_NO to
110 * accept (but user is away), GNUNET_SYSERR to signal denied delivery
112 typedef int (*GNUNET_CHAT_MessageCallback) (void *cls,
113 struct GNUNET_CHAT_Room * room,
114 const struct GNUNET_HashCode * sender,
116 GNUNET_CONTAINER_MetaData *
117 member_info, const char *message,
118 struct GNUNET_TIME_Absolute
120 enum GNUNET_CHAT_MsgOptions
124 * Callback used for notification that another room member has joined or left.
127 * @param member_info will be non-null if the member is joining, NULL if he is
129 * @param member_id hash of public key of the user (for unique identification)
130 * @param options what types of messages is this member willing to receive?
133 typedef int (*GNUNET_CHAT_MemberListCallback) (void *cls,
135 GNUNET_CONTAINER_MetaData *
138 GNUNET_CRYPTO_RsaPublicKey
140 enum GNUNET_CHAT_MsgOptions
144 * Callback used for message delivery confirmations.
147 * @param room in which room was the message received?
148 * @param orig_seq_number sequence number of the original message
149 * @param timestamp when was the message received?
150 * @param receiver who is confirming the receipt?
151 * @return GNUNET_OK to continue, GNUNET_SYSERR to refuse processing further
152 * confirmations from anyone for this message
154 typedef int (*GNUNET_CHAT_MessageConfirmation) (void *cls,
155 struct GNUNET_CHAT_Room * room,
156 uint32_t orig_seq_number,
157 struct GNUNET_TIME_Absolute
159 const struct GNUNET_HashCode *
165 * @param cfg configuration
166 * @param nick_name nickname of the user joining (used to
167 * determine which public key to use);
168 * the nickname should probably also
169 * be used in the member_info (as "EXTRACTOR_TITLE")
170 * @param member_info information about the joining member
171 * @param room_name name of the room
172 * @param msg_options message options of the joining user
173 * @param joinCallback which function to call when we've joined the room
174 * @param join_cls argument to callback
175 * @param messageCallback which function to call if a message has
177 * @param message_cls argument to callback
178 * @param memberCallback which function to call for join/leave notifications
179 * @param member_cls argument to callback
180 * @param confirmationCallback which function to call for confirmations
182 * @param confirmation_cls argument to callback
183 * @param me member ID (pseudonym)
184 * @return NULL on error
186 struct GNUNET_CHAT_Room *
187 GNUNET_CHAT_join_room (const struct GNUNET_CONFIGURATION_Handle *cfg,
188 const char *nick_name,
189 struct GNUNET_CONTAINER_MetaData *member_info,
190 const char *room_name,
191 enum GNUNET_CHAT_MsgOptions msg_options,
192 GNUNET_CHAT_JoinCallback joinCallback, void *join_cls,
193 GNUNET_CHAT_MessageCallback messageCallback,
195 GNUNET_CHAT_MemberListCallback memberCallback,
197 GNUNET_CHAT_MessageConfirmation confirmationCallback,
198 void *confirmation_cls, struct GNUNET_HashCode * me);
203 * @param room handle for the chat room
204 * @param message message to be sent
205 * @param options options for the message
206 * @param receiver use NULL to send to everyone in the room
207 * @param sequence_number where to write the sequence id of the message
210 GNUNET_CHAT_send_message (struct GNUNET_CHAT_Room *room, const char *message,
211 enum GNUNET_CHAT_MsgOptions options,
212 const struct GNUNET_CRYPTO_RsaPublicKey
213 *receiver, uint32_t * sequence_number);
220 GNUNET_CHAT_leave_room (struct GNUNET_CHAT_Room *chat_room);
224 /* these are not yet implemented / supported */
226 * Callback function to iterate over rooms.
228 * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration
230 typedef int (*GNUNET_CHAT_RoomIterator) (const char *room, const char *topic,
234 * List all of the (publically visible) chat rooms.
235 * @return number of rooms on success, GNUNET_SYSERR if iterator aborted
238 GNUNET_CHAT_list_rooms (struct GNUNET_GE_Context *ectx,
239 struct GNUNET_GC_Configuration *cfg,
240 GNUNET_CHAT_RoomIterator it, void *cls);
244 #if 0 /* keep Emacsens' auto-indent happy */
253 /* end of gnunet_chat_service.h */