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