Legrand / Raritan Xerus™ JSON-RPC API for Remote Access Devices like KX4-101, KX3G2

Loading...
Searching...
No Matches
SessionManager.idl
1/* SPDX-License-Identifier: BSD-3-Clause */
2/*
3 * Copyright 2009 Raritan Inc. All rights reserved.
4 */
5
6/**
7 * %Session Management
8 */
9
10#include <Event.idl>
11
12module session {
13
14 /** %Session information */
15 structure Session {
16 int sessionId; ///< ID of the session
17 string username; ///< Name of user owning the session
18 string remoteIp; ///< Session IP address
19 string clientType; ///< Client type
20 time creationTime; ///< Session creation timestamp (seconds since system boot)
21 int timeout; ///< Session timeout in seconds
22 int idle; ///< Session idle time in seconds
23 int userIdle; ///< User idle time in seconds
24 };
25
26 /** %Session history entry */
27 structure HistoryEntry {
28 time creationTime; ///< Session creation timestamp (UNIX timestamp, UTC)
29 string remoteIp; ///< Session IP address
30 string clientType; ///< Session client type
31 };
32
33 /**
34 * %Session manager interface
35 *
36 * Session manager allows clients to announce a user session,
37 * i.e. consecutive activity that is related to each other,
38 * and make use of session services.
39 * Depending on transport protocoll an established session
40 * allows simplified authentication using the session token.
41 * For instance, for HTTP transport implementation sessiontoken
42 * can be written into HTTP Header while other authentication
43 * schemes may be omitted (for details, see transport mapping
44 * documentation).
45 * Each session has a defined timeout and an idle timer.
46 * A session is deleted once idle time is equal or greater
47 * than session timeout. Idle timer is implicitely touched
48 * by transport implementation whenever a call arrives that
49 * can be mapped to a particular session. In addition a client
50 * may decide to call touchCurrentSession with userActivity flag
51 * set to true. In this case userIdle attribute of session is reset
52 * to 0. This has purely informational character and will not cause
53 * any further action of session manager. It may be used to determine
54 * user activity under the assumptions that clients may do frequent
55 * background calls without actual user activity.
56 */
57 interface SessionManager {
58
59 constant int ERR_ACTIVE_SESSION_EXCLUSIVE_FOR_USER = 1; ///< Session creation denied due to single login limitation
60 constant int ERR_NO_SUCH_SESSION = 2; ///< Session for provided data could not be found
61
62 /** %Session close reasons */
63 enumeration CloseReason {
64 CLOSE_REASON_LOGOUT, ///< Regular logout
65 CLOSE_REASON_TIMEOUT, ///< Session timed out
66 CLOSE_REASON_BROWSER_CLOSED, ///< Browser window was closed
67 CLOSE_REASON_FORCED_DISCONNECT ///< Session was forcibly closed
68 };
69
70 /**
71 * Open a new session.
72 *
73 * This function will create a new session for the authenticated user.
74 * Upon success it will return a session token which can be used to
75 * authenticate future requests.
76 *
77 * @param session %Session information
78 * @param token Returned token for the newly created session
79 *
80 * @return 0 if OK
81 * @return 1 if session creation was denied due to single login limitation
82 */
83 int newSession(out Session session, out string token);
84
85 /**
86 * Retrieve an existing session using CC-SG provided session data
87 *
88 * @param sessionId Session ID
89 * @param sessionKey Session key
90 * @param session %Session information
91 * @param token Returned session token
92 *
93 * @return 0 if OK
94 * @return 1 if session creation was denied due to single login limitation
95 */
96 int getSessionForCcSessionData(in string sessionId, in string sessionKey, out Session session, out string token);
97
98 /**
99 * Retrieve current session information.
100 *
101 * This call must be authenticated using a session token.
102 *
103 * @return %Session information
104 */
105 Session getCurrentSession();
106
107 /**
108 * Retrieve all open sessions.
109 *
110 * @return List of sessions
111 */
112 vector<Session> getSessions();
113
114 /**
115 * Close a session identified by its token.
116 *
117 * @param sessionId ID of the session that should be closed
118 * @param reason close reason
119 */
120 void closeSession(in int sessionId, in CloseReason reason);
121
122 /**
123 * Close the current session.
124 *
125 * This call must be authenticated using a session token.
126 *
127 * @param reason close reason
128 */
129 void closeCurrentSession(in CloseReason reason);
130
131 /**
132 * Reset the current session's idle timer.
133 *
134 * @param userActivity Indicates that the session is touched
135 * due to user activity.
136 *
137 * If userActivity is not set, this is internally a NOP since
138 * any RPC call will implicitly touch the session.
139 * This call must be authenticated using a session token.
140 */
141 void touchCurrentSession(in boolean userActivity);
142
143 /**
144 * Get previous session data for the current user
145 *
146 * @return History data, sorted from newer to older sessions
147 */
148 vector<HistoryEntry> getSessionHistory();
149
150 /** Event: Session was created */
151 valueobject SessionCreatedEvent extends idl.Event {
152 int sessionId; ///< ID of the session
153 string username; ///< Name of user owning the session
154 string remoteIp; ///< Session IP address
155 };
156
157 /** Event: Session was closed */
158 valueobject SessionClosedEvent extends idl.Event {
159 int sessionId; ///< ID of the session
160 string username; ///< Name of user owning the session
161 string remoteIp; ///< Session IP address
162 CloseReason reason; ///< close reason
163 };
164 };
165}
session::SessionManager
Session manager interface
Definition SessionManager.idl:57
session::SessionManager::closeSession
void closeSession(in int sessionId, in CloseReason reason)
Close a session identified by its token.
session::SessionManager::getSessionHistory
vector< HistoryEntry > getSessionHistory()
Get previous session data for the current user.
session::SessionManager::ERR_NO_SUCH_SESSION
constant int ERR_NO_SUCH_SESSION
Session for provided data could not be found.
Definition SessionManager.idl:60
session::SessionManager::closeCurrentSession
void closeCurrentSession(in CloseReason reason)
Close the current session.
session::SessionManager::getSessions
vector< Session > getSessions()
Retrieve all open sessions.
session::SessionManager::getSessionForCcSessionData
int getSessionForCcSessionData(in string sessionId, in string sessionKey, out Session session, out string token)
Retrieve an existing session using CC-SG provided session data.
session::SessionManager::ERR_ACTIVE_SESSION_EXCLUSIVE_FOR_USER
constant int ERR_ACTIVE_SESSION_EXCLUSIVE_FOR_USER
Session creation denied due to single login limitation.
Definition SessionManager.idl:59
session::SessionManager::getCurrentSession
Session getCurrentSession()
Retrieve current session information.
session::SessionManager::newSession
int newSession(out Session session, out string token)
Open a new session.
session::SessionManager::touchCurrentSession
void touchCurrentSession(in boolean userActivity)
Reset the current session's idle timer.
session::SessionManager::CloseReason
CloseReason
Session close reasons
Definition SessionManager.idl:63
session::SessionManager::CLOSE_REASON_FORCED_DISCONNECT
@ CLOSE_REASON_FORCED_DISCONNECT
Session was forcibly closed.
Definition SessionManager.idl:67
session::SessionManager::CLOSE_REASON_BROWSER_CLOSED
@ CLOSE_REASON_BROWSER_CLOSED
Browser window was closed.
Definition SessionManager.idl:66
session::SessionManager::CLOSE_REASON_TIMEOUT
@ CLOSE_REASON_TIMEOUT
Session timed out.
Definition SessionManager.idl:65
session::SessionManager::CLOSE_REASON_LOGOUT
@ CLOSE_REASON_LOGOUT
Regular logout.
Definition SessionManager.idl:64
idl
Basic IDL definitions.
Definition Event.idl:10
session
Session Management
Definition SessionManager.idl:12
idl::Event
Common base for all events.
Definition Event.idl:13
session::HistoryEntry
Session history entry
Definition SessionManager.idl:27
session::HistoryEntry::creationTime
time creationTime
Session creation timestamp (UNIX timestamp, UTC)
Definition SessionManager.idl:28
session::HistoryEntry::remoteIp
string remoteIp
Session IP address.
Definition SessionManager.idl:29
session::HistoryEntry::clientType
string clientType
Session client type.
Definition SessionManager.idl:30
session::SessionManager::SessionClosedEvent
Event: Session was closed.
Definition SessionManager.idl:158
session::SessionManager::SessionClosedEvent::sessionId
int sessionId
ID of the session.
Definition SessionManager.idl:159
session::SessionManager::SessionClosedEvent::username
string username
Name of user owning the session.
Definition SessionManager.idl:160
session::SessionManager::SessionClosedEvent::reason
CloseReason reason
close reason
Definition SessionManager.idl:162
session::SessionManager::SessionClosedEvent::remoteIp
string remoteIp
Session IP address.
Definition SessionManager.idl:161
session::SessionManager::SessionCreatedEvent
Event: Session was created.
Definition SessionManager.idl:151
session::SessionManager::SessionCreatedEvent::remoteIp
string remoteIp
Session IP address.
Definition SessionManager.idl:154
session::SessionManager::SessionCreatedEvent::username
string username
Name of user owning the session.
Definition SessionManager.idl:153
session::SessionManager::SessionCreatedEvent::sessionId
int sessionId
ID of the session.
Definition SessionManager.idl:152
session::Session
Session information
Definition SessionManager.idl:15
session::Session::username
string username
Name of user owning the session.
Definition SessionManager.idl:17
session::Session::userIdle
int userIdle
User idle time in seconds.
Definition SessionManager.idl:23
session::Session::clientType
string clientType
Client type.
Definition SessionManager.idl:19
session::Session::timeout
int timeout
Session timeout in seconds.
Definition SessionManager.idl:21
session::Session::creationTime
time creationTime
Session creation timestamp (seconds since system boot)
Definition SessionManager.idl:20
session::Session::remoteIp
string remoteIp
Session IP address.
Definition SessionManager.idl:18
session::Session::sessionId
int sessionId
ID of the session.
Definition SessionManager.idl:16
session::Session::idle
int idle
Session idle time in seconds.
Definition SessionManager.idl:22