Server.idl

Go to the documentation of this file.

/**
 * @file   Server.idl
 * @brief  Work with product specific options like alerts, connections, opened folders, active (web) sessions.
 *
 * @author Dusan Juhas
 *
 * @copyright Copyright © 2017 Kerio Technologies s.r.o.
 */

#import <kerio/web/idl/SharedStructures.idl>
#import <common.idl> //WebComponent
#import <AdminStructures.idl> // DirectoryAccessResult, DirectoryList
#import <Domains.idl> //MaximumUsers


module kerio {
module jsonapi {
module admin {

/**
 * Available entities, entity prefix due to name collision
 */
enum Entity {
   EntityUser,          ///< User Entity
   EntityAlias,         ///< Alias Entity
   EntityGroup,         ///< Group Entity
   EntityMailingList,      ///< Mailing List Entity
   EntityResource,         ///< Resource Scheduling Entity
   EntityTimeRange,     ///< Time Range Entity
   EntityTimeRangeGroup,   ///< Time Range Group Entity
   EntityIpAddress,     ///< Ip Address Entity
   EntityIpAddressGroup,   ///< Ip Address Group Entity
   EntityService,       ///< Service Entity
   EntityDomain
};

/**
 * Restriction Items
 */
struct RestrictionTuple {
   kerio::web::ItemName name;
   kerio::web::RestrictionKind kind;
   kerio::web::StringList values;
};

/**
 * Restriction tuple for 1 entity
 */
typedef sequence<RestrictionTuple> RestrictionTupleList;

/**
 * Entity name restriction definition
 */
struct Restriction {
   Entity entityName;            ///< IDL entity name, eg. User
   RestrictionTupleList tuples;  ///< Restriction tuples
};

/**
 * List of restrictions
 */
typedef sequence<Restriction> RestrictionList;

/**
 * JavaScript timestamp
 */
typedef string JavaScriptDate;

/**
 * Subscription information
 */
struct SubscriptionInfo {
   boolean        isUnlimited;      ///< is it a special license with expiration == never ?
   boolean        showAlert;        ///< show subscription expiration alert
   long        remainingDays;    ///< days remaining to subscription expiration
   JavaScriptDate subscriptionDate; ///< last date of subscription
};

/**
 * About information
 */
struct AboutInfo {
   long           currentUsers;     ///< number of created users on domain
   MaximumUsers      allowedUsers;     ///< number of allowed users, take stricter limit from max. number for domain, max. number by license
   string            serverSoftware;      ///< product name and version string, same as SERVER_SOFTWARE
   SubscriptionInfo  subscription;     ///< information about subscription
   string            copyright;        ///< copyright string
   string            productHomepage;  ///< url to homepage of product
};

/**
 * Type of Alert
 */
enum AlertName {
   LicenseExpired,               ///< License has expired
   LicenseInvalidMinVersion,     ///< Invalid minimal version of a product found
   LicenseInvalidEdition,        ///< The license was not issued for this edition of the product
   LicenseInvalidUser,           ///< The license was not issued for this user
   LicenseInvalidDomain,         ///< The license was not issued for this domain
   LicenseInvalidOS,          ///< The license was not issued for this operating system
   LicenseCheckForwardingEnabled,  ///< The license was not alowed forward the message to another host
   LicenseTooManyUsers,       ///< More users try login to their mailboxes then allowed License.
   StorageSpaceLow,           ///< Low space in storage
   SubscriptionExpired,       ///< Subscription has expired
   SubscriptionSoonExpire,       ///< Subscription soon expire
   LicenseSoonExpire,            ///< License soon expire
   CoredumpFound,             ///< Some coredump was found after crash
   MacOSServicesKeepsPorts,      ///< Apache on Lion server keeps ports (Eg. port 443), which are assigned to our services. See Services.stopMacOSServices()   
   RemoteUpgradeFailed,       ///< Remote server upgrade failed
   RemoteUpgradeSucceeded        ///< Remote server upgrade succeeded
};

/**
 * Type of Alert
 */
enum TypeAlert {
   Warning,
   Critical,
   Info
};

/**
 * Alert
 */
struct Alert {
   AlertName alertName;    ///< Alert Id
   TypeAlert alertType;    ///< Alert type
   string    currentValue;    ///< Current Value
   string    criticalValue;   ///< Critical Value
};

typedef sequence<Alert> AlertList;

/**
 * Potential duplicate
 */
struct EntityDuplicate {
   Entity   kind;    ///< which entity was found as first duplicate
   string   name;    ///< name of duplicate
   string  collisionAddress;
   boolean win;      ///< if entity is winner in this collision of mail address
   boolean isPattern;   ///< is true if it is the pattern to check (self duplicity)
};

typedef sequence<EntityDuplicate> EntityDuplicateList;

/**
 * Detail about entity to be checked. Kind or id must be filled.
 */
struct EntityDetail {
   Entity         kind;       ///< which entity is inserting
   kerio::web::KId   id;            ///< entity global identification of updated entity
};

typedef sequence<string> UserNameList;

struct FolderInfo {
   string folderName;
   long referenceCount;
   boolean indexLoaded;
   UserNameList users;
};

typedef sequence<FolderInfo> FolderInfoList;

struct WebSession {
   string         id;
   string         userName;
   string         clientAddress;    ///< IPv4 address
   string         expirationTime;      ///< format dd.mm.yyyy hh:mm:ss
   WebComponent   componentType;       ///< what about CalDav, WebDav,  ActiveSync
   boolean        isSecure;         ///< is protocol secure
};

typedef sequence<WebSession> WebSessionList;

enum Protocol {
   protocolAdmin,
   protocolSmtp,
   protocolSmtps,
   protocolSubmission,
   protocolPop3,
   protocolPop3s,
   protocolImap,
   protocolImaps,
   protocolNntp,
   protocolNntps,
   protocolLdap,
   protocolLdaps,
   protocolHttp,
   protocolHttps,
   protocolXmpp,
   protocolXmpps
};

enum HttpExtension {
   NoExtension,
   WebGeneric,    ///< WebMail or WebMail Mini or WebAdmin
   WebDav,
   CalDav,
   ActiveSync,
   KocOffline,
   KBC,        ///< Kerio Connector for BlackBerry Enterprise Server
   EWS            ///< Exchange Web Services
};

struct Connection {
   Protocol    proto;
   HttpExtension  extension;
   boolean        isSecure;
   string         time;
   string         from;
   string         user;
   string         description;
};

typedef sequence<Connection> ConnectionList;

/**
 *
 * Note: isEnabled, isLimited and groupId fields must be assigned if any of them is used in set methods
 */
struct Administration {
   boolean        isEnabled;     ///< administration from other that local machine is enabled/disabled
   boolean        isLimited;     ///< administration is limited
   kerio::web::KId   groupId;    ///< IP Address Group identifier on which is limit applied
   string         groupName;     ///< [READ-ONLY] IP Address Group name on which is limit applied

   boolean        builtInAdminEnabled;       ///< if is enabled field builtInAdminPassword is required
   string         builtInAdminUsername;         ///< [READ-ONLY] user name
   string         builtInAdminPassword;         ///< password
   boolean         builtInAdminPasswordIsEmpty; ///< [READ-ONLY] password is empty
   boolean        builtInAdminUsernameCollide;  ///< [READ-ONLY] username colide with user in primary domain
};

/**
 * Server time information
 */
struct ServerTimeInfo {
   long timezoneOffset;       ///< +/- offset in minutes
   DateTimeStamp startTime;      ///< +/- start time of server
   DateTimeStamp currentTime;    ///< +/- current time on server
};

interface Server {

   /**
    * Server creates an archive/backup path. If credentials aren't specified, values from current configuration of backup are used.
    *
    * @param result - result of create action
    * @param path - new directory to create
    * @param credentials - (optional) user name and password required to access network disk
    */
   void createPath(out DirectoryAccessResult result, in string path, in Credentials credentials);

   /**
    * Find emails duplicate among entities in this order: resources, aliases, mailing lists, groups, users;
    * caller must be authenticated; Note: creating duplicates is often allowed but may cause unwanted effects.
    *
    * @param entities - list of found entities with e-mail address duplicate 'updatedEntity' is included in list and marked, if none duplicate is found list is empty
    * @param addresses - list of email addresses (without domain) to be checked
    * @param updatedEntity - identification of the current entity (to avoid self duplicity)
    * @param domainId - domain identification
    */
   void findEntityByEmail(out EntityDuplicateList entities, in kerio::web::StringList addresses, in EntityDetail updatedEntity, in kerio::web::KId domainId);

   /**
    * Generate a file with information for the support.
    *
    * @param fileDownload - description of output file
    */
   void generateSupportInfo(out kerio::web::Download fileDownload);

   /**
    * Obtain information about server, caller must be authenticated.
    *
    * @param aboutInformation - information about server
    */
   void getAboutInfo(out AboutInfo aboutInformation);

   /**
    * Obtain a list of alerts.
    *
    * @param alerts - list of alerts
    */
   void getAlertList(out AlertList alerts);

   /**
    * Returns a list of user-preferred languages set in browser.
    *
    * @param calculatedLanguage - a list of 2-character language codes
    */
   void getBrowserLanguages(out kerio::web::StringList calculatedLanguage);

   /**
    * Obtain client statistics settings.
    *
    * @param setting - new settings
    */
   void getClientStatistics(out boolean isEnabled);

   /**
    * Obtain a list of columns dependent on callee role.
    *
    * @param columns - list of available columns
    * @param objectName - name of the API object
    * @param methodName - name of the method of appropriate object
    */
   void getColumnList(out kerio::web::StringList columns, in string objectName, in string methodName);

   /**
    * Obtain information about active connections.
    *
    * @param list - active connections
    * @param totalItems - total number of active connections
    * @param query - condition and fields have no effect for this method
    */
   void getConnections(out ConnectionList list, out long totalItems, in kerio::web::SearchQuery query);

   /**
    * Obtain a list of directories in a particular path.
    *
    * @param dirList - List of directories
    * @param fullPath - directory for listing, if full path is empty logical drives will be listed
    */
   void getDirs(out DirectoryList dirList, in string fullPath);

    /**
    * Obtain list of license extensions, caller must be authenticated.
    *
    * @param extensions - list of license extensions
    */
   void getLicenseExtensionsList(out kerio::web::StringList extensions);

   /**
    * Server side list of constants.
    *
    * @param constants - list of constants
    */
   void getNamedConstantList(out NamedConstantList constants);

   /**
    * Obtain information about folders opened on server.
    *
    * @param list - opened folders with info
    * @param totalItems - total number of opened folders
    * @param query - condition and fields have no effect for this method
    */
   void getOpenedFoldersInfo(out FolderInfoList list, out long totalItems, in kerio::web::SearchQuery query);

   /**
    * Get basic information about product and its version.
    *
    * @param info - structure with basic information about product
    */
   void getProductInfo(out ProductInfo info);

   /**
    * Obtain information about remote administration settings.
    *
    * @param setting - current settings
    */
   void getRemoteAdministration(out Administration setting);

   /**
    * Obtain a hash string created from product name, version, and installation time.
    *
    * @param serverHash - server hash
    */
   void getServerHash(out string serverHash);

   /**
    * List all server IP addresses.
    *
    * @param addresses - all IP addresses of the server
    */
   void getServerIpAddresses(out kerio::web::StringList addresses);

   /**
    * Get server time information.
    *
    * @param info - structure with time information
    */
   void getServerTime(out ServerTimeInfo info);

   /**
    * Obtain information about server version.
    *
    * @param product - name of product
    * @param version - version in string consists of values of major, minor, revision, build a dot separated
    * @param major - major version
    * @param minor - minor version
    * @param revision  - revision number
    * @param build - build number
    */
   void getVersion(out string product, out string version, out long major, out long minor, out long revision, out long build);

   /**
    * Obtain information about web component sessions.
    *
    * @param list - web component sessions
    * @param totalItems - total number of web component sessions
    * @param query - condition and fields have no effect for this method
    */
   void getWebSessions(out WebSessionList list, out long totalItems, in kerio::web::SearchQuery query);

   /**
    * Terminate actual web sessions.
    *
    * @param ids - list of web sessions IDs to terminate
    */
   void killWebSessions(in kerio::web::KIdList ids);

   /**
    * Check if the selected path exists and is accessible from the server.
    *
    * @param path - directory name
    * @param credentials - (optional) user name and password required to access network disk
    * @param result - result of check
    */
   void pathExists(out DirectoryAccessResult result, in string path, in Credentials credentials);

   /**
    * Reboot the host system.
    */
   void reboot();

   /**
    * Restart server. The server must run as service.
    */
   void restart();

   /**
    * Upgrade server to the latest version. The server must run as service.
   */
   void upgrade();

   /**
   * Get progress of installation package downloading
   *
   * @param
   * @param progress - download progress in percents (0-100)
   */
   void getDownloadProgress(out long progress);

   /**
    * Send a bug report to Kerio.
    *
    * @param name - name of sender
    * @param email - email of sender
    * @param language - language of report
    * @param subject - summary of report
    * @param description - description of problem
    */
   void sendBugReport(in string name, in string email, in string language, in string subject, in string description);

   /**
    * Set client statistics settings.
    *
    * @param setting - new settings
    */
   void setClientStatistics(in boolean isEnabled);

   /**
    * Set new remote administration parameters.
    *
    * @param setting - new settings
    */
   void setRemoteAdministration(in Administration setting);

   /**
    * Upload license manually from a file.
    *
    * @param fileId - ID of the uploaded file
    */
   void uploadLicense(in string fileId);

   /**
    * Validate whether the administrator can cut off him/herself from the administration.
    *
    * @param setting - new setting
    */
   void validateRemoteAdministration(in Administration setting);

   /**
    * Determine whether to use British or American flag for English.
    *
    * @param preferred - use British flag
    */
   void isBritishPreferred(out boolean preferred);
};

}; }; };//end of namespace