Users.idl

Go to the documentation of this file.

/**
 * @file     Users.idl
 * @brief    API for Kerio Control Users
 * @version  3
 */

#import <kerio/web/idl/SharedStructures.idl>
#import <common.idl>

module webadmin {

enum UserConditionType {
   AnyUser,
   AuthenticatedUsers,
   UnrecognizedUsers,
   SelectedUsers,
   Nobody
};

/**
 * Roles in webadmin correspond with user rights. If user doesn't have even
 * read right, he can't create session, so there is no "none" in the enum
 */
enum UserRoleType {
   Auditor,
   FullAdmin
};

typedef sequence<UserRoleType> UserRoleList;

enum AuthType {
   Internal,
   KerberosNt
};

struct UserRights {
   boolean readConfig;
   boolean writeConfig;
   boolean overrideWwwFilter;
   boolean unlockRule;
   boolean dialRasConnection;
   boolean connectVpn;
   boolean connectSslVpn;
   boolean useP2p;
};

enum QuotaType {
   QuotaBoth,
   QuotaDownload,
   QuotaUpload
};

struct QuotaInterval {
   boolean enabled;
   QuotaType type;
   kerio::web::ByteValueWithUnits limit;
};

struct Quota {
   QuotaInterval daily;
   QuotaInterval weekly;
   QuotaInterval monthly;
   
   boolean blockTraffic;
   boolean notifyUser;
};

struct WwwFilter {
   boolean javaApplet; /* true => HTML content is filtered (disabled) */
   boolean embedObject;
   boolean script;
   boolean popup;
   boolean referer;
};

/** common user data, used in domain template */
struct UserData {
   UserRights rights;
   Quota quota;
   WwwFilter wwwFilter;
   string language;    /** see spec id 217 */
};

struct AutoLogin {
   OptionalStringList macAddresses;
   OptionalIpAddressList addresses;
   kerio::web::OptionalEntity addressGroup;
};

/** user or group reference, used as "member of group" in user, "have member" in group and in various policies */
struct UserReference {
   kerio::web::KId id;
   string name;
   boolean isGroup;
   string domainName;
};

typedef sequence<UserReference> UserReferenceList;

enum AddresseeType {
  AddresseeEmail,
  AddresseeUser
};

struct Addressee {
  AddresseeType type;
  string        email;
  
  /*@{ valid for type AddresseeUser */
  UserReference user;
  /*@}*/
};

struct UserCondition {
   UserConditionType type;
   UserReferenceList users;
};

struct UserSettings {
   string calculatedLanguage;
   string language;
   string detectedLanguage;
   UserRoleList roles;
   UserReference user;
   string fullName;
   string email;
};

struct User {
   kerio::web::KId id;
   CredentialsConfig credentials;      /** username char[128], passwd char [128] */
   string fullName;              /** char [128] */
   string description;                 /** char [128] */
   string email;                       /** char [128] */
   AuthType authType;
   boolean localEnabled;
   boolean adEnabled;
   boolean useTemplate;
   UserData data;                      /** if uses template, data may not be loaded from configuration */
   AutoLogin autoLogin;
   OptionalIpAddress vpnAddress;
   UserReferenceList groups;
   boolean conflictWithLocal;          /** read only */
   boolean totpConfigured;          /** can be cleared, but not configured */
};

typedef sequence<User> UserList;

interface Users {

   /**
    * Obtain list of users in given domain
    *
    * @param  warnings - list of warnings \n
    *          8003  Users conflict.       - "Some user names are in conflict with users in the local user database." \n
    *          8004  Authentication Error. - "Some user accounts are not functional, authentication in the directory service and/or Windows NT® domain is not active." \n
    * @param  list - list of users and it's details
    * @param  totalItems - count of all users on server (before the start/limit applied)
    * @param  query - conditions and limits
    * @param  domainId - id of domain - only users from this domain will be listed
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.      - "The user is not logged in." \n
    *          1000  Operation failed.     - "Directory service error: %1." \n
    *          1004  Access denied.        - "Insufficient rights to perform the requested operation."
    */
   void get(out kerio::web::ErrorList warnings, out UserList list, out long totalItems, in kerio::web::SearchQuery query, in kerio::web::KId domainId);

   /**
    * Add new user
    *
    * @param  errors - list of errors \n
    *          1000  Operation failed. - "Unable to add item." \n
    *          1001  Already exists.   - "User %1 already exists." \n
    *          8001  Invalid params.   - "Unable to add/modify user %1, wrong parameters." \n
    *          8002  Database error.   - "Unable to add/modify user %1, it may already exist." \n
    * @param result - list of IDs assigned to each item     
    * @param users - details for new users. field id is assigned by the manager to temporary value until apply() or reset().
    * @param domainId - id of domain - specifies domain, where user will be created (only local is supported)
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.  - "The user is not logged in." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation."
    */
   void create(out kerio::web::ErrorList errors, out kerio::web::CreateResultList result, in UserList users, in kerio::web::KId domainId);

   /**
    * Update users' details
    *
    * @param  errors - list of errors \n
    *          1001  Already exists.  - "User %1 already exists." \n
    *          8001  Invalid params.  - "Unable to add/modify user %1, wrong parameters." \n
    *          8002  Database error.  - "Unable to add/modify user %1, it may already exist."
    * @param userIds - ids of users to be updated.
    * @param details - details for update. Field "kerio::web::KId" is ignored. Only filled details will be stored in users config defined by userIds
    * @param domainId - id of domain - users from this domain will be updated
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation."
    */
   void set(out kerio::web::ErrorList errors, in kerio::web::KIdList userIds, in User details, in kerio::web::KId domainId);

   /**
    * Delete users
    *
    * @param  errors - list of errors \n
    *          1000  Operation failed. - "Unable to remove item." \n
    *          1000  Operation failed. - "Unable to delete Admin user." \n
    *          8002  Database error.   - "Unable to delete the user."
    * @param userIds - ids of users that should be removed
    * @param domainId - id of domain - specifies domain, where user will be removed (only local is supported)
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.  - "The user is not logged in." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation."
    */
   void remove(out kerio::web::ErrorList errors, in kerio::web::KIdList userIds, in kerio::web::KId domainId);

   /**
    * replace all conflicting local users with domain users in policies
    * @param domainId - id of domain - specifies domain, from which users will be loaded
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.  - "The user is not logged in." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation."
    */
   void convertLocalUsers(in kerio::web::KId domainId);

   /**
    * Returns list of users suitable for import
    * 
    * @param users - list of users and details
    * @param domainName - name of AD domain
    * @param server - AD server
    * @param credentials - username and password for user with read privilegies 
    * @param ldapSecure - use secured connection
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.  - "The user is not logged in." \n
    *          1000  Operation failed. - "Directory service error: %1." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation."
    */
   void getAdUsers(out UserList users, in string domainName, in string server, in CredentialsConfig credentials, in boolean ldapSecure);
   
   /**
    * Returns list of users suitable for import
    * 
    * @param users - list of users and details
    * @param domainName - name of NT domain
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.  - "The user is not logged in." \n
    *          1000  Operation failed. - "Failed to list Windows NT domain users, error: %1." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation."
    */
   void getNtUsers(out UserList users, in string domainName);

   /**
    * supported languages, name like "Cestina" in utf8, value in configuration, default value is "detect"
    *
    * @param languages - list of languages
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.  - "The user is not logged in." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation."
    */
   void getSupportedLanguages(out kerio::web::NamedValueList languages);

   /**
    * Returns list of user's settings
    * 
    * @param settings - list of all settings
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.  - "The user is not logged in." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation."
    */
   void getMySettings(out UserSettings settings);

   /**
    * Stores list of user's settings
    * 
    * @param settings - list of all settings
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.  - "The user is not logged in." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation."
    */
   void setMySettings(in UserSettings settings);

   /**
    * Checks, if autoLogin and vpnAddress params are unique and returns appropriate warnings if so
    * 
    * @param errors - list of all warnings
    * @param user - user data
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired.  - "The user is not logged in." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation."
    */
   void checkWarnings(out kerio::web::ErrorList errors, in User user);
};

}; //webadmin