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 *
 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,
 194                        void *message_cls,
 195                        GNUNET_CHAT_MemberListCallback memberCallback,
 196                        void *member_cls,
 197                        GNUNET_CHAT_MessageConfirmation confirmationCallback,
 198                        void *confirmation_cls, GNUNET_HashCode * me);
 199
 200 /**
 201  * Send a message.
 202  *
 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
 208  */
 209 void
 210 GNUNET_CHAT_send_message (struct GNUNET_CHAT_Room *room, const char *message,
 211                           enum GNUNET_CHAT_MsgOptions options,
 212                           const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded
 213                           *receiver, uint32_t * sequence_number);
 214
 215
 216 /**
 217  * Leave a chat room.
 218  */
 219 void
 220 GNUNET_CHAT_leave_room (struct GNUNET_CHAT_Room *chat_room);
 221
 222
 223 #if 0
 224 /* these are not yet implemented / supported */
 225 /**
 226  * Callback function to iterate over rooms.
 227  *
 228  * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration
 229  */
 230 typedef int (*GNUNET_CHAT_RoomIterator) (const char *room, const char *topic,
 231                                          void *cls);
 232
 233 /**
 234  * List all of the (publically visible) chat rooms.
 235  * @return number of rooms on success, GNUNET_SYSERR if iterator aborted
 236  */
 237 int
 238 GNUNET_CHAT_list_rooms (struct GNUNET_GE_Context *ectx,
 239                         struct GNUNET_GC_Configuration *cfg,
 240                         GNUNET_CHAT_RoomIterator it, void *cls);
 241 #endif
 242
 243
 244 #if 0                           /* keep Emacsens' auto-indent happy */
 245 {
 246 #endif
 247 #ifdef __cplusplus
 248 }
 249 #endif
 250
 251 #endif
 252
 253 /* end of gnunet_chat_service.h */