src/include/gnunet_chat_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009, 2011 Christian Grothoff (and other contributing authors)
   4
   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.
   9
  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.
  14
  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.
  19 */
  20
  21 /**
  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
  27  */
  28
  29 #ifndef GNUNET_CHAT_SERVICE_H
  30 #define GNUNET_CHAT_SERVICE_H
  31
  32 #include "gnunet_util_lib.h"
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #if 0                           /* keep Emacsens' auto-indent happy */
  38 }
  39 #endif
  40 #endif
  41
  42
  43 #define GNUNET_CHAT_VERSION 0x00000003
  44 #define MAX_MESSAGE_LENGTH (32 * 1024)
  45
  46 /**
  47  * Options for messaging.  Compatible options can be OR'ed together.
  48  */
  49 enum GNUNET_CHAT_MsgOptions
  50 {
  51     /**
  52      * No special options.
  53      */
  54   GNUNET_CHAT_MSG_OPTION_NONE = 0,
  55
  56     /**
  57      * Encrypt the message so that only the receiver can decrypt it.
  58      */
  59   GNUNET_CHAT_MSG_PRIVATE = 1,
  60
  61     /**
  62      * Hide the identity of the sender.
  63      */
  64   GNUNET_CHAT_MSG_ANONYMOUS = 2,
  65
  66     /**
  67      * Sign the content, authenticating the sender (using the provided private
  68      * key, which may represent a pseudonym).
  69      */
  70   GNUNET_CHAT_MSG_AUTHENTICATED = 4,
  71
  72     /**
  73      * Require signed acknowledgment before completing delivery (and of course,
  74      * only acknowledge if delivery is guaranteed).
  75      */
  76   GNUNET_CHAT_MSG_ACKNOWLEDGED = 8,
  77
  78     /**
  79      * Authenticate for the receiver, but ensure that receiver cannot prove
  80      * authenticity to third parties later. (not yet implemented)
  81      */
  82   GNUNET_CHAT_MSG_OFF_THE_RECORD = 16,
  83
  84 };
  85
  86 /**
  87  * Handle for a (joined) chat room.
  88  */
  89 struct GNUNET_CHAT_Room;
  90
  91 /**
  92  * Callback used for notification that we have joined the room.
  93  *
  94  * @param cls closure
  95  * @return GNUNET_OK
  96  */
  97 typedef int (*GNUNET_CHAT_JoinCallback) (void *cls);
  98
  99 /**
 100  * Callback used for notification about incoming messages.
 101  *
 102  * @param cls closure
 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
 111  */
 112 typedef int (*GNUNET_CHAT_MessageCallback) (void *cls,
 113                                             struct GNUNET_CHAT_Room * room,
 114                                             const GNUNET_HashCode * sender,
 115                                             const struct
 116                                             GNUNET_CONTAINER_MetaData *
 117                                             member_info, const char *message,
 118                                             struct GNUNET_TIME_Absolute
 119                                             timestamp,
 120                                             enum GNUNET_CHAT_MsgOptions
 121                                             options);
 122
 123 /**
 124  * Callback used for notification that another room member has joined or left.
 125  *
 126  * @param cls closure
 127  * @param member_info will be non-null if the member is joining, NULL if he is
 128  *        leaving
 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?
 131  * @return GNUNET_OK
 132  */
 133 typedef int (*GNUNET_CHAT_MemberListCallback) (void *cls,
 134                                                const struct
 135                                                GNUNET_CONTAINER_MetaData *
 136                                                member_info,
 137                                                const struct
 138                                                GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded
 139                                                * member_id,
 140                                                enum GNUNET_CHAT_MsgOptions
 141                                                options);
 142
 143 /**
 144  * Callback used for message delivery confirmations.
 145  *
 146  * @param cls closure
 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
 153  */
 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
 158                                                 timestamp,
 159                                                 const GNUNET_HashCode *
 160                                                 receiver);
 161
 162 /**
 163  * Join a chat room.
 164  *
 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
 176  *        been received?
 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
 181  *        (maybe NULL)
 182  * @param confirmation_cls argument to callback
 183  * @param me member ID (pseudonym)
 184  * @return NULL on error
 185  */
 186 struct GNUNET_CHAT_Room *GNUNET_CHAT_join_room (const struct
 187                                                 GNUNET_CONFIGURATION_Handle
 188                                                 *cfg, const char *nick_name,
 189                                                 struct GNUNET_CONTAINER_MetaData
 190                                                 *member_info,
 191                                                 const char *room_name,
 192                                                 enum GNUNET_CHAT_MsgOptions
 193                                                 msg_options,
 194                                                 GNUNET_CHAT_JoinCallback
 195                                                 joinCallback, void *join_cls,
 196                                                 GNUNET_CHAT_MessageCallback
 197                                                 messageCallback,
 198                                                 void *message_cls,
 199                                                 GNUNET_CHAT_MemberListCallback
 200                                                 memberCallback,
 201                                                 void *member_cls,
 202                                                 GNUNET_CHAT_MessageConfirmation
 203                                                 confirmationCallback,
 204                                                 void *confirmation_cls,
 205                                                 GNUNET_HashCode * me);
 206
 207 /**
 208  * Send a message.
 209  *
 210  * @param room handle for the chat room
 211  * @param message message to be sent
 212  * @param options options for the message
 213  * @param receiver use NULL to send to everyone in the room
 214  * @param sequence_number where to write the sequence id of the message
 215  */
 216 void GNUNET_CHAT_send_message (struct GNUNET_CHAT_Room *room,
 217                                const char *message,
 218                                enum GNUNET_CHAT_MsgOptions options,
 219                                const struct
 220                                GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded
 221                                *receiver, uint32_t * sequence_number);
 222
 223
 224 /**
 225  * Leave a chat room.
 226  */
 227 void GNUNET_CHAT_leave_room (struct GNUNET_CHAT_Room *chat_room);
 228
 229
 230 #if 0
 231 /* these are not yet implemented / supported */
 232 /**
 233  * Callback function to iterate over rooms.
 234  *
 235  * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration
 236  */
 237 typedef int (*GNUNET_CHAT_RoomIterator) (const char *room, const char *topic,
 238                                          void *cls);
 239
 240 /**
 241  * List all of the (publically visible) chat rooms.
 242  * @return number of rooms on success, GNUNET_SYSERR if iterator aborted
 243  */
 244 int GNUNET_CHAT_list_rooms (struct GNUNET_GE_Context *ectx,
 245                             struct GNUNET_GC_Configuration *cfg,
 246                             GNUNET_CHAT_RoomIterator it, void *cls);
 247 #endif
 248
 249
 250 #if 0                           /* keep Emacsens' auto-indent happy */
 251 {
 252 #endif
 253 #ifdef __cplusplus
 254 }
 255 #endif
 256
 257 #endif
 258
 259 /* end of gnunet_chat_service.h */