UpdateChecker.idl

Go to the documentation of this file.

/**
 * @file     UpdateChecker.idl
 * @brief    API for update checker
 * @version  4
 */

#import <kerio/web/idl/SharedStructures.idl>
#import <common.idl>

module webadmin {
 
struct UpdateCheckerConfig {
   boolean enabled;
   boolean betaVersion; /** check also for beta ver. If currently running version is beta, it will be forced regardless of this value */
   boolean download;    /** auto download and update */
   OptionalIdReference autoUpdateTimeRange; /** Time interval when auto update will be scheduled */
};

enum CheckVersionType {
   CheckVersionConfig,
   CheckVersionBeta,
   CheckVersionFinal
};

enum UpdateStatus {
   UpdateStatusOk,
   UpdateStatusChecking,
   UpdateStatusCheckFailed,
   /** States only for Linux version */
   UpdateStatusDownloadOk,
   UpdateStatusDownloading,
   UpdateStatusDownloadFailed,
   UpdateStatusUpgrading,
   UpdateStatusUpgradeFailed
};

struct UpdateCheckerInfo {
   UpdateStatus status;
   boolean newVersion;         /** new version may or may not be available or downloaded */
   long lastCheckTime;         /**< time_t (seconds since 1.1.1970) */
   TimeSpan lastUpdateCheck;  /**< how long is since last rules update check */
   string packageCode;         /**< e.g. "KWF:010.001.00000.B.001.000" */
   string description;         /**< e.g. "Kerio Control 10.1.0 beta 1 - QA Team" */
   string downloadUrl;         /** significant only for Windows version */
   string infoUrl;
   string updateErrorDescr;   /**< optional description of failure happened during attempt to check or download upgrade image */
   boolean autoUpdatePlanned;  /**< true if auto update is planned */
   string autoUpdateDateTime;  /**< When auto update is planned */
};

interface UpdateChecker {

   /**
    * Returns configuration
    * @param config - Contains Structure with update checker's settings.
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation." 
    */   
   void get(out UpdateCheckerConfig config);
   
   /**
    * Stores configuration
    * @param config - Contains Structure with update checker's settings to be stored &a pplied.
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation." 
    */   
   void set(in UpdateCheckerConfig config);

   /**
    * Checks for a new version
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.  - "The user is not logged in." \n
    *          1000  Operation failed. - "No connection available, update disabled or already in progress." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation." \n
    *          8000  Internal error.   - "Internal error." 
    */   
   void check(in CheckVersionType type);
   
   /**
    * Returns actual state of Update checker
    * @param status - a phase of update process.
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation." \n
    *          8000  Internal error.  - "Internal error." 
    */   
   void getStatus(out UpdateCheckerInfo status);
   
   /**
    * METHODS ONLY FOR LINUX VERSION
    */
   
   /**
    * @param percentage - Returns percentage progress for Status Downloading \n
    *                     Stop reading this, when percentage == -1 (DownloadFailed) \n
    *                     or percentage == 100 (DownloadOk)
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation."   
    */
   void getProgressStatus(out long percentage);
   
   /**
    * Starts Downloading
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation." \n
    *          8000  Internal error.  - "Internal error."
    */    
   void download(in CheckVersionType type);

   /**
    * Converts fileId to id, that will be passed into performCustomUpgrade. 
    * @param id - an id obtained from fileId (same values);
    * @param fileId - according to spec 390.
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation." 
    */
   void uploadImage(out kerio::web::KId id, in string fileId);

   /**
    * Processes newly uploaded image for upgrade. Ids according to spec 390.
    * In case of return true, it reboots machine (after 2s delay)
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1000  Operation failed. - "Unable to perform update: %1" \n
    *          1002  No such entity.  - "Unable to open upgrade image file." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation." \n
    *          8000  Internal error.  - "Internal error."   
    */
   void performCustomUpgrade(in kerio::web::KId id);

   /**
    * Runs upgrade
    * In case of return true, it reboots machine (after 2s delay)
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1000  Operation failed. - "Unable to perform update: %1" \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation."
    */
   void performUpgrade();
   
   /**
    * Stops Downloading
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation." \n
    *          8000  Internal error.  - "Internal error."    
    */    
   void cancelDownload();
   
};

}; //webadmin