ProductRegistration.idl

Go to the documentation of this file.

/**
 * @file   ProductRegistration.idl
 * @brief  Registration from the product
 *
 * @author Dusan Juhas, Jakub Zeman, Slavoj Pisek
 *
 * Copyright © 2017 Kerio Technologies s.r.o.
 */
#import <kerio/web/idl/SharedStructures.idl>

 module kerio {
 module web {
 
 
/**
 * @brief ineger value used in KISS as "UNLIMITED" in license, see Registration::subscribers and RegistrationFullStatus::users below
 */
const long unlimitedUsers = -2;

/**
 * @brief a date structure
 */
struct RegDate {
   long year;      ///< year
   long month;    ///< 1-12
   long day;      ///< 1-31 max day is limited by month
};

 /**
 * @brief Registration Number info
 */
struct RegistrationNumber {
   string key;                 ///< Registration number
   string type;                ///< A type of the reg. number (base id, addon...)
   string description;         ///< A description of the reg. number.
};


/**
 *  @brief A list of strings
 **/
typedef sequence<string> RegStringList;

/**
 * @brief An answer for survey questions
 */
struct SurveyAnswer {
   string questionID;      ///< ID of the question
   string answer;          ///< answer to the question
};

/**
 * @brief a list of answers for survey questions
 */
typedef sequence<SurveyAnswer> SurveyAnswerList;


/**
 *  @brief A list of registration numbers related to a registration.
 */
typedef sequence<RegistrationNumber> RegistrationNumberList;

/**
 * @brief Extension information
 */
struct Extension {
   string name;         ///< extension name
};

/**
 *  @brief A list of extensions related to a registration.
 */
typedef sequence<Extension> ExtensionList;


/**
 * @brief Details about the license's owner
 */
struct LicenseDetail {
   string organization;  ///< compulsory
   string person;        ///< compulsory
   string email;         ///< compulsory
   string phone;         ///< compulsory
   string web;
   string country;      ///< compulsory
   string state;        ///< compulsory for countries such as USA, Canada, Australia etc.
   string city;         ///< compulsory
   string street;       ///< compulsory
   string zip;          ///< compulsory
   string comment;
};


/**
 *  @brief The data related to a registration. Content of the structure is obtained
 *   from our registration server by method getRegistrationInfo, modified by client and sent back
 *   to the server by method finishRegistration
 *
 *  @see getRegistrationInfo, finishRegistration
 */
struct Registration {
   LicenseDetail details;              ///< Information about user
   RegDate expirationDate;             ///< Expiration date
   long   subscribers;                 ///< A count of Subscribers (typically users) of the product
   boolean   showQuestions;            ///< Have to show questions?
   long   registrationType;            ///< is it edu/gov registration?
   string eduInfo;                     ///< information special for EDUcational type of organization
   RegistrationNumberList regNumbers;  ///< All registration numbers included in registration
   SurveyAnswerList surveyAnswers;     ///< Survey answers - Answers should be sent in the same order as the questions are displayed.
   ExtensionList extensions;        ///< list of extensions
};

/**
 *  Type of registration finish
 **/
enum RegistrationFinishType {
   rfCreate,                    ///< Create a new registration
   rfModify,                    ///< Modify existing Registration
   rfDownload,                  ///< Download license key without any modification
   rfStore                      ///< Just store in product without downloading key and modifying reg. (trial)
};

/**
 * A type of the current registration of the product
 */
enum RegistrationType {
   rsNoRegistration,        ///< The product has not been registered yet
   rsTrialRegistered,       ///< The product has a valid trial registration
   rsTrialExpired,          ///< The product has a trial registration but it has expired!
   rsProductRegistered      ///< The product has been registered.
};


/**
 * A registration Status of the current product.
 */
struct RegistrationStatus {
   RegistrationType    regType;    ///< The registration type of the current prooduct
   string              Id;         ///< Base or trial ID used for registration
};


/**
 * Type of expiration
 */
enum ExpireType {
   License,                        ///< License
   Subscription                    ///< Subscription
};


/**
 * Expire date information
 */
struct ExpireInfo {
   ExpireType     type;          ///< type of expiration
   boolean        isUnlimited;      ///< is it a special license with expiration == never ?
   long        remainingDays;    ///< days remaining to subscription expiration
   long        date;          ///< last date of subscription
};


/**
 * All expiration dates information in license
 */
typedef sequence<ExpireInfo> LicenseExpireInfo;


/**
 * Full status information
 */
struct RegistrationFullStatus {
   RegistrationType    regType;     ///< The registration type of the current prooduct
   string              Id;          ///< Base or trial ID used for registration
   string            company;    ///< Company name
   long           users;         ///< Users count
   LicenseExpireInfo expirations;   ///< sequence of expire information
};


/**
 * @brief Class provides an interface for both standard and trial registration
 *  process of Kerio products
 *
 * (Trial) registration begins with calling method startRegistration().
 *  The method returns a token (for identifying registration session) and
 *  a "security" picture.
 *  A code from the picture and the token are sent back to server as argument
 *  of method get() together with a registration number.
 *  If the reg. number already exists in the system the server sends back
 *  License details which could be displayied by the wizard.
 *  As step 3 the wizard offers a user interface for adding new registration
 *  numbers. A new number can be verified by method verifyRegistrationNumber().
 *  The registration can be finished by method finish().
 */
interface ProductRegistration {

    /**
     * The Method finishes registration and installs the valid licenseKey.
     *
     * @param token - ID of wizard's session
    * @param baseId - Base ID of registration
     * @param registrationInfo - Registration data retrieved from server by getRegistrationInfo() and modified by user.
     * @param finishType - how to finish the registration? Create a new one, modyfy an existing or just download an existing license?
     */
   void finish(in string token, in string baseId, in Registration registrationInfo, in RegistrationFinishType finishType);

   /**
    * Retrieves existing registration data from the server.
    *
    * @param registrationInfo - the registration data related to the license ID
    * @param newRegistration - flag indicates whether the registration has already existed.
    * @param token - ID of wizard's session
    * @param securityCode - a code number from the security immage
    * @param baseId - license ID
    * @param trial - trial ID registered on web, do not display registrationInfo and finish immediatelly     
    */
   void get(out Registration registrationInfo, out boolean newRegistration, in string token, in string securityCode, in string baseId, out boolean trial);

   /**
    * The function checks what kind of registration should be offered to the user.
    *
    * @param status - A current registration status of the product.
    * @see RegistrationFullStatus
    */
   void getFullStatus(out RegistrationFullStatus status);

   /**
    * The function checks what kind of registration should be offered to the user.
    *
    * @param status - Current registration status of the product.
    * @see RegistrationStatus
    */
   void getStatus(out RegistrationStatus status);

   /**
    * Starts registration process. Methods connect to a server and obtain an identification token and a security image.
    *
    * @param token - ID of wizard's session
    * @param image - URL of the image with the security code
    * @param showImage - show captcha image in wizard if true
    * @param langId - language id
    */
    void start(out string token, out string image, out boolean showImage, in string langId);

    /**
    * Function checks whether a registration number can be added to the registration with the BaseId.
    *
    * It may happen that the nummber is OK, but the registration cannot be finished without adding some other registration numbers.
    * In that case parameter allowFinish is set to false and admin must disable wizards "next" button to avoid finishing
    * an uncomplete registration.
    *
    * @param errors - description of an error in case of failure
    * @param regNumberInfo - information related to given registration key(s)
    * @param allowFinish - if false, the number is OK, but the registration cannot be finished without adding some other numbers.
    * @param users - the count of users connected to the license
    * @param expirationDate - licence expiration date
    * @param token - ID of wizard's session
    * @param baseId - Registration's baseId
    * @param regNumbersToVerify - a list of numbers to be verified
    */
    void verifyNumber(out ErrorList errors, out RegistrationNumberList regNumberInfo, out boolean allowFinish,  out long users, out RegDate expirationDate, in string token, in string baseId, in RegStringList regNumbersToVerify);
};

}; // module web
}; // module kerio