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 GNUNET_CONTAINER_MetaData *member_info,
 116                                             const char *message,
 117                                             struct GNUNET_TIME_Absolute timestamp,
 118                                             enum GNUNET_CHAT_MsgOptions options);
 119
 120 /**
 121  * Callback used for notification that another room member has joined or left.
 122  *
 123  * @param cls closure
 124  * @param member_info will be non-null if the member is joining, NULL if he is
 125  *        leaving
 126  * @param member_id hash of public key of the user (for unique identification)
 127  * @param options what types of messages is this member willing to receive?
 128  * @return GNUNET_OK
 129  */
 130 typedef int (*GNUNET_CHAT_MemberListCallback) (void *cls,
 131                                                const struct GNUNET_CONTAINER_MetaData *member_info,
 132                                                const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *member_id,
 133                                                enum GNUNET_CHAT_MsgOptions options);
 134
 135 /**
 136  * Callback used for message delivery confirmations.
 137  *
 138  * @param cls closure
 139  * @param room in which room was the message received?
 140  * @param orig_seq_number sequence number of the original message
 141  * @param timestamp when was the message received?
 142  * @param receiver who is confirming the receipt?
 143  * @return GNUNET_OK to continue, GNUNET_SYSERR to refuse processing further
 144  *         confirmations from anyone for this message
 145  */
 146 typedef int (*GNUNET_CHAT_MessageConfirmation) (void *cls,
 147                                                 struct GNUNET_CHAT_Room *room,
 148                                                 uint32_t orig_seq_number,
 149                                                 struct GNUNET_TIME_Absolute timestamp,
 150                                                 const GNUNET_HashCode *receiver);
 151
 152 /**
 153  * Join a chat room.
 154  *
 155  * @param cfg configuration
 156  * @param nick_name nickname of the user joining (used to
 157  *                  determine which public key to use);
 158  *                  the nickname should probably also
 159  *                  be used in the member_info (as "EXTRACTOR_TITLE")
 160  * @param member_info information about the joining member
 161  * @param room_name name of the room
 162  * @param msg_options message options of the joining user
 163  * @param joinCallback which function to call when we've joined the room
 164  * @param join_cls argument to callback
 165  * @param messageCallback which function to call if a message has
 166  *        been received?
 167  * @param message_cls argument to callback
 168  * @param memberCallback which function to call for join/leave notifications
 169  * @param member_cls argument to callback
 170  * @param confirmationCallback which function to call for confirmations
 171  *        (maybe NULL)
 172  * @param confirmation_cls argument to callback
 173  * @param me member ID (pseudonym)
 174  * @return NULL on error
 175  */
 176 struct GNUNET_CHAT_Room *
 177 GNUNET_CHAT_join_room (const struct GNUNET_CONFIGURATION_Handle *cfg,
 178                        const char *nick_name,
 179                        struct GNUNET_CONTAINER_MetaData *member_info,
 180                        const char *room_name,
 181                        enum GNUNET_CHAT_MsgOptions msg_options,
 182                        GNUNET_CHAT_JoinCallback joinCallback,
 183                        void *join_cls,
 184                        GNUNET_CHAT_MessageCallback messageCallback,
 185                        void *message_cls,
 186                        GNUNET_CHAT_MemberListCallback memberCallback,
 187                        void *member_cls,
 188                        GNUNET_CHAT_MessageConfirmation confirmationCallback,
 189                        void *confirmation_cls,
 190                        GNUNET_HashCode *me);
 191
 192 /**
 193  * Send a message.
 194  *
 195  * @param room handle for the chat room
 196  * @param message message to be sent
 197  * @param options options for the message
 198  * @param receiver use NULL to send to everyone in the room
 199  * @param sequence_number where to write the sequence id of the message
 200  */
 201 void
 202 GNUNET_CHAT_send_message (struct GNUNET_CHAT_Room *room,
 203                           const char *message,
 204                           enum GNUNET_CHAT_MsgOptions options,
 205                           const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *receiver,
 206                           uint32_t *sequence_number);
 207
 208
 209 /**
 210  * Leave a chat room.
 211  */
 212 void
 213 GNUNET_CHAT_leave_room (struct GNUNET_CHAT_Room *chat_room);
 214
 215
 216 #if 0
 217 /* these are not yet implemented / supported */
 218 /**
 219  * Callback function to iterate over rooms.
 220  *
 221  * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration
 222  */
 223 typedef int (*GNUNET_CHAT_RoomIterator) (const char *room,
 224                                          const char *topic, void *cls);
 225
 226 /**
 227  * List all of the (publically visible) chat rooms.
 228  * @return number of rooms on success, GNUNET_SYSERR if iterator aborted
 229  */
 230 int GNUNET_CHAT_list_rooms (struct GNUNET_GE_Context *ectx,
 231                             struct GNUNET_GC_Configuration *cfg,
 232                             GNUNET_CHAT_RoomIterator it, void *cls);
 233 #endif
 234
 235
 236 #if 0                           /* keep Emacsens' auto-indent happy */
 237 {
 238 #endif
 239 #ifdef __cplusplus
 240 }
 241 #endif
 242
 243 #endif
 244
 245 /* end of gnunet_chat_service.h */