Changes.idl

Go to the documentation of this file.

/**
 * @file   Changes.idl
 * @brief  Work with WebMail changes like new e-mail, reminders, events.
 *
 * @author Martin Hosna
 *
 * @copyright Copyright © 2017 Kerio Technologies s.r.o.
 */


/**
 * @defgroup FOLDERS Accessing message folders
 * @{
 */
#import <Structures.idl>

module kerio {
module jsonapi {
module webmail {
module changes {

enum ChangeType {
   chtCreated,
   chtCopied,
   chtDeleted,
   chtModified,
   chtMoved,
   chtNewMail,          ///< Valid only for item type 'itMail' and not for folder. Folder filter is not applied for this.
   chtStatus,
   chtReadFlagChanged,  ///< Valid only for item type 'itMail' and not for folder.
   chtModifiedMetadata, ///< Valid only for item type 'itMail' and not for folder. Content of messge is not changed, basicaly only flags. 
   chtModifiedContent   ///< Valid only for folder. It means there was a change in messages which are placed in the folder. E.g.: number of unread messages.
};

enum ItemType {
   itMail,          ///< change per mailbox for type 'chtNewMail'  (folder filter is not applied)
   itCalendar,
   itContact,
   itTask,
   itNote,
   itCalendarInbox,  ///< change per mailbox (folder filter is not applied)
   itDelegation      ///< Valid ChangeType is 'chtCreated' and 'chtDeleted'
};

struct AccountSyncKey {
   string guid;
   Watermark watermark;
};

typedef sequence<AccountSyncKey> AccountSyncKeyList;

struct SyncKey {
   long id;
   long version;
   Watermark watermark;
   Watermark publicFolder;
   AccountSyncKeyList accountSyncKey;
};

struct Change {
   boolean isFolder;
   ChangeType type;
   ItemType   itemType;

   kerio::web::KId itemId;
   kerio::web::KId parentId;

   kerio::web::KId origId;
   kerio::web::KId origParentId;

   Watermark watermark;

   long messageUnread; ///< when type is chtModifiedContent, it contains number of unreaded messages; when type is chtReadFlagChanged, it contains 1 if a message is unreaded
};

typedef sequence<Change> ChangeList;

/**
 * Changes manager class
 */
interface Changes {
   /**
    * Get changes for all folders on this server.
    * Is permitted only one long-poll request with the same 'lastSyncKey'.  
    *
    * @param list - all found changes
    * @param syncKey - new watermark
    * @param lastSyncKey - last watermark
    * @param timeout - max time to wait for new changes. If value is zero response is returned imediately.  
    */
   void get(out ChangeList list, out SyncKey syncKey, in SyncKey lastSyncKey, in long timeout);

   /**
    * Get changes for all accessible folders of particular user or resource.
    *
    * @param list - all found changes
    * @param asyncKey - new watermark
    * @param lastAsyncKey - last watermark
    * @param folderIds - IDs of subcribed folders
    */
   void getAccount(out ChangeList list, out AccountSyncKey asyncKey, in AccountSyncKey lastAsyncKey, in kerio::web::KIdList folderIds);

   /**
    * Kill current running Changes.get's request. It supposed that timeout was specified > 0.
    *
    * @param lastSyncKey - last watermark
    */
   void killRequest(in SyncKey lastSyncKey);

   /**
    * Get changes in a folder.
    *
    * @param list - all found changes
    * @param syncKey - new last synckey (watermark)
    * @param folderId - folder from which we want get item changes
    * @param lastSyncKey - last synckey (watermark)
    */
   void getFolder(out ChangeList list, out Watermark syncKey, in kerio::web::KId folderId, in Watermark lastSyncKey);


   /**
    * Get actual watermark.
    *
    * @param watermark - actual watermark
    */
   void getSyncKey(out SyncKey syncKey);

   /**
    * Get actual watermark.
    *
    * @param watermark - actual watermark
    * @param pricipalId - ID of a user or a resurce
    */
   void getAccountSyncKey(out AccountSyncKey asyncKey, in kerio::web::KId mailboxId);

   /**
    * Get actual sync key for a folder.
    *
    * @param syncKey - actual synckey (watermark) for folder
    * @param folderId - wanted folder 
    */
   void getFolderSyncKey(out Watermark syncKey, in kerio::web::KId folderId);
};


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

/**
 * @}
 */