All Classes Files Functions Variables Enumerations Enumerator Groups Pages
Users.idl
Go to the documentation of this file.
1 /**
2  * @file Users.idl
3  * @brief Work with user accounts as an representation of physical email boxes.
4  *
5  * @author Dusan Juhas, Martin Kuchar
6  *
7  * @copyright Copyright © 2011-2012 Kerio Technologies s.r.o.
8  */
9 
10 #import <kerio/web/idl/SharedStructures.idl>
11 #import <AdminStructures.idl> //ActionAfterDays
12 #import <common.idl> //DateTimeStamp
13 #import <ContactsCommon.idl>
14 #import <DistributedDomain.idl> //HomeServer
15 #import <MobileCommon.idl>
16 
17 module kerio {
18 module jsonapi {
19 module admin {
20 
21 struct PublicFolder {
22  kerio::web::KId id;
23  string name;
24 };
25 
26 typedef sequence<PublicFolder> PublicFolderList;
27 
28 /**
29  * List of email addresses
30  */
31 typedef sequence<string> UserEmailAddressList;
32 
33 /**
34  * Export format type.
35  */
36 enum FileFormatType {
37  TypeXml, ///< Extensible Markup Language
38  TypeCsv ///< Comma Separated Values
39 };
40 
41 /**
42  * Type of user role.
43  */
44 enum UserRoleType {
45  UserRole, ///< regular user without any administration rights
46  Auditor, ///< read only access to administration
47  AccountAdmin, ///< can administer Users,Groups,Aliases,MLs
48  FullAdmin, ///< unlimited administration
49  BuiltInAdmin ///< BuiltIn admin role can be returned only in Session::WhoAmI method for built-in administrator. This role must NOT be assigned.
50 };
51 
52 /**
53  *
54  * Note: all fields must be assigned if used in set methods.
55  */
56 struct UserRight {
57  UserRoleType userRole;
58  boolean publicFolderRight;
59  boolean archiveFolderRight;
60 };
61 
62 /**
63  * Forwarding setup for user.
64  */
65 enum UserForwardMode {
66  UForwardNone, ///< Forwarding is disabled
67  UForwardYes, ///< Forward all messages for this user to some addresses, don't deliver the message to the mailbox.
68  UForwardDeliver ///< Forward all messages for this user to some addresses, and also deliver the message to user's mailbox.
69 };
70 
71 /**
72  * Type of deleting folder of the user
73  */
74 enum UserDeleteFolderMode {
75  UDeleteUser, ///< Delete user without deleting his folder.
76  UDeleteFolder, ///< Delete user and delete his folder.
77  UMoveFolder ///< Delete user and his folder will move into another user's folder.
78 };
79 
80 /**
81  * Settings of email forwarding.
82  * Note: all fields must be assigned if used in set methods.
83  */
85  UserForwardMode mode;
86  UserEmailAddressList emailAddresses; ///< list of email addresses, make sense only for UForwardDeliver
87 };
88 
89 /**
90  * Properties of user's groups.
91  */
92 struct UserGroup {
93  kerio::web::KId id; ///< global identification
94  string name;
95  string description;
96  DataSource itemSource;
97 };
98 
99 /**
100  * List of user's groups.
101  */
102 typedef sequence<UserGroup> UserGroupList;
103 
104 /**
105  * Settings of items limit.
106  * Note: all fields must be assigned if used in set methods.
107  */
109  boolean isActive;
110  long limit;
111 };
112 
113 /**
114  * Amount of storage used and items currently stored in user's store.
115  */
116 struct QuotaUsage {
117  long items;
119 };
120 
121 /**
122  * List of QuotaUsage.
123  */
124 typedef sequence<QuotaUsage> QuotaUsageList;
125 
126 /**
127  * Last login information.
128  */
129 struct LastLogin {
130  DateTimeStamp dateTime; ///< date and time of last login
131  string protocol; ///< protocol name of last login, example POP3
132 };
133 
134 /**
135  * Per-user message retention policy.
136  */
137 struct CleanOut {
138  boolean isUsedDomain; ///< use domain settings
139  ActionAfterDays deletedItems; ///< clean Deleted Items folder (maximum: 24855)
140  ActionAfterDays junkEmail; ///< clean Junk Email folder (maximum: 24855)
141  ActionAfterDays sentItems; ///< clean Sent Items folder (maximum: 24855)
142  ActionAfterDays autoDelete; ///< clean all folders (maximum: 24855)
143 };
144 
145 /**
146  * User details.
147  */
148 struct User {
149  kerio::web::KId id; ///< [READ-ONLY] global identification
150  string loginName; ///< [REQUIRED FOR CREATE] [USED BY QUICKSEARCH] loginName name
151  string fullName; ///< [USED BY QUICKSEARCH]
152  string description; ///< [USED BY QUICKSEARCH]
153  boolean isEnabled; ///< user account is enabled/disabled
154  DataSource itemSource; ///< is user stored internally or by LDAP? This field cannot be used with Or queries.
155  UserAuthType authType; ///< supported values must be retrieved from engine by ServerInfo::getSupportedAuthTypes()
156  string password; ///< [WRITE-ONLY]
157  boolean isPasswordReversible; ///< typically triple DES
158  boolean allowPasswordChange; ///< if it is set to false the password can be changed only by the administrator
159  boolean hasDefaultSpamRule; ///< now: available only on user creation
160 
161  UserRight role; ///< user role
162  UserRight groupRole; ///< the mightiest user role obtained via group membership
163  UserRight effectiveRole; ///< the mightiest user role from role and groupRole
164  boolean isWritableByMe; ///< Does caller have right to change the user? E.g. if Account Admin gets User structure for Full Admin, isWritableByMe will be false. This field is read-only and cannot be used in kerio::web::SearchQuery conditions.
165 
166  kerio::web::KId domainId; ///< [REQUIRED FOR CREATE] ID of domain where user belongs to
167  UserEmailAddressList emailAddresses; ///< List of user email addresses. His default one (loginName@domain) is not listed here
168  EmailForwarding emailForwarding; ///< email forwarding setting
169  UserGroupList userGroups; ///< groups membership
170  ItemCountLimit itemLimit; ///< max. number of items
171  kerio::web::SizeLimit diskSizeLimit; ///< max. disk usage
172  long consumedItems; ///< current items used
174  boolean hasDomainRestriction; ///< user can send/receive from/to his/her domain only
175  kerio::web::SizeLimit outMessageLimit; ///< limit of outgoing message
176  LastLogin lastLoginInfo; ///< information about last login datetime and protocol
177  boolean publishInGal; ///< publish user in global address list? Default is true - the user will be published in Global Address Book.
178  CleanOut cleanOutItems; ///< Items clean-out settings
179  IdEntity accessPolicy; ///< ID and name of Access Policy applied for user. Only ID is writable.
180  kerio::web::KId companyContactId; ///< ID of company contact associated with this user
181 
182  HomeServer homeServer; ///< [WRITE-ONCE] Id of user's homeserver if server is in a distributed domain.
183  kerio::web::OptionalEntity migration; ///< [READ-ONLY] migration.enabled is true if user's store is just being migrated and migration.id contains migration task id
184 };
185 
186 /**
187  * List of users.
188  */
189 typedef sequence<User> UserList;
190 
191 /**
192 * User effective rights (inherited from groups)
193 */
195  kerio::web::KId userId; ///< [READ-ONLY] global identification
196  boolean hasDomainRestriction; ///< user can send/receive from/to his/her domain only
197 };
198 
199 /**
200  * List of users effective rights
201  */
202 typedef sequence<EffectiveUserRights> EffectiveUserRightsList;
203 
204 /**
205  * Type of user directory
206  */
207 enum ServerDirectoryType {
208  WinNT, ///< Windows NT Domain directory (Win NT 4.0)
209  ActiveDirectory, ///< Active Directory (Windows 2000 and newer)
210  NovellEDirectory ///< Novell eDirectory
211 };
212 
213 /**
214  * Properties of the server from which users are imported.
215  */
216 struct ImportServer {
217  ServerDirectoryType directoryType;
218  string remoteDomainName;
219  string address; ///< server IP or FQDN
220  string loginName;
221  string password;
222  string ldapFilter;
223  boolean isSecureConnection;
224 };
225 
226 /**
227  * Login statistics - count and timestamp of the last login.
228  */
229 struct LoginStats {
230  long count;
231  string lastLogin;
232 };
233 
234 /**
235  * Statistics about user's usage of quota, logins to different services.
236  */
237 struct UserStats {
238  string name; ///< user's loginName
239  QuotaUsage occupiedSpace;
240  LoginStats pop3;
241  LoginStats securePop3;
242  LoginStats imap;
243  LoginStats secureImap;
244  LoginStats http;
245  LoginStats secureHttp;
246  LoginStats ldap;
247  LoginStats secureLdap;
248  LoginStats nntp;
249  LoginStats secureNntp;
250  LoginStats activeSync;
251  LoginStats secureActiveSync;
252  LoginStats xmpp;
253  LoginStats secureXmpp;
254 };
255 
256 /**
257  * List of users' statistics.
258  */
259 typedef sequence<UserStats> UserStatList;
260 
261 /**
262  * Result of a mass operation.
263  */
265  long inputIndex;
266  long itemsCount;
267 };
268 
269 /**
270  * List of mass operation results.
271  */
272 typedef sequence<ResultTriplet> ResultTripletList;
273 
274 /**
275  * User to be removed, what to do with his/her mailbox.
276  */
278  kerio::web::KId userId; ///< ID of user to be removed
279  UserDeleteFolderMode method; ///< removal method
280  boolean removeReferences; ///< if true all reference to this user is going to be removed as well
281  kerio::web::KId targetUserId; ///< applicable only when moving user's store to another user, use empty string if not moving user's messages to target mailbox
282  DirectoryServiceDeleteMode mode; ///< delete mode
283 };
284 
285 typedef sequence<RemovalRequest> RemovalRequestList;
286 
287 /**
288  * A user being imported from directory server.
289  */
290 struct Importee {
291  User userItem; ///< user data
292  boolean isImportable; ///< user can be imported
293  string message; ///< error message if user is not importable
294 };
295 
296 typedef sequence<Importee> ImporteeList;
297 
298 struct MailboxCount {
299  long active; ///< the number of active mailboxes on server
300  long total; ///< the number of created users on server
301 };
302 
303 /**
304  * Resut of autentication.
305  */
306 enum AuthResult {
307  AuthOK, ///< User was autenticated
308  AuthFail, ///< Wrong login name or password.
309  AuthUserDisabled, ///< User cannot to log in, because his account is disabled.
310  AuthLicense, ///< User cannot log in, because license limit was reached.
311  AuthDenied, ///< User is denied to log in.
312  AuthTryLater ///< User cannot to log in at this moment, try later.
313 };
314 
315 
316 /**
317  * User accounts management.
318  */
319 interface Users {
320 
321  /**
322  * Activate user(s) from a directory service.
323  *
324  * @param errors - list of error messages for appropriate users
325  * @param userIds - list of global user identifiers
326  */
327  void activate(out kerio::web::ErrorList errors, in kerio::web::KIdList userIds);
328 
329  /**
330  * Activate user(s) from a directory service in distributed domain environment.
331  *
332  * @param errors - list of error messages for appropriate users
333  * @param userIds - list of global user identifiers
334  * @param homeServerId - Id of server in distributed domain on which users will be activated
335  */
336  void activateOnServer(out kerio::web::ErrorList errors, in kerio::web::KIdList userIds, in kerio::web::KId homeServerId);
337 
338  /**
339  * Register connection.
340  *
341  * @param service - service name
342  * @param connectionId - unique connection identifier
343  * @param port - host port
344  * @param isSecure - ssl connection
345  */
346  void connectFromExternalService(out boolean result, in string service, in string connectionId, in string clientIpAddress, in long port, in boolean isSecure);
347 
348  /**
349  * Authenticate given user and create session. connectionId must be registered by function connectFromExternalService otherwise authenticate fails.
350  *
351  * @param result - resut of autentication.
352  * @param userName - login name + domain name (can be omitted if primary) of the user to be logged in, e.g. "jdoe" or "jdoe@company.com"
353  * @param password - password of the user to be authenticate
354  * @param connectionId - connection identifier, must be the same as in connectFromExternalService
355  * @param isSecure - ssl connection
356  */
357  void authenticateConnectionFromExternalService(out AuthResult result, in string userName, in string password, in string service, in string connectionId, in boolean isSecure);
358 
359  /**
360  * Unregister connection registered by connectFromExternalService and destroy session created if authenticateFromExternalService was called.
361  * @param service - service name
362  * @param connectionId - unique connection identifier
363  */
364  void disconnectFromExternalService(in string service, in string connectionId);
365 
366  /**
367  * Cancel wiping of user's mobile device.
368  *
369  * @param userId - global user identifier
370  * @param deviceId - ID of user's mobile device to cancel wipe
371  */
372  void cancelWipeMobileDevice(in kerio::web::KId userId, in string deviceId);
373 
374  /**
375  * Check integrity of all folders in user(s) mailboxes.
376  * If corrupted folder is found, try to fix it.
377  *
378  * @param userIds - list of user identifiers
379  */
380  void checkMailboxIntegrity(in kerio::web::KIdList userIds);
381 
382  /**
383  * Create new users.
384  *
385  * @param errors - error message list
386  * @param result - list of IDs of created users
387  * @param users - new user entities
388  */
389  void create(out kerio::web::ErrorList errors, out kerio::web::CreateResultList result, in UserList users);
390 
391  /**
392  * Create new users in directory service
393  * @param errors - error message list
394  * @param result - list of IDs of created users
395  * @param users - new user entities
396  */
397  void createLdap(out kerio::web::ErrorList errors, out kerio::web::CreateResultList result, in UserList users);
398 
399  /**
400  * Export statistics of given users in given format.
401  *
402  * @param fileDownload - description of output file
403  * @param userIds - list of IDs of given users
404  * @param format - output data format
405  */
406  void exportStatistics(out kerio::web::Download fileDownload, in kerio::web::KIdList userIds, in FileFormatType format);
407 
408  /**
409  * Export given domain users to comma-separated values file format.
410  *
411  * @param fileDownload - description of output file
412  * @param filename - part of filename; full filename is compound as user_<domainname>_<filename>_<date>.csv
413  * @param query - query attributes and limits
414  * @param domainId - domain identification
415  */
416  void exportToCsv(out kerio::web::Download fileDownload, in string filename, in kerio::web::SearchQuery query, in kerio::web::KId domainId);
417 
418  /**
419  * Obtain a list of users in given domain.
420  *
421  * @param list - users
422  * @param totalItems - number of users found in given domain
423  * @param query - query attributes and limits
424  * @param domainId - domain identification
425  */
426  void get(out UserList list, out long totalItems, in kerio::web::SearchQuery query, in kerio::web::KId domainId);
427 
428  /**
429  * Obtain a list of contact public folders in given domain.
430  *
431  * @param publicFolderList - list of public folders
432  * @param domainId - global identification of domain
433  */
434  void getContactPublicFolderList(out PublicFolderList publicFolders, in kerio::web::KId domainId);
435 
436  /**
437  * Obtain list of users from given LDAP server potentially importable to the Connect server.
438  *
439  * @param newUsers - list of users
440  * @param importServer - properties of the server to import from
441  * @param domainToImport - the mailserver domain where users are imported
442  */
443  void getFromServer(out ImporteeList newUsers, in ImportServer importServer, in kerio::web::KId domainToImport);
444 
445  /**
446  * Obtain the number of users created on the server and number of active mailboxes.
447  * This method may take a long time if a directory service for mapped users is not available.
448  *
449  * @param count - Number of users created on the server and number of active mailboxes.
450  */
451  void getMailboxCount(out MailboxCount count);
452 
453  /**
454  * Obtain a list of mobile devices of given user.
455  *
456  * @param list - mobile devices of given user
457  * @param totalItems - number of mobile devices found for given user
458  * @param userId - name of user
459  * @param query - query attributes and limits
460  */
461  void getMobileDeviceList(out kerio::jsonapi::mobile::MobileDeviceList list, out long totalItems, in kerio::web::KId userId, in kerio::web::SearchQuery query);
462 
463  /**
464  * Obtain a list of LDAP mapped users who are not activated in given domain.
465  * Only user's ID, loginName, fullName, description are set in structures.
466  *
467  * @param newUsers - list of users
468  * @param domainId - global identification of domain
469  */
470  void getNotActivated(out ImporteeList newUsers, in kerio::web::KId domainId);
471 
472  /**
473  * Obtain a size of items stored for recovering.
474  *
475  * @param errors - error message list
476  * @param sizes - count and size of items
477  * @param userIds - global identification of user
478  */
479  void getRecoveryDeletedItemsSize(out kerio::web::ErrorList errors, out QuotaUsageList sizeList, in kerio::web::KIdList userIds);
480 
481  /**
482  * Obtain statistics of given users.
483  *
484  * @param list - users' statistics
485  * @param userIds - list of IDs of given users
486  * @param query - query parameters and limits
487  */
488  void getStatistics(out UserStatList list, in kerio::web::KIdList userIds, in kerio::web::SearchQuery query);
489 
490  /**
491  * Parse users from given string. It is used to import users from file. The only supported encoding is UTF-8.
492  *
493  * @param users - list of parsed users with appropriate status and message
494  * @param fileId - ID of the uploaded file
495  * @param domainToImport - import to given domain, magic constants
496  * 'PRIMARY_DOMAIN': use primary domain
497  * 'PRESERVE_FROM_CSV': preserve domain from CSV file (use primary if not defined)
498  */
499  void parseFromCsv(out ImporteeList users, in string fileId, in kerio::web::KId domainToImport);
500 
501  /**
502  * Recover deleted items for particular user(s).
503  * If the user quota is exceeded an error with code 4000 will be returned.
504  *
505  * @param recoveryMessages - list of recovery messages
506  * @param userIds - list of user IDs
507  * @param recoverAnyway - if true messages are recovered even if the user quota is exceeded.
508  */
509  void recoverDeletedItems(out kerio::web::ErrorList errors, out ResultTripletList recoveryMessages, in kerio::web::KIdList userIds);
510 
511  /**
512  * Remove user(s).
513  *
514  * @param errors - list of users failed to remove only (successfully removed are NOT listed)
515  * @param requests - list of user IDs to be removed, method, and owner of deleted messages
516  */
517  void remove(out kerio::web::ErrorList errors, in RemovalRequestList requests);
518 
519  /**
520  * Remove mobile device from the list of user's mobile devices.
521  *
522  * @param userId - name of user
523  * @param deviceId - ID of user's mobile device to be removed
524  */
525  void removeMobileDevice(in kerio::web::KId userId, in string deviceId);
526 
527  /**
528  * IM: Reset buddy list of selected users
529  *
530  * @param userIds - list of user identifiers
531  */
532  void resetBuddyList(in kerio::web::KIdList userIds);
533 
534 
535  /**
536  * Obtains user effective rights (inherited from groups)
537  *
538  * @param errors - list of users failed to get effective rights
539  * @param result - list of effective rights
540  * @param userIds - list of IDs of users
541  */
542  void getEffectiveUserRights(out kerio::web::ErrorList errors, out EffectiveUserRightsList result, in kerio::web::KIdList userIds);
543 
544 
545  /**
546  * Set users' details according given pattern.
547  *
548  * @param errors - create a new user
549  * @param userIds - list of IDs of users to be changed
550  * @param pattern - pattern to use for new values
551  */
552  void set(out kerio::web::ErrorList errors, in kerio::web::KIdList userIds, in User pattern);
553 
554  /**
555  * Wipe user's mobile device.
556  *
557  * @param userId - global user identifier
558  * @param deviceId - ID of user's mobile device to be wiped
559  */
560  void wipeMobileDevice(in kerio::web::KId userId, in string deviceId);
561 
562  /**
563  * Get personal user contacts
564  *
565  */
566  void getPersonalContact(out kerio::web::ErrorList errors, out kerio::jsonapi::contacts::PersonalContactList contacts, in kerio::web::KIdList userIds);
567 
568  /**
569  * Set personal user contacts
570  *
571  */
572  void setPersonalContact(out kerio::web::ErrorList errors, in kerio::web::KIdList userIds, in kerio::jsonapi::contacts::PersonalContact contact);
573 };
574 
575 }; }; };//end of namespace