diff options
Diffstat (limited to 'src/include/gnunet_chat_service.h')
| -rw-r--r-- | src/include/gnunet_chat_service.h | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/src/include/gnunet_chat_service.h b/src/include/gnunet_chat_service.h new file mode 100644 index 0000000..938b434 --- /dev/null +++ b/src/include/gnunet_chat_service.h @@ -0,0 +1,253 @@ +/* + This file is part of GNUnet. + (C) 2009, 2011 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. +*/ + +/** + * @file include/gnunet_chat_service.h + * @brief API for chatting via GNUnet + * @author Christian Grothoff + * @author Nathan Evans + * @author Vitaly Minko + */ + +#ifndef GNUNET_CHAT_SERVICE_H +#define GNUNET_CHAT_SERVICE_H + +#include "gnunet_util_lib.h" + +#ifdef __cplusplus +extern "C" +{ +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + + +#define GNUNET_CHAT_VERSION 0x00000003 +#define MAX_MESSAGE_LENGTH (32 * 1024) + +/** + * Options for messaging. Compatible options can be OR'ed together. + */ +enum GNUNET_CHAT_MsgOptions +{ + /** + * No special options. + */ + GNUNET_CHAT_MSG_OPTION_NONE = 0, + + /** + * Encrypt the message so that only the receiver can decrypt it. + */ + GNUNET_CHAT_MSG_PRIVATE = 1, + + /** + * Hide the identity of the sender. + */ + GNUNET_CHAT_MSG_ANONYMOUS = 2, + + /** + * Sign the content, authenticating the sender (using the provided private + * key, which may represent a pseudonym). + */ + GNUNET_CHAT_MSG_AUTHENTICATED = 4, + + /** + * Require signed acknowledgment before completing delivery (and of course, + * only acknowledge if delivery is guaranteed). + */ + GNUNET_CHAT_MSG_ACKNOWLEDGED = 8, + + /** + * Authenticate for the receiver, but ensure that receiver cannot prove + * authenticity to third parties later. (not yet implemented) + */ + GNUNET_CHAT_MSG_OFF_THE_RECORD = 16, + +}; + +/** + * Handle for a (joined) chat room. + */ +struct GNUNET_CHAT_Room; + +/** + * Callback used for notification that we have joined the room. + * + * @param cls closure + * @return GNUNET_OK + */ +typedef int (*GNUNET_CHAT_JoinCallback) (void *cls); + +/** + * Callback used for notification about incoming messages. + * + * @param cls closure + * @param room in which room was the message received? + * @param sender what is the ID of the sender? (maybe NULL) + * @param member_info information about the joining member + * @param message the message text + * @param timestamp when was the message sent? + * @param options options for the message + * @return GNUNET_OK to accept the message now, GNUNET_NO to + * accept (but user is away), GNUNET_SYSERR to signal denied delivery + */ +typedef int (*GNUNET_CHAT_MessageCallback) (void *cls, + struct GNUNET_CHAT_Room * room, + const GNUNET_HashCode * sender, + const struct + GNUNET_CONTAINER_MetaData * + member_info, const char *message, + struct GNUNET_TIME_Absolute + timestamp, + enum GNUNET_CHAT_MsgOptions + options); + +/** + * Callback used for notification that another room member has joined or left. + * + * @param cls closure + * @param member_info will be non-null if the member is joining, NULL if he is + * leaving + * @param member_id hash of public key of the user (for unique identification) + * @param options what types of messages is this member willing to receive? + * @return GNUNET_OK + */ +typedef int (*GNUNET_CHAT_MemberListCallback) (void *cls, + const struct + GNUNET_CONTAINER_MetaData * + member_info, + const struct + GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded + * member_id, + enum GNUNET_CHAT_MsgOptions + options); + +/** + * Callback used for message delivery confirmations. + * + * @param cls closure + * @param room in which room was the message received? + * @param orig_seq_number sequence number of the original message + * @param timestamp when was the message received? + * @param receiver who is confirming the receipt? + * @return GNUNET_OK to continue, GNUNET_SYSERR to refuse processing further + * confirmations from anyone for this message + */ +typedef int (*GNUNET_CHAT_MessageConfirmation) (void *cls, + struct GNUNET_CHAT_Room * room, + uint32_t orig_seq_number, + struct GNUNET_TIME_Absolute + timestamp, + const GNUNET_HashCode * + receiver); + +/** + * Join a chat room. + * + * @param cfg configuration + * @param nick_name nickname of the user joining (used to + * determine which public key to use); + * the nickname should probably also + * be used in the member_info (as "EXTRACTOR_TITLE") + * @param member_info information about the joining member + * @param room_name name of the room + * @param msg_options message options of the joining user + * @param joinCallback which function to call when we've joined the room + * @param join_cls argument to callback + * @param messageCallback which function to call if a message has + * been received? + * @param message_cls argument to callback + * @param memberCallback which function to call for join/leave notifications + * @param member_cls argument to callback + * @param confirmationCallback which function to call for confirmations + * (maybe NULL) + * @param confirmation_cls argument to callback + * @param me member ID (pseudonym) + * @return NULL on error + */ +struct GNUNET_CHAT_Room * +GNUNET_CHAT_join_room (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *nick_name, + struct GNUNET_CONTAINER_MetaData *member_info, + const char *room_name, + enum GNUNET_CHAT_MsgOptions msg_options, + GNUNET_CHAT_JoinCallback joinCallback, void *join_cls, + GNUNET_CHAT_MessageCallback messageCallback, + void *message_cls, + GNUNET_CHAT_MemberListCallback memberCallback, + void *member_cls, + GNUNET_CHAT_MessageConfirmation confirmationCallback, + void *confirmation_cls, GNUNET_HashCode * me); + +/** + * Send a message. + * + * @param room handle for the chat room + * @param message message to be sent + * @param options options for the message + * @param receiver use NULL to send to everyone in the room + * @param sequence_number where to write the sequence id of the message + */ +void +GNUNET_CHAT_send_message (struct GNUNET_CHAT_Room *room, const char *message, + enum GNUNET_CHAT_MsgOptions options, + const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded + *receiver, uint32_t * sequence_number); + + +/** + * Leave a chat room. + */ +void +GNUNET_CHAT_leave_room (struct GNUNET_CHAT_Room *chat_room); + + +#if 0 +/* these are not yet implemented / supported */ +/** + * Callback function to iterate over rooms. + * + * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration + */ +typedef int (*GNUNET_CHAT_RoomIterator) (const char *room, const char *topic, + void *cls); + +/** + * List all of the (publically visible) chat rooms. + * @return number of rooms on success, GNUNET_SYSERR if iterator aborted + */ +int +GNUNET_CHAT_list_rooms (struct GNUNET_GE_Context *ectx, + struct GNUNET_GC_Configuration *cfg, + GNUNET_CHAT_RoomIterator it, void *cls); +#endif + + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + +#endif + +/* end of gnunet_chat_service.h */ |