All Classes Files Functions Variables Enumerations Enumerator Groups Pages
Server.idl
Go to the documentation of this file.
1 /**
2  * @file Server.idl
3  * @brief Work with product specific options like alerts, connections, opened folders, active (web) sessions.
4  *
5  * @author Dusan Juhas
6  *
7  * @copyright Copyright © 2011-2012 Kerio Technologies s.r.o.
8  */
9 
10 #import <kerio/web/idl/SharedStructures.idl>
11 #import <common.idl> //WebComponent
12 #import <AdminStructures.idl> // DirectoryAccessResult, DirectoryList
13 #import <Domains.idl> //MaximumUsers
14 
15 
16 module kerio {
17 module jsonapi {
18 module admin {
19 
20 /**
21  * Available entities, entity prefix due to name collision
22  */
23 enum Entity {
24  EntityUser, ///< User Entity
25  EntityAlias, ///< Alias Entity
26  EntityGroup, ///< Group Entity
27  EntityMailingList, ///< Mailing List Entity
28  EntityResource, ///< Resource Scheduling Entity
29  EntityTimeRange, ///< Time Range Entity
30  EntityTimeRangeGroup, ///< Time Range Group Entity
31  EntityIpAddress, ///< Ip Address Entity
32  EntityIpAddressGroup, ///< Ip Address Group Entity
33  EntityService, ///< Service Entity
34  EntityDomain
35 };
36 
37 /**
38  * Restriction Items
39  */
41  kerio::web::ItemName name;
42  kerio::web::RestrictionKind kind;
43  kerio::web::StringList values;
44 };
45 
46 /**
47  * Restriction tuple for 1 entity
48  */
49 typedef sequence<RestrictionTuple> RestrictionTupleList;
50 
51 /**
52  * Entity name restriction definition
53  */
54 struct Restriction {
55  Entity entityName; ///< IDL entity name, eg. User
56  RestrictionTupleList tuples; ///< Restriction tuples
57 };
58 
59 /**
60  * List of restrictions
61  */
62 typedef sequence<Restriction> RestrictionList;
63 
64 /**
65  * JavaScript timestamp
66  */
67 typedef string JavaScriptDate;
68 
69 /**
70  * Subscription information
71  */
73  boolean isUnlimited; ///< is it a special license with expiration == never ?
74  boolean showAlert; ///< show subscription expiration alert
75  long remainingDays; ///< days remaining to subscription expiration
76  JavaScriptDate subscriptionDate; ///< last date of subscription
77 };
78 
79 /**
80  * About information
81  */
82 struct AboutInfo {
83  long currentUsers; ///< number of created users on domain
84  MaximumUsers allowedUsers; ///< number of allowed users, take stricter limit from max. number for domain, max. number by license
85  string serverSoftware; ///< product name and version string, same as SERVER_SOFTWARE
86  SubscriptionInfo subscription; ///< information about subscription
87  string copyright; ///< copyright string
88  string productHomepage; ///< url to homepage of product
89 };
90 
91 /**
92  * Type of Alert
93  */
94 enum AlertName {
95  LicenseExpired, ///< License has expired
96  LicenseInvalidMinVersion, ///< Invalid minimal version of a product found
97  LicenseInvalidEdition, ///< The license was not issued for this edition of the product
98  LicenseInvalidUser, ///< The license was not issued for this user
99  LicenseInvalidDomain, ///< The license was not issued for this domain
100  LicenseInvalidOS, ///< The license was not issued for this operating system
101  LicenseCheckForwardingEnabled, ///< The license was not alowed forward the message to another host
102  LicenseTooManyUsers, ///< More users try login to their mailboxes then allowed License.
103  StorageSpaceLow, ///< Low space in storage
104  SubscriptionExpired, ///< Subscription has expired
105  SubscriptionSoonExpire, ///< Subscription soon expire
106  LicenseSoonExpire, ///< License soon expire
107  CoredumpFound, ///< Some coredump was found after crash
108  MacOSServicesKeepsPorts, ///< Apache on Lion server keeps ports (Eg. port 443), which are assigned to our services. See Services.stopMacOSServices()
109  RemoteUpgradeFailed, ///< Remote server upgrade failed
110  RemoteUpgradeSucceeded ///< Remote server upgrade succeeded
111 };
112 
113 /**
114  * Type of Alert
115  */
116 enum TypeAlert {
117  Warning,
118  Critical,
119  Info
120 };
121 
122 /**
123  * Alert
124  */
125 struct Alert {
126  AlertName alertName; ///< Alert Id
127  TypeAlert alertType; ///< Alert type
128  string currentValue; ///< Current Value
129  string criticalValue; ///< Critical Value
130 };
131 
132 typedef sequence<Alert> AlertList;
133 
134 /**
135  * Potential duplicate
136  */
138  Entity kind; ///< which entity was found as first duplicate
139  string name; ///< name of duplicate
140  string collisionAddress;
141  boolean win; ///< if entity is winner in this collision of mail address
142  boolean isPattern; ///< is true if it is the pattern to check (self duplicity)
143 };
144 
145 typedef sequence<EntityDuplicate> EntityDuplicateList;
146 
147 /**
148  * Detail about entity to be checked. Kind or id must be filled.
149  */
150 struct EntityDetail {
151  Entity kind; ///< which entity is inserting
152  kerio::web::KId id; ///< entity global identification of updated entity
153 };
154 
155 typedef sequence<string> UserNameList;
156 
157 struct FolderInfo {
158  string folderName;
159  long referenceCount;
160  boolean indexLoaded;
161  UserNameList users;
162 };
163 
164 typedef sequence<FolderInfo> FolderInfoList;
165 
166 struct WebSession {
167  string id;
168  string userName;
169  string clientAddress; ///< IPv4 address
170  string expirationTime; ///< format dd.mm.yyyy hh:mm:ss
171  WebComponent componentType; ///< what about CalDav, WebDav, ActiveSync
172  boolean isSecure; ///< is protocol secure
173 };
174 
175 typedef sequence<WebSession> WebSessionList;
176 
177 enum Protocol {
178  protocolAdmin,
179  protocolSmtp,
180  protocolSmtps,
181  protocolSubmission,
182  protocolPop3,
183  protocolPop3s,
184  protocolImap,
185  protocolImaps,
186  protocolNntp,
187  protocolNntps,
188  protocolLdap,
189  protocolLdaps,
190  protocolHttp,
191  protocolHttps,
192  protocolXmpp,
193  protocolXmpps
194 };
195 
196 enum HttpExtension {
197  NoExtension,
198  WebGeneric, ///< WebMail or WebMail Mini or WebAdmin
199  WebDav,
200  CalDav,
201  ActiveSync,
202  KocOffline,
203  KBC, ///< Kerio Connector for BlackBerry Enterprise Server
204  EWS ///< Exchange Web Services
205 };
206 
207 struct Connection {
208  Protocol proto;
209  HttpExtension extension;
210  boolean isSecure;
211  string time;
212  string from;
213  string user;
214  string description;
215 };
216 
217 typedef sequence<Connection> ConnectionList;
218 
219 /**
220  *
221  * Note: isEnabled, isLimited and groupId fields must be assigned if any of them is used in set methods
222  */
224  boolean isEnabled; ///< administration from other that local machine is enabled/disabled
225  boolean isLimited; ///< administration is limited
226  kerio::web::KId groupId; ///< IP Address Group identifier on which is limit applied
227  string groupName; ///< [READ-ONLY] IP Address Group name on which is limit applied
228 
229  boolean builtInAdminEnabled; ///< if is enabled field builtInAdminPassword is required
230  string builtInAdminUsername; ///< [READ-ONLY] user name
231  string builtInAdminPassword; ///< password
232  boolean builtInAdminPasswordIsEmpty; ///< [READ-ONLY] password is empty
233  boolean builtInAdminUsernameCollide; ///< [READ-ONLY] username colide with user in primary domain
234 };
235 
236 /**
237  * Server time information
238  */
240  long timezoneOffset; ///< +/- offset in minutes
241  DateTimeStamp startTime; ///< +/- start time of server
242  DateTimeStamp currentTime; ///< +/- current time on server
243 };
244 
245 /**
246  * Data Encryption Errors Constants
247  */
248 // 5000 to 5022 (SHould be the same as defined for ligdpr library)
249 const long ErrorCodeEncryptionFailed = 5000; ///< Encryption failed.
250 const long ErrorCodeNotEnoughSpace = 5001; ///< Not enough free space.
251 const long ErrorCodeDecryptionFailed = 5010; ///< Decryption failed.
252 const long ErrorCodeNotEnoughSpaceDec = 5011; ///< Not enough free space.
253 const long ErrorCodeIncorrectPassword = 5012; ///< Password is incorrect.
254 const long ErrorCodeIncPassWait = 5013; ///< Password is incorrect. You shall wait for a minute before you can try again.
255 const long ErrorCodeThreeAttempts = 5014; ///< You have 3 failed attempts to enter password. Please wait for a minute before you can try again.
256 const long ErrorCodeSavePassword = 5022; ///< Can't save the password.
257 
258 //Encrypted volume size errors
259 const long ErrorCodeLowDiskSpace = 6000; ///< Not enough free space
260 const long ErrorCodeCritLowDiskSpace = 6001; ///< Critically low free space
261 const long ErrorCodeTooMuchDiskSpace = 6002; ///< Encrypted volume allocate too much disk space
262 //resizing errors
263 const long ErrorCodeResizeFailed = 6010; ///< Encrypted volume resize failed
264 const long ErrorCodeResizeLowDiskSpace = 6011; ///< Not enough disk space to increase encrypted volume size
265 const long ErrorCodeResizeCritLowDiskSpace = 6012; ///< Critically low free space on encrypted volume and there is not enough disk space to increase encrypted volume
266 
267 
268 interface Server {
269 
270  /**
271  * Server creates an archive/backup path. If credentials aren't specified, values from current configuration of backup are used.
272  *
273  * @param result - result of create action
274  * @param path - new directory to create
275  * @param credentials - (optional) user name and password required to access network disk
276  */
277  void createPath(out DirectoryAccessResult result, in string path, in Credentials credentials);
278 
279  /**
280  * Find emails duplicate among entities in this order: resources, aliases, mailing lists, groups, users;
281  * caller must be authenticated; Note: creating duplicates is often allowed but may cause unwanted effects.
282  *
283  * @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
284  * @param addresses - list of email addresses (without domain) to be checked
285  * @param updatedEntity - identification of the current entity (to avoid self duplicity)
286  * @param domainId - domain identification
287  */
288  void findEntityByEmail(out EntityDuplicateList entities, in kerio::web::StringList addresses, in EntityDetail updatedEntity, in kerio::web::KId domainId);
289 
290  /**
291  * Generate a file with information for the support.
292  *
293  * @param fileDownload - description of output file
294  */
295  void generateSupportInfo(out kerio::web::Download fileDownload);
296 
297  /**
298  * Obtain information about server, caller must be authenticated.
299  *
300  * @param aboutInformation - information about server
301  */
302  void getAboutInfo(out AboutInfo aboutInformation);
303 
304  /**
305  * Obtain a list of alerts.
306  *
307  * @param alerts - list of alerts
308  */
309  void getAlertList(out AlertList alerts);
310 
311  /**
312  * Returns a list of user-preferred languages set in browser.
313  *
314  * @param calculatedLanguage - a list of 2-character language codes
315  */
316  void getBrowserLanguages(out kerio::web::StringList calculatedLanguage);
317 
318  /**
319  * Obtain client statistics settings.
320  *
321  * @param setting - new settings
322  */
323  void getClientStatistics(out boolean isEnabled);
324 
325  /**
326  * Obtain a list of columns dependent on callee role.
327  *
328  * @param columns - list of available columns
329  * @param objectName - name of the API object
330  * @param methodName - name of the method of appropriate object
331  */
332  void getColumnList(out kerio::web::StringList columns, in string objectName, in string methodName);
333 
334  /**
335  * Obtain information about active connections.
336  *
337  * @param list - active connections
338  * @param totalItems - total number of active connections
339  * @param query - condition and fields have no effect for this method
340  */
341  void getConnections(out ConnectionList list, out long totalItems, in kerio::web::SearchQuery query);
342 
343  /**
344  * Obtain a list of directories in a particular path.
345  *
346  * @param dirList - List of directories
347  * @param fullPath - directory for listing, if full path is empty logical drives will be listed
348  */
349  void getDirs(out DirectoryList dirList, in string fullPath);
350 
351  /**
352  * Obtain list of license extensions, caller must be authenticated.
353  *
354  * @param extensions - list of license extensions
355  */
356  void getLicenseExtensionsList(out kerio::web::StringList extensions);
357 
358  /**
359  * Server side list of constants.
360  *
361  * @param constants - list of constants
362  */
363  void getNamedConstantList(out NamedConstantList constants);
364 
365  /**
366  * Obtain information about folders opened on server.
367  *
368  * @param list - opened folders with info
369  * @param totalItems - total number of opened folders
370  * @param query - condition and fields have no effect for this method
371  */
372  void getOpenedFoldersInfo(out FolderInfoList list, out long totalItems, in kerio::web::SearchQuery query);
373 
374  /**
375  * Get basic information about product and its version.
376  *
377  * @param info - structure with basic information about product
378  */
379  void getProductInfo(out ProductInfo info);
380 
381  /**
382  * Obtain information about remote administration settings.
383  *
384  * @param setting - current settings
385  */
386  void getRemoteAdministration(out Administration setting);
387 
388  /**
389  * Obtain a hash string created from product name, version, and installation time.
390  *
391  * @param serverHash - server hash
392  */
393  void getServerHash(out string serverHash);
394 
395  /**
396  * List all server IP addresses.
397  *
398  * @param addresses - all IP addresses of the server
399  */
400  void getServerIpAddresses(out kerio::web::StringList addresses);
401 
402  /**
403  * Get server time information.
404  *
405  * @param info - structure with time information
406  */
407  void getServerTime(out ServerTimeInfo info);
408 
409  /**
410  * Obtain information about server version.
411  *
412  * @param product - name of product
413  * @param version - version in string consists of values of major, minor, revision, build a dot separated
414  * @param major - major version
415  * @param minor - minor version
416  * @param revision - revision number
417  * @param build - build number
418  */
419  void getVersion(out string product, out string version, out long major, out long minor, out long revision, out long build);
420 
421  /**
422  * Obtain information about web component sessions.
423  *
424  * @param list - web component sessions
425  * @param totalItems - total number of web component sessions
426  * @param query - condition and fields have no effect for this method
427  */
428  void getWebSessions(out WebSessionList list, out long totalItems, in kerio::web::SearchQuery query);
429 
430  /**
431  * Terminate actual web sessions.
432  *
433  * @param ids - list of web sessions IDs to terminate
434  */
435  void killWebSessions(in kerio::web::KIdList ids);
436 
437  /**
438  * Check if the selected path exists and is accessible from the server.
439  *
440  * @param path - directory name
441  * @param credentials - (optional) user name and password required to access network disk
442  * @param result - result of check
443  */
444  void pathExists(out DirectoryAccessResult result, in string path, in Credentials credentials);
445 
446  /**
447  * Reboot the host system.
448  */
449  void reboot();
450 
451  /**
452  * Restart server. The server must run as service.
453  */
454  void restart();
455 
456  /**
457  * Upgrade server to the latest version. The server must run as service.
458  */
459  void upgrade();
460 
461  /**
462  * Get progress of installation package downloading
463  *
464  * @param
465  * @param progress - download progress in percents (0-100)
466  */
467  void getDownloadProgress(out long progress);
468 
469  /**
470  * Send a bug report to Kerio.
471  *
472  * @param name - name of sender
473  * @param email - email of sender
474  * @param language - language of report
475  * @param subject - summary of report
476  * @param description - description of problem
477  */
478  void sendBugReport(in string name, in string email, in string language, in string subject, in string description);
479 
480  /**
481  * Set client statistics settings.
482  *
483  * @param setting - new settings
484  */
485  void setClientStatistics(in boolean isEnabled);
486 
487  /**
488  * Set new remote administration parameters.
489  *
490  * @param setting - new settings
491  */
492  void setRemoteAdministration(in Administration setting);
493 
494  /**
495  * Upload license manually from a file.
496  *
497  * @param fileId - ID of the uploaded file
498  */
499  void uploadLicense(in string fileId);
500 
501  /**
502  * Validate whether the administrator can cut off him/herself from the administration.
503  *
504  * @param setting - new setting
505  */
506  void validateRemoteAdministration(in Administration setting);
507 
508  /**
509  * Determine whether to use British or American flag for English.
510  *
511  * @param preferred - use British flag
512  */
513  void isBritishPreferred(out boolean preferred);
514 
515  /**
516  * Returns the encryption information
517  *
518  * @param result - encryption information
519  */
520  void getEncryptionStatus(out string status, out string action, out EncryptionError error, out EncryptionProgress progress);
521 
522  /**
523  * Returns Start encryption action
524  * @param params - action params
525  * @param result - encryption information
526  */
527  void startEncryption(in string password, out string status, out string action, out EncryptionError error, out EncryptionProgress progress);
528 
529  /**
530  * Returns Start descryption action
531  * @param params - action params
532  * @param result - encryption information
533  */
534  void startDecryption(in string password, out string status, out string action, out EncryptionError error, out EncryptionProgress progress);
535 
536  /**
537  * Returns Start descryption action
538  * @param params - action params
539  * @param result - encryption information
540  */
541  void startResizing(in string password, out string status, out string action, out EncryptionError error, out EncryptionProgress progress);
542 };
543 
544 }; }; };//end of namespace