Folders.idl

Go to the documentation of this file.

/**
 * @file   Folders.idl
 * @brief  Message Folders
 *
 * @author Martin Hosna
 *
 * @copyright Copyright © 2017 Kerio Technologies s.r.o.
 */


/**
 * @defgroup FOLDERS Accessing message folders
 * @{
 */

#import <Structures.idl>
#import <Principals.idl>

module kerio {
module jsonapi {
module webmail {
module folders {

/**
 * Folder sub-type enumeration.
 */
enum FolderSubType {
   FSubNone,         ///< Ordinary folder.
   FSubInbox,        ///< Special sub-type of FMail. This folder cannot be removed.
   FSubDrafts,       ///< Special sub-type of FMail. This folder cannot be removed.
   FSubSentItems,    ///< Special sub-type of FMail. This folder cannot be removed.
   FSubDeletedItems, ///< Special sub-type of FMail. This folder cannot be removed.
   FSubJunkEmail,    ///< Special sub-type of FMail. This folder cannot be removed.
   FSubDefault,      ///< These folders cannot be removed.
   FSubGalResources,   ///< This folder is created via GAL for storage contacts of resources.
   FSubGalContacts      ///< This folder is created via GAL for storage contacts of people.
};

/**
 * Folder type enumeration
 */
enum FolderType {
   FRoot,
   FMail,
   FContact,
   FCalendar,
   FTask,
   FNote
};

/**
 * Type of place where is folder placed
 */
enum FolderPlaceType {
   FPlaceMailbox,    ///< the mailbox of currently loged user
   FPlaceResources,  ///< the resource type of Equipment
   FPlaceLocations,  ///< the resource type of Room
   FPlacePeople,     ///< the shared folder of another user
   FPlacePublic,     ///< the public folder
   FPlaceArchive  ///< the archive folder
};

/**
 * Access to folder
 */
enum FolderAccess {
   FAccessListingOnly,
   FAccessReadOnly,
   FAccessReadWrite,
   FAccessAdmin ///< full access; E.g user can add folder
};

struct FolderPermission {
   FolderAccess access;
   kerio::jsonapi::webmail::principals::Principal principal;
   boolean inherited;      ///< [READ-ONLY] permission are placed in a public root folder and there are read-only here
   boolean isDelegatee; ///< [READ-ONLY] principal is delegatee (this flag is filled only for default calendar and INBOX otherwise is false)
};

typedef sequence<FolderPermission> FolderPermissionList;


struct Folder {
   kerio::web::KId      id;            ///< [READ-ONLY] global identification
   kerio::web::KId      parentId;      ///< global identification
   string            name;       ///< folder name displayed in folder tree
   string            ownerName;     ///< [READ-ONLY] name of owner of folder (available only for 'FPlacePeople', 'FPlaceResources' and 'FPlaceLocations')
   string            emailAddress;  ///< [READ-ONLY] email of owner of folder (available only for 'FPlacePeople', 'FPlaceResources' and 'FPlaceLocations')
   FolderType        type;       ///< type of the folder
   FolderSubType     subType;    ///< [READ-ONLY] type of the folder
   FolderPlaceType     placeType;      ///< [READ-ONLY] type of place where is folder placed
   FolderAccess      access;        ///< [READ-ONLY] type of access of currently loged user
   boolean           isShared;      ///< [READ-ONLY] true if a folder is shared to another user (permissions are not empty)
   boolean           isDelegated;   ///< [READ-ONLY] true if a folder access is R/W and user is a delegate
   long           nestingLevel;  ///< [READ-ONLY] number 0 = root folder, 1 = subfolders of root folder, 2 = subfolder of subfolder, ...
   long           messageCount;  ///< [READ-ONLY] count of items in the folder (not set for root folder)
   long           messageUnread; ///< [READ-ONLY] count of unread items (mails or deleted items) in folder, not set for non-mail folder types
   longlong       messageSize;         ///< [READ-ONLY] size of all messages in the folder (without subdirectories)
   boolean           checked;    ///< true if a folder is chosen to view
   string            color;         ///< a color of folder, if string is empty no color is set
   boolean           published;     ///< [READ-ONLY] true, if folder was published to server
};

typedef sequence<Folder> FolderList;


struct SharedMailbox {
   kerio::jsonapi::webmail::principals::Principal principal;  ///< types [ptUser, ptResource]
   kerio::web::KId                                mailboxId;  ///< root folder ID 
   boolean                                        isLoaded;   ///< folders are loaded (are present on the same home server) 
   FolderList                                     folders;    ///< folders with at least listing-only righs
   kerio::web::KIdList                            subscribedFolderIds;
};

typedef sequence<SharedMailbox> SharedMailboxList;


/**
 * Folder store manager class
 */
interface Folders {

   /**
    * Remove all items in folder older then given item ID including. If folder is type of 'FMail' the items are moved to Delete Items or throw away if folder is Delete Items.
    *
    * @param itemId - the last item ID
    */
   void clearToItemId(in kerio::web::KId itemId);

   /**
    * Create new folders
    *
    * @param errors - error message list
    * @param result - list of ID of crated folders.
    * @param folders - list of folders to create
    */
   void create(out kerio::web::ErrorList errors, out kerio::web::CreateResultList result, in FolderList folders);

   /**
    * Obtain list of folders of currently logged user
    *
    * @param list - list of folders
    */
   void get(out FolderList list);
   
   /**
    * Obtain list of folders which currently logged user can access
    *
    * @param list - list of folders
    */
   void getShared(out FolderList list, in kerio::web::KId mailboxId);

   /**
    * Obtain list of public folders which currently logged user can access
    *
    * @param list - list of public folders
    */
   void getPublic(out FolderList list);

   /**
    * Obtain list of folders acording SubscriptionList. 
    *
    * @param list - list of folders
    */
   void getSubscribed(out SharedMailboxList list);

   /**
    * Obtain ID of special folder for auto-complete contacts
    *
    * @param folderId - ID of special folder
    */
   void getAutoCompleteContactsFolderId(out kerio::web::KId folderId);

   /**
    * Obtain list of mailboxes with their folders which currently logged user can access
    *
    * @param mailboxes - list of mailboxes with their folders
    */
   void getSharedMailboxList(out SharedMailboxList mailboxes);
   
   /**
    * Move folder. Sub-folders of different types are moved to a parent folder, therefore it's safe to call this method even
    * if it isn't known if some sub-folders are there.
    * Take a note that mail folders are moved recursively (the whole subtree)! Folders of other types (e.g. calendars) are not moved recursively.
    *
    * @param errors - error message list
    * @param targetId - target folder ID
    * @param ids - folder IDs
    */
   void moveByType(out kerio::web::ErrorList errors, in kerio::web::KId targetId, in kerio::web::KIdList ids);

   /**
    * Set folder properties
    *
    * @param errors - error message list
    * @param folders - properties to save
    */
   void set(out kerio::web::ErrorList errors, in FolderList folders);
   
   /**
    * Remove folder. Sub-folders are removed if recursive is true.
    *
    * @param errors - error message list
    * @param ids - folder IDs
    * @param recursive - remove sub-folders
    */
   void remove(out kerio::web::ErrorList errors, in kerio::web::KIdList ids, in boolean recursive);

   /**
    * Remove folder. Sub-folders of different types are moved to a parent folder, therefore it's safe to call this method even
    * if it isn't known if some sub-folders are there.
    * Take a note that mail folders are removed recursively! Folders of other types (e.g. calendars) are not removed recursively.
    *
    * @param errors - error message list
    * @param ids - folder IDs
    */
   void removeByType(out kerio::web::ErrorList errors, in kerio::web::KIdList ids);

   /**
    * Get sharing permissions
    *
    * @param permissions - sharing settings
    * @param folderId - ID of folder
    */
   void getPermissions(out FolderPermissionList permissions, in kerio::web::KId folderId);

   /**
    * Set sharing permissions
    *
    * @param permissions - sharing settings
    * @param folderId - ID of folder
    * @param recursively - if true all permissions in subfolders are replaced by these permissions
    */
   void setPermissions(in FolderPermissionList permissions, in kerio::web::KId   folderId, in boolean recursive);
   
   /**
    * Get list of subscribed folders
    *
    * @param folder IDs
    */
   void getSubscriptionList(out kerio::web::KIdList folderIds);

   /**
    * Set list of subscribed folders
    *
    * @param folder IDs
    */
   void setSubscriptionList(in kerio::web::KIdList folderIds);
   
   /**
    * Copies (or moves) all messages from the source folder to the destination
    *
    * @param sourceId - ID of the source folder
    * @param destId - ID of the destionation folder
    * @param doMove - if true move the messages instead of copy the
    */
   void copyAllMessages(in kerio::web::KId sourceId, in kerio::web::KId destId, in boolean doMove);
   
};

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

/**
 * @}
 */