All Classes Files Functions Variables Enumerations Enumerator Groups Pages
ProductRegistration.idl
Go to the documentation of this file.
1 /**
2  * @file ProductRegistration.idl
3  * @brief Registration from the product
4  *
5  * @author Dusan Juhas, Jakub Zeman, Slavoj Pisek
6  *
7  * Copyright © 2017 Kerio Technologies s.r.o.
8  */
9 #import <kerio/web/idl/SharedStructures.idl>
10 
11  module kerio {
12  module web {
13 
14 
15 /**
16  * @brief ineger value used in KISS as "UNLIMITED" in license, see Registration::subscribers and RegistrationFullStatus::users below
17  */
18 const long unlimitedUsers = -2;
19 
20 /**
21  * @brief a date structure
22  */
23 struct RegDate {
24  long year; ///< year
25  long month; ///< 1-12
26  long day; ///< 1-31 max day is limited by month
27 };
28 
29  /**
30  * @brief Registration Number info
31  */
32 struct RegistrationNumber {
33  string key; ///< Registration number
34  string type; ///< A type of the reg. number (base id, addon...)
35  string description; ///< A description of the reg. number.
36 };
37 
38 
39 /**
40  * @brief A list of strings
41  **/
42 typedef sequence<string> RegStringList;
43 
44 /**
45  * @brief An answer for survey questions
46  */
47 struct SurveyAnswer {
48  string questionID; ///< ID of the question
49  string answer; ///< answer to the question
50 };
51 
52 /**
53  * @brief a list of answers for survey questions
54  */
55 typedef sequence<SurveyAnswer> SurveyAnswerList;
56 
57 
58 /**
59  * @brief A list of registration numbers related to a registration.
60  */
61 typedef sequence<RegistrationNumber> RegistrationNumberList;
62 
63 /**
64  * @brief Extension information
65  */
66 struct Extension {
67  string name; ///< extension name
68 };
69 
70 /**
71  * @brief A list of extensions related to a registration.
72  */
73 typedef sequence<Extension> ExtensionList;
74 
75 
76 /**
77  * @brief Details about the license's owner
78  */
79 struct LicenseDetail {
80  string organization; ///< compulsory
81  string person; ///< compulsory
82  string email; ///< compulsory
83  string phone; ///< compulsory
84  string web;
85  string country; ///< compulsory
86  string state; ///< compulsory for countries such as USA, Canada, Australia etc.
87  string city; ///< compulsory
88  string street; ///< compulsory
89  string zip; ///< compulsory
90  string comment;
91 };
92 
93 
94 /**
95  * @brief The data related to a registration. Content of the structure is obtained
96  * from our registration server by method getRegistrationInfo, modified by client and sent back
97  * to the server by method finishRegistration
98  *
99  * @see getRegistrationInfo, finishRegistration
100  */
101 struct Registration {
102  LicenseDetail details; ///< Information about user
103  RegDate expirationDate; ///< Expiration date
104  long subscribers; ///< A count of Subscribers (typically users) of the product
105  boolean showQuestions; ///< Have to show questions?
106  long registrationType; ///< is it edu/gov registration?
107  string eduInfo; ///< information special for EDUcational type of organization
108  RegistrationNumberList regNumbers; ///< All registration numbers included in registration
109  SurveyAnswerList surveyAnswers; ///< Survey answers - Answers should be sent in the same order as the questions are displayed.
110  ExtensionList extensions; ///< list of extensions
111 };
112 
113 /**
114  * Type of registration finish
115  **/
116 enum RegistrationFinishType {
117  rfCreate, ///< Create a new registration
118  rfModify, ///< Modify existing Registration
119  rfDownload, ///< Download license key without any modification
120  rfStore ///< Just store in product without downloading key and modifying reg. (trial)
121 };
122 
123 /**
124  * A type of the current registration of the product
125  */
126 enum RegistrationType {
127  rsNoRegistration, ///< The product has not been registered yet
128  rsTrialRegistered, ///< The product has a valid trial registration
129  rsTrialExpired, ///< The product has a trial registration but it has expired!
130  rsProductRegistered ///< The product has been registered.
131 };
132 
133 
134 /**
135  * A registration Status of the current product.
136  */
137 struct RegistrationStatus {
138  RegistrationType regType; ///< The registration type of the current prooduct
139  string Id; ///< Base or trial ID used for registration
140 };
141 
142 
143 /**
144  * Type of expiration
145  */
146 enum ExpireType {
147  License, ///< License
148  Subscription ///< Subscription
149 };
150 
151 
152 /**
153  * Expire date information
154  */
155 struct ExpireInfo {
156  ExpireType type; ///< type of expiration
157  boolean isUnlimited; ///< is it a special license with expiration == never ?
158  long remainingDays; ///< days remaining to subscription expiration
159  long date; ///< last date of subscription
160 };
161 
162 
163 /**
164  * All expiration dates information in license
165  */
166 typedef sequence<ExpireInfo> LicenseExpireInfo;
167 
168 
169 /**
170  * Full status information
171  */
172 struct RegistrationFullStatus {
173  RegistrationType regType; ///< The registration type of the current prooduct
174  string Id; ///< Base or trial ID used for registration
175  string company; ///< Company name
176  long users; ///< Users count
177  LicenseExpireInfo expirations; ///< sequence of expire information
178 };
179 
180 
181 /**
182  * @brief Class provides an interface for both standard and trial registration
183  * process of Kerio products
184  *
185  * (Trial) registration begins with calling method startRegistration().
186  * The method returns a token (for identifying registration session) and
187  * a "security" picture.
188  * A code from the picture and the token are sent back to server as argument
189  * of method get() together with a registration number.
190  * If the reg. number already exists in the system the server sends back
191  * License details which could be displayied by the wizard.
192  * As step 3 the wizard offers a user interface for adding new registration
193  * numbers. A new number can be verified by method verifyRegistrationNumber().
194  * The registration can be finished by method finish().
195  */
196 interface ProductRegistration {
197 
198  /**
199  * The Method finishes registration and installs the valid licenseKey.
200  *
201  * @param token - ID of wizard's session
202  * @param baseId - Base ID of registration
203  * @param registrationInfo - Registration data retrieved from server by getRegistrationInfo() and modified by user.
204  * @param finishType - how to finish the registration? Create a new one, modyfy an existing or just download an existing license?
205  */
206  void finish(in string token, in string baseId, in Registration registrationInfo, in RegistrationFinishType finishType);
207 
208  /**
209  * Retrieves existing registration data from the server.
210  *
211  * @param registrationInfo - the registration data related to the license ID
212  * @param newRegistration - flag indicates whether the registration has already existed.
213  * @param token - ID of wizard's session
214  * @param securityCode - a code number from the security immage
215  * @param baseId - license ID
216  * @param trial - trial ID registered on web, do not display registrationInfo and finish immediatelly
217  */
218  void get(out Registration registrationInfo, out boolean newRegistration, in string token, in string securityCode, in string baseId, out boolean trial);
219 
220  /**
221  * The function checks what kind of registration should be offered to the user.
222  *
223  * @param status - A current registration status of the product.
224  * @see RegistrationFullStatus
225  */
226  void getFullStatus(out RegistrationFullStatus status);
227 
228  /**
229  * The function checks what kind of registration should be offered to the user.
230  *
231  * @param status - Current registration status of the product.
232  * @see RegistrationStatus
233  */
234  void getStatus(out RegistrationStatus status);
235 
236  /**
237  * Starts registration process. Methods connect to a server and obtain an identification token and a security image.
238  *
239  * @param token - ID of wizard's session
240  * @param image - URL of the image with the security code
241  * @param showImage - show captcha image in wizard if true
242  * @param langId - language id
243  */
244  void start(out string token, out string image, out boolean showImage, in string langId);
245 
246  /**
247  * Function checks whether a registration number can be added to the registration with the BaseId.
248  *
249  * It may happen that the nummber is OK, but the registration cannot be finished without adding some other registration numbers.
250  * In that case parameter allowFinish is set to false and admin must disable wizards "next" button to avoid finishing
251  * an uncomplete registration.
252  *
253  * @param errors - description of an error in case of failure
254  * @param regNumberInfo - information related to given registration key(s)
255  * @param allowFinish - if false, the number is OK, but the registration cannot be finished without adding some other numbers.
256  * @param users - the count of users connected to the license
257  * @param expirationDate - licence expiration date
258  * @param token - ID of wizard's session
259  * @param baseId - Registration's baseId
260  * @param regNumbersToVerify - a list of numbers to be verified
261  */
262  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);
263 };
264 
265 }; // module web
266 }; // module kerio