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 © 2017 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 interface Server {
246 
247  /**
248  * Server creates an archive/backup path. If credentials aren't specified, values from current configuration of backup are used.
249  *
250  * @param result - result of create action
251  * @param path - new directory to create
252  * @param credentials - (optional) user name and password required to access network disk
253  */
254  void createPath(out DirectoryAccessResult result, in string path, in Credentials credentials);
255 
256  /**
257  * Find emails duplicate among entities in this order: resources, aliases, mailing lists, groups, users;
258  * caller must be authenticated; Note: creating duplicates is often allowed but may cause unwanted effects.
259  *
260  * @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
261  * @param addresses - list of email addresses (without domain) to be checked
262  * @param updatedEntity - identification of the current entity (to avoid self duplicity)
263  * @param domainId - domain identification
264  */
265  void findEntityByEmail(out EntityDuplicateList entities, in kerio::web::StringList addresses, in EntityDetail updatedEntity, in kerio::web::KId domainId);
266 
267  /**
268  * Generate a file with information for the support.
269  *
270  * @param fileDownload - description of output file
271  */
272  void generateSupportInfo(out kerio::web::Download fileDownload);
273 
274  /**
275  * Obtain information about server, caller must be authenticated.
276  *
277  * @param aboutInformation - information about server
278  */
279  void getAboutInfo(out AboutInfo aboutInformation);
280 
281  /**
282  * Obtain a list of alerts.
283  *
284  * @param alerts - list of alerts
285  */
286  void getAlertList(out AlertList alerts);
287 
288  /**
289  * Returns a list of user-preferred languages set in browser.
290  *
291  * @param calculatedLanguage - a list of 2-character language codes
292  */
293  void getBrowserLanguages(out kerio::web::StringList calculatedLanguage);
294 
295  /**
296  * Obtain client statistics settings.
297  *
298  * @param setting - new settings
299  */
300  void getClientStatistics(out boolean isEnabled);
301 
302  /**
303  * Obtain a list of columns dependent on callee role.
304  *
305  * @param columns - list of available columns
306  * @param objectName - name of the API object
307  * @param methodName - name of the method of appropriate object
308  */
309  void getColumnList(out kerio::web::StringList columns, in string objectName, in string methodName);
310 
311  /**
312  * Obtain information about active connections.
313  *
314  * @param list - active connections
315  * @param totalItems - total number of active connections
316  * @param query - condition and fields have no effect for this method
317  */
318  void getConnections(out ConnectionList list, out long totalItems, in kerio::web::SearchQuery query);
319 
320  /**
321  * Obtain a list of directories in a particular path.
322  *
323  * @param dirList - List of directories
324  * @param fullPath - directory for listing, if full path is empty logical drives will be listed
325  */
326  void getDirs(out DirectoryList dirList, in string fullPath);
327 
328  /**
329  * Obtain list of license extensions, caller must be authenticated.
330  *
331  * @param extensions - list of license extensions
332  */
333  void getLicenseExtensionsList(out kerio::web::StringList extensions);
334 
335  /**
336  * Server side list of constants.
337  *
338  * @param constants - list of constants
339  */
340  void getNamedConstantList(out NamedConstantList constants);
341 
342  /**
343  * Obtain information about folders opened on server.
344  *
345  * @param list - opened folders with info
346  * @param totalItems - total number of opened folders
347  * @param query - condition and fields have no effect for this method
348  */
349  void getOpenedFoldersInfo(out FolderInfoList list, out long totalItems, in kerio::web::SearchQuery query);
350 
351  /**
352  * Get basic information about product and its version.
353  *
354  * @param info - structure with basic information about product
355  */
356  void getProductInfo(out ProductInfo info);
357 
358  /**
359  * Obtain information about remote administration settings.
360  *
361  * @param setting - current settings
362  */
363  void getRemoteAdministration(out Administration setting);
364 
365  /**
366  * Obtain a hash string created from product name, version, and installation time.
367  *
368  * @param serverHash - server hash
369  */
370  void getServerHash(out string serverHash);
371 
372  /**
373  * List all server IP addresses.
374  *
375  * @param addresses - all IP addresses of the server
376  */
377  void getServerIpAddresses(out kerio::web::StringList addresses);
378 
379  /**
380  * Get server time information.
381  *
382  * @param info - structure with time information
383  */
384  void getServerTime(out ServerTimeInfo info);
385 
386  /**
387  * Obtain information about server version.
388  *
389  * @param product - name of product
390  * @param version - version in string consists of values of major, minor, revision, build a dot separated
391  * @param major - major version
392  * @param minor - minor version
393  * @param revision - revision number
394  * @param build - build number
395  */
396  void getVersion(out string product, out string version, out long major, out long minor, out long revision, out long build);
397 
398  /**
399  * Obtain information about web component sessions.
400  *
401  * @param list - web component sessions
402  * @param totalItems - total number of web component sessions
403  * @param query - condition and fields have no effect for this method
404  */
405  void getWebSessions(out WebSessionList list, out long totalItems, in kerio::web::SearchQuery query);
406 
407  /**
408  * Terminate actual web sessions.
409  *
410  * @param ids - list of web sessions IDs to terminate
411  */
412  void killWebSessions(in kerio::web::KIdList ids);
413 
414  /**
415  * Check if the selected path exists and is accessible from the server.
416  *
417  * @param path - directory name
418  * @param credentials - (optional) user name and password required to access network disk
419  * @param result - result of check
420  */
421  void pathExists(out DirectoryAccessResult result, in string path, in Credentials credentials);
422 
423  /**
424  * Reboot the host system.
425  */
426  void reboot();
427 
428  /**
429  * Restart server. The server must run as service.
430  */
431  void restart();
432 
433  /**
434  * Upgrade server to the latest version. The server must run as service.
435  */
436  void upgrade();
437 
438  /**
439  * Get progress of installation package downloading
440  *
441  * @param
442  * @param progress - download progress in percents (0-100)
443  */
444  void getDownloadProgress(out long progress);
445 
446  /**
447  * Send a bug report to Kerio.
448  *
449  * @param name - name of sender
450  * @param email - email of sender
451  * @param language - language of report
452  * @param subject - summary of report
453  * @param description - description of problem
454  */
455  void sendBugReport(in string name, in string email, in string language, in string subject, in string description);
456 
457  /**
458  * Set client statistics settings.
459  *
460  * @param setting - new settings
461  */
462  void setClientStatistics(in boolean isEnabled);
463 
464  /**
465  * Set new remote administration parameters.
466  *
467  * @param setting - new settings
468  */
469  void setRemoteAdministration(in Administration setting);
470 
471  /**
472  * Upload license manually from a file.
473  *
474  * @param fileId - ID of the uploaded file
475  */
476  void uploadLicense(in string fileId);
477 
478  /**
479  * Validate whether the administrator can cut off him/herself from the administration.
480  *
481  * @param setting - new setting
482  */
483  void validateRemoteAdministration(in Administration setting);
484 
485  /**
486  * Determine whether to use British or American flag for English.
487  *
488  * @param preferred - use British flag
489  */
490  void isBritishPreferred(out boolean preferred);
491 };
492 
493 }; }; };//end of namespace