InstantMessaging.idl

/**
 * @file   Messages.idl
 * @brief  Work with instant messaging. Note that all communication is designed to be via WebSocket interface.
 *
 * @author Vaclav Purchart
 */

#import <Structures.idl>

module kerio {
module jsonapi {
module webmail {
module im {

// -- Presence types --
typedef long MessageId;
typedef long ConversationId;
typedef string ContactId;


enum Status {
   available,
   offline,
   dnd,
   away,
   invisible
};

struct Presence {
   ContactId contactId;
   Status status;
   string text;
   UtcDateTime date;
};

typedef sequence<Presence> PresenceList;

// -- Conversations --

enum ConversationEvent {
   Created,  // when conversation id is created
   Updated,  // when message flows into conversation
   Delivered,  // when messages within this conversation were delivered
   Read  // when messages within this conversation has been read
};

typedef sequence<ContactId> ContactIdList;

struct Conversation {
   ConversationId conversationId;
   UtcDateTime lastActivity;  // used to find RECENT conversations
   MessageId sentLastDeliveredId;  // all higher ids are undelivered (user-specific - messages from me)
   MessageId sentLastReadId; // // all higher ids are undelivered (user-specific - messages from me)
   MessageId receivedLastReadId;  // all higher ids are undelivered (user-specific - message to me)
   long receivedUnreadCount;  // user-specific - message to me
   ContactIdList contacts;  // one for 1:1, more for groupchats
   ConversationEvent event;  // to notify other users/sessions about conversation activity
   boolean muted;
};

typedef sequence<Conversation> ConversationList;

// -- Messages --

enum MessageEvent {
   active,  // typing
   inactive  // stopped typing
};

struct Message {
   MessageId messageId;
   string text;
   MessageEvent event;
   ConversationId to;  // conversation ID
   ContactId from;
   UtcDateTime time;  // filled by server
};

typedef sequence<Message> MessageList;

interface im {

   // -- Presence types --

   /**
    * Every contact has its presence status updated on server according to contact activity or availability.
    * Retrieve presence for users.
    *
    * @param list - list of statuses of given contacts (or all non-offilne contacts if input array is empty)
    * @param contacts - (optional) list of all contacts
    */
   void getPresence(out PresenceList list, in kerio::web::KIdList contacts);

   /**
    * Subsribe for presence changes. Presence status of all users are returned and changes then continuously pushed into client.
    * Note that callback will be executed periodically as changes from server arrive.
    *
    * @param list - Presence status of all users. Offline users are always excluded. Missing means offline. (TODO)
    */
   void subscribePresence(out PresenceList list);

   /**
    * Update own presence. Server than resend such status to all interested clients (subscribed) as a Presence with current date.
    *
    * @param status - new user status to be set (online, offline, ...)
    * @param text - status text
    */
   void setPresence(in Status status, in string text);


   // -- Conversations --

   /**
    * Create new conversation (or return existing one)
    *
    * @param contacts - required conversation, one for 1:1, more for groupchats
    * @param conversation - created conversation
    */
   void createConversation(out Conversation conversation, in ContactIdList contacts);

   /**
    * It provides list of all conversations in which the current user participates and also subscribes for further changes.
    *
    * @param list - all conversations in which current user participes
    */
   void subscribeConversations(out ConversationList list);

   /**
    * Set conversation as (un)muted for the current user
    *
    * @param conversationId - conversation to be set
    * @param isMuted        - true = conversation will be muted
    */
   void muteConversation(in ConversationId conversationId, in boolean mute);

   /**
   * Set last read message in conversation for the current user
   *
   * @param conversationId - conversation to be set
   * @param messageId      - ID of last message which has been read
   */
   void readConversation(in ConversationId conversationId, in MessageId lastReadId);

   // -- Messages --

   /**
    * Returns ordered list of messages from single conversation. The list is always ordered by messageId and always returns older messages than currentMessageId parameter
    *
    * @param conversationId - Identifier of a conversation.
    * @param currentMessageId - Messages older than currentMessageId are returned
    * @param count - Required messages count
    * @param list  - Ordered list of messages for given conversation
    */
   void getMessages(out MessageList list, in ConversationId conversationId, in MessageId currentMessageId, in long count);

   /**
    * Returns ordered list of all new messages + required count of older messages from single conversation and also subscribes for continuous flow of changes.  The list is always
    * ordered by messageId. The continuous flow of messages includes all new, it is NOT filtered by query.
    *
    * @param conversationId - Identifier of a conversation
    * @param currentMessageId - All newer (included currentMessageId) messages are returned + count of older messages
    * @param count - Required older messages count
    */
   void subscribeMessages(out MessageList list, in ConversationId conversationId, in long currentMessageId, in long count);

   /**
    * Stops listening on new messages within conversation.
    *
    * @param conversationId - Identifier of conversation to unsubscribe.
    */
   void unsubscribeMessages(in ConversationId conversationId);

   /**
    * It sends a message into a conversation. Field 'message.to' must be known before sending a message. Client either have it or must asks for it.
    *
    * @param message   - Message to be send. It already contains the destination (the 'to' field). It does not contain a 'messageId' as it is generated by server.
    * @param messageId - Message id
    * @param time - Time of message
    * @param markAsRead - Message will be marked as read for to users.
    */
   void sendMessage(out MessageId messageId, out UtcDateTime time, in Message message, in boolean markAsRead);
};

}; }; }; }; // end of namespace