SessionManager.idl

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2009 Raritan Inc. All rights reserved.
 */

/**
 * %Session Management
 */
module session {

    /** %Session information */
    structure Session_2_0_0 {
        int sessionId;          ///< ID of the session
        string username;        ///< Name of user owning the session
        string remoteIp;        ///< Session IP address
        string clientType;      ///< Client type
        time creationTime;      ///< Session creation timestamp
        int timeout;            ///< Session timeout in seconds
        int idle;               ///< Session idle time in seconds
        int userIdle;           ///< User idle time in seconds
    };

    /** %Session history entry */
    structure HistoryEntry {
        time creationTime;      ///< Session creation timestamp
        string remoteIp;        ///< Session IP address
        string clientType;      ///< Session client type
    };

    /**
     * %Session manager interface
     * 
     * Session manager allows clients to announce a user session, 
     * i.e. consecutive activity that is related to each other, 
     * and make use of session services.
     * Depending on transport protocoll an established session 
     * allows simplified authentication using the session token.
     * For instance, for HTTP transport implementation sessiontoken
     * can be written into HTTP Header while other authentication
     * schemes may be omitted (for details, see transport mapping
     * documentation).
     * Each session has a defined timeout and an idle timer. 
     * A session is deleted once idle time is equal or greater 
     * than session timeout. Idle timer is implicitely touched
     * by transport implementation whenever a call arrives that 
     * can be mapped to a particular session. In addition a client
     * may decide to call touchCurrentSession with userActivity flag
     * set to true. In this case userIdle attribute of session is reset
     * to 0. This has purely informational character and will not cause 
     * any further action of session manager. It may be used to determine
     * user activity under the assumptions that clients may do frequent 
     * background calls without actual user activity. 
     */
    interface SessionManager_2_0_0 {

        constant int ERR_ACTIVE_SESSION_EXCLUSIVE_FOR_USER = 1; ///< Session creation denied due to single login limitation

        /** %Session close reasons */
        enumeration CloseReason {
            CLOSE_REASON_LOGOUT,                ///< Regular logout
            CLOSE_REASON_TIMEOUT,               ///< Session timed out
            CLOSE_REASON_BROWSER_CLOSED,        ///< Browser window was closed
            CLOSE_REASON_FORCED_DISCONNECT      ///< Session was forcibly closed
        };

        /**
         * Open a new session.
         *
         * This function will create a new session for the authenticated user.
         * Upon success it will return a session token which can be used to
         * authenticate future requests.
         *
         * @param session  %Session information
         * @param token    Returned token for the newly created session
         *
         * @return 0 if OK
         * @return 1 if session creation was denied due to single login limitation
         */
        int newSession(out Session_2_0_0 session, out string token);

        /**
         * Retrieve current session information.
         *
         * This call must be authenticated using a session token.
         *
         * @return %Session information
         */
        Session_2_0_0 getCurrentSession();

        /**
         * Retrieve all open sessions.
         *
         * @return List of sessions
         */
        vector<Session_2_0_0> getSessions();
        
        /**
         * Close a session identified by its token.
         *
         * @param sessionId ID of the session that should be closed
         * @param reason    close reason
         */
        void closeSession(in int sessionId, in CloseReason reason);

        /**
         * Close the current session.
         *
         * This call must be authenticated using a session token.
         *
         * @param reason close reason
         */
        void closeCurrentSession(in CloseReason reason);

        /**
         * Reset the current session's idle timer.
         *
         * @param userActivity  Indicates that the session is touched
         *                      due to user activity.
         *
         * If userActivity is not set, this is internally a NOP since
         * any RPC call will implicitly touch the session.
         * This call must be authenticated using a session token.
         */
        void touchCurrentSession(in boolean userActivity);

        /**
         * Get previous session data for the current user 
         *
         * @return History data, sorted from newer to older sessions
         */
        vector<HistoryEntry> getSessionHistory();
    };

}