SessionManager.idl

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2009 Raritan Inc. All rights reserved.
 */
 
/**
 * %Session Management
 */
 
#include <Event.idl>
 
module session {
 
    /** %Session information */
    structure Session {
        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 (seconds since system boot)
        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 (UNIX timestamp, UTC)
        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 protocol an established session
     * allows simplified authentication using the session token.
     * For instance, for HTTP transport implementation session token
     * 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 implicitly 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 {
 
        constant int ERR_ACTIVE_SESSION_EXCLUSIVE_FOR_USER = 1; ///< Session creation denied due to single login limitation
        constant int ERR_NO_SUCH_SESSION = 2;                   ///< Session for provided data could not be found
 
        /** %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 session, out string token);
 
        /**
         * Retrieve an existing session using CC-SG provided session data
         *
         * @param sessionId  Session ID
         * @param sessionKey Session key
         * @param session    %Session information
         * @param token      Returned session token
         *
         * @return 0 if OK
         * @return 1 if session creation was denied due to single login limitation
         */
        int getSessionForCcSessionData(in string sessionId, in string sessionKey, out Session session, out string token);
 
        /**
         * Retrieve current session information.
         *
         * This call must be authenticated using a session token.
         *
         * @return %Session information
         */
        Session getCurrentSession();
 
        /**
         * Retrieve all open sessions.
         *
         * @return List of sessions
         */
        vector<Session> 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();
 
        /** Event: Session was created */
        valueobject SessionCreatedEvent extends idl.Event {
            int sessionId;          ///< ID of the session
            string username;        ///< Name of user owning the session
            string remoteIp;        ///< Session IP address
        };
 
        /** Event: Session was closed */
        valueobject SessionClosedEvent extends idl.Event {
            int sessionId;          ///< ID of the session
            string username;        ///< Name of user owning the session
            string remoteIp;        ///< Session IP address
            CloseReason reason;     ///< close reason
        };
    };
}