Contacts.idl

Go to the documentation of this file.

/**
 * @file   Contacts.idl
 * @brief  %Contacts management
 *
 * @author Dusan Juhas, Frantisek Boranek
 *
 * @copyright Copyright © 2017 Kerio Technologies s.r.o.
 */

#import <Structures.idl>
#import <ContactsCommon.idl>
#import <Certificates.idl>

module kerio {
module jsonapi {
module webmail {
module contacts {


enum ContactType {
   ctContact,
   ctDistributionList
};

/**
 * Contact detail.
 */
struct Contact {
   kerio::web::KId id;
   kerio::web::KId folderId;
   Watermark      watermark;
   ContactType type;

   string commonName;
   string firstName;
   string middleName;
   string surName;
   string titleBefore;
   string titleAfter;
   string nickName;

   kerio::jsonapi::contacts::PhoneNumberList phoneNumbers;
   kerio::jsonapi::contacts::EmailAddressList emailAddresses;
   kerio::jsonapi::contacts::PostalAddressList postalAddresses;
   kerio::jsonapi::contacts::UrlList urls;

   UtcDateTime birthDay;
   UtcDateTime anniversary;
   string companyName;
   string departmentName;
   string profession;
   string managerName;
   string assistantName;
   string comment;
   string IMAddress;
   kerio::jsonapi::contacts::PhotoAttachment photo;   

   kerio::web::StringList categories;

   kerio::web::KId certSourceId; ///< [WRITE-ONLY]

   boolean isGalContact; ///< [READ-ONLY]
};

typedef sequence<Contact> ContactList;


/**
 * Export format type
 */
enum ResourceType {
   ResourceRoom,     ///< resource is a room
   ResourceEquipment ///< resource is something else, eg: a car
};

/**
 * Resource details [READ-ONLY]
 */
struct Resource {
   string            name;       ///< resource name
   string            address;    ///< email of resource
   string            description;   ///< resource description
   ResourceType      type;       ///< type of the resource
};

/**
 * List of resources
 */
typedef sequence<Resource> ResourceList;


/** Constants for composing kerio::web::SearchQuery */
module searchFields {
   const string QUICKSEARCH = "QUICKSEARCH";    ///< [SEARCHABLE]
   const string displayName = "displayName";    ///< [SEARCHABLE][SORTABLE] string
   const string firstName = "firstName";        ///< [SEARCHABLE][SORTABLE] string
   const string surName = "surName";            ///< [SEARCHABLE][SORTABLE] string
   const string middleName = "middleName";      ///< [SEARCHABLE] string
   const string nickName = "nickName";          ///< [SEARCHABLE] string
   const string company = "company";            ///< [SEARCHABLE][SORTABLE] string
   const string hasEmail = "hasEmail";          ///< [SEARCHABLE] boolean
   const string email = "email";                ///< [SEARCHABLE][SORTABLE] string
   const string phone = "phone";                ///< [SEARCHABLE][SORTABLE] string (work phone)
   const string category = "category";          ///< [SEARCHABLE] string
   const string homeAddress = "homeAddress";    ///< [SEARCHABLE] string
   const string otherAddress = "otherAddress";  ///< [SEARCHABLE] string
   const string guid = "guid";                  ///< [SEARCHABLE] string
   const string uid = "uid";                    ///< [SEARCHABLE] string
      
   const string isDList = "isDList";            ///< [SEARCHABLE] boolean
   const string listMember = "listMember";      ///< [SEARCHABLE] string
   
   const string fileAs = "fileAs";              ///< [SORTABLE]
   

   // Resource fields  
   const string name = "name";                 ///< [SEARCHABLE] string (resource name)
   const string address = "address";         ///< [SEARCHABLE] string (email of resource)
   const string description = "description"; ///< [SEARCHABLE] string (resource description)
   const string type = "type";               ///< [SEARCHABLE] ResourceType (type of the resource)
};

/**
 * Contacts management.
 */
interface Contacts {

   /**
    * Copy existing contacts to folder
    *
    * @param errors - error message list
    * @param ids - list of global identifiers of contacts to be copied
    * @param folder - target folder
    */
   void copy(out kerio::web::ErrorList errors, out CreateResultList result, in kerio::web::KIdList ids, in kerio::web::KId folder);

   /**
    * Create contact in particular folder
    *
    * @param errors - error message list
    * @param result - list of ID of crated contacts
    * @param contacts - new contacts; Field 'folderId' must be set.
    */
   void create(out kerio::web::ErrorList errors, out CreateResultList result, in ContactList contacts);

   /**
    * Get a list of contacts.
    *
    * @param list - all found contacts
    * @param totalItems - number of contacts found if there is no limit
    * @param folderIds - list of global identifiers of folders to be listed.
    * @param query - query attributes and limits
    */
   void get(out ContactList list, out long totalItems, in kerio::web::KIdList folderIds, in kerio::web::SearchQuery query);

   /**
    * Get a list of contacts. It works the same way as Contacts.get but retuns only this fields:
    * id, folderId, watermark, type, commonName, titleAfter, titleBefore, firstName, middleName, surName, nickName, emailAddresses, phoneNumbers, photo
    *
    * @param list - all found contacts
    * @param totalItems - number of contacts found if there is no limit
    * @param folderIds - list of global identifiers of folders to be listed.
    * @param query - query attributes and limits
    */
   void getFromCache(out ContactList list, out long totalItems, in kerio::web::KIdList folderIds, in kerio::web::SearchQuery query);

   /**
    * Get particular contacts. All members of struct Contact are filed in response.
    *
    * @param errors - list of errors which happened
    * @param result - contacts of given IDs. All members of struct are returned.
    * @param ids - global identifiers of contact.
    */
   void getById(out kerio::web::ErrorList errors, out ContactList result, in kerio::web::KIdList ids);

   /**
    * Get particular contacts. These members of struct Contact are filed in response:
    * id, folderId, watermark, type, commonName, titleAfter, titleBefore, firstName, middleName, surName, nickName, emailAddresses, phoneNumbers, photo
    *
    * @param errors - list of errors which happened
    * @param result - contacts of given IDs.
    * @param ids - global identifiers of contact.
    */
   void getByIdFromCache(out kerio::web::ErrorList errors, out ContactList result, in kerio::web::KIdList ids);

   /**
   * Get contact from attachment.
   *
   * @param result - contact of given IDs. All members of struct are returned.
   * @param id - global identifiers of mail attachment.
   */
   void getFromAttachment(out Contact result, in kerio::web::KId id);
   
   /**
    * Get a list of resources that an user can schedule.
    *
    * @param list - all found resources
    * @param totalItems - number of resources found if there is no limit
    * @param query - query attributes and limits (empty query obtain all resources)
    */
   void getResources(out ResourceList list, out long totalItems, in kerio::web::SearchQuery query);

   /**
    * Get a certificate for given email address.
    *
    * @param cert  - found certificate
    * @param email - email address of requested certificate
    * @param id    - global identifier of contacts to be searched
    */
   void getCertificate(out kerio::jsonapi::webmail::certificates::Certificate cert, in string email, in kerio::web::KId id);
   
   /**
    * Remove a list of contacts.
    *
    * @param errors - list of contacts that failed to remove
    * @param ids - list of global identifiers of contacts to be removed
    */
   void remove(out kerio::web::ErrorList errors, in kerio::web::KIdList ids);

   /**
    * Set existing contacts.
    *
    * @param errors - error message list
    * @param contacts - modifications of contacts. Field 'folderId' must be set.
    */
   void set(out kerio::web::ErrorList errors, out SetResultList result, in ContactList contacts);

   /**
    * Move existing contacts to folder
    *
    * @param errors - error message list
    * @param ids - list of global identifiers of contacts to be moved
    * @param folder - target folder
    */
   void move(out kerio::web::ErrorList errors, out CreateResultList result, in kerio::web::KIdList ids, in kerio::web::KId folder);

   /**
   * Get personal user contact
   *
   */
   void getPersonal(out kerio::jsonapi::contacts::PersonalContact contact);

   /**
   * Set personal user contact
   *
   */
   void setPersonal(in kerio::jsonapi::contacts::PersonalContact contact);

};

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

/**
 * @}
 */