Session.idl

Go to the documentation of this file.

/**
 * @file     Session.idl
 * @brief    Session for webadmin
 * @version  2
 */

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

module webadmin {

/**
  * Describes client (third-party) application or script which uses the Administration API.
  */
struct ApiApplication {
   string name;       ///< E.g. "Simple server monitor"
   string vendor;     ///< E.g. "MyScript Ltd."
   string version;    ///< E.g. "1.0.0 beta 1"
};

enum LoginType {
   LoginRegular,
   LoginAutomatic,
   LoginReactivation
};

struct ClientTimestamp {
   string name;
   long timestamp;
};

typedef sequence<ClientTimestamp>  ClientTimestampList;

/** May be created only if user is authenticated (request contains valid cookie) */
interface Session
{
   /**
    * Retrieves an unique session ID intended to be used for CSRF protection in web forms. \n
    * This ID is different from the session cookie but also remains the same during the session lifetime.
    *
    * @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 getCsrfToken(out string token);

   /**
    * Retrieves name os logged user
    *
    * @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 getUserName(out string name);
   
   /**
    * Log in given user.
    *
    * Please note that with a session to one module you cannot use another one (eg. with admin session you cannot use webmail).
    *
    * @param token - CSRF attack prevention token, use it as X-Token HTTP header
    * @param userName - login name + domain name (can be omitted if primary/local) of the user to be logged in, e.g. "jdoe" or "jdoe@company.com"
    * @param password - password of the user to be logged in
    * @param application - client application description
    *
    * @throws kerio::web::ApiException \n
    *          1000  Operation failed. - "Username or password is not correct." \n
    *          1004  Access denied.    - "Insufficient rights to perform the requested operation."
    */
   [KAuthentication(AuthenticationMode.NO_AUTHENTICATION_REQUIRED)]
  [KLoginMethod]
   void login(out string token, in string userName, in string password, in ApiApplication application);

   /** 
    * destroys session
    *
    * @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."
    */
  [KLogoutMethod]
   void logout();

   /** 
    * Returns clients defined variable stored in configuration for logged user
    *
    * @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 getSessionVariable(in string name, out string value);

   /** 
    * Stores clients defined variable to configuration for logged user
    *
    * @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 setSessionVariable(in string name, in string value);

   /** 
    * reset all persistent objects (managers) in session
    *
    * @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 reset();
   
   /**
    * Reloads configuration and returns timestamp of current configuration
    * @param clientTimestampList - is empty in case, that cut-off prevention is not active
    *
    * @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 getConfigTimestamp(out ClientTimestampList clientTimestampList);
   
   /**
    * Confirm the new configuration
    * @param confirmed - true in case, that cut-off prevention was active and timestamp matched last provided timestamp
    * @param clientTimestampList - values obtained by getConfigTimestamp
    *
    * @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 confirmConfig(out boolean confirmed, in ClientTimestampList clientTimestampList);

   /**
    * Returns id of interface through which is client connected to server
    * @param id - id of interface or empty in case of localhost
    *
    * @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 getConnectedInterface(out kerio::web::KId id);
   
   /**
    * Returns type of login, that has to be performed
    *
    * @param type - type of login
    */
   [KAuthentication(AuthenticationMode.NO_AUTHENTICATION_REQUIRED)]
   void getLoginType(out LoginType type);
};

}; //webadmin