gnunet/src/include/gnunet_chat_service.h

/*
     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 */