Working with session properties
A client session with the appropriate permissions can view, request, or update the session properties of another client session.
Session properties
Each client session has a number of properties associated with it. Properties are keys and values. Both the key and the value are case sensitive. These session properties can be used by other clients to select sets of client session to perform actions on.
For more information, see Session properties.
Receiving notifications of client session events and their session properties
Required permissions: ,
To receive notifications when any client session opens, closes, or is updated, register a listener to listen for these events:
// Register a listener for session properties
session.clients.setSessionPropertiesListener(diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES)
.then(function() {
var listener = session.clients.getSessionPropertiesListener();
listener
.on('onSessionOpen', function(event) {
// The action to take on a client session open notification
})
.on('onSessionUpdate', function(event) {
// The action to take on a client session update notification
})
.on('onSessionClose', function(event) {
// The action to take on a client session close notification
});
}, function(err) {
console.log('An error has occurred:', err);
});
ClientControl clientControl = session.feature(ClientControl.class);
clientControl.setSessionPropertiesListener(
new ClientControl.SessionPropertiesListener.Default() {
@Override
public void onSessionOpen(){
// The action to take on a client session open notification
}
@Override
public void onSessionEvent(){
// The action to take on a client session update notification
}
@Override
public void onSessionClose(){
// The action to take on a client session close notification
}
},
// The session properties to receive
"$Country", "$Department");
var _clientControl = session.ClientControlGet; // Set up a listener to receive notification of all sessions _clientControl.SetSessionPropertiesListener( propertyListener, "$Country", "Department" );
/*
* Register a session properties listener.
*
* Requests all "fixed" properties, i.e. those defined by
* Diffusion rather than user-defined properties.
*/
SET_T *required_properties = set_new_string(5);
set_add(required_properties, PROPERTIES_SELECTOR_ALL_FIXED_PROPERTIES);
// Set the parameters to callbacks previously defined
SESSION_PROPERTIES_REGISTRATION_PARAMS_T params = {
.on_registered = on_registered,
.on_registration_error = on_registration_error,
.on_session_open = on_session_open,
.on_session_close = on_session_close,
.on_session_update = on_session_update,
.on_session_error = on_session_error,
.required_properties = required_properties
};
session_properties_listener_register(session, params);
When registering this listener, specify which session properties to receive for each client session:
// Receive all fixed properties
session.clients.setSessionPropertiesListener(diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES, listener)
.then(function() {
});
// OR
// Receive all user-defined properties
session.clients.setSessionPropertiesListener(diffusion.clients.PropertyKeys.ALL_USER_PROPERTIES, listener)
.then(function() {
});
// OR
// Receive all properties
session.clients.setSessionPropertiesListener([diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES, diffusion.clients.PropertyKeys.ALL_USER_PROPERTIES], listener)
.then(function() {
});
// Define individual session properties to receive
clientControl.setSessionPropertiesListener(
new ClientControl.SessionPropertiesListener.Default() {
// Define callbacks
},
"$Country", "$Department");
// OR
// Receive all fixed properties
clientControl.setSessionPropertiesListener(
new ClientControl.SessionPropertiesListener.Default() {
// Define callbacks
},
Session.ALL_FIXED_PROPERTIES);
// OR
// Receive all user-defined properties
clientControl.setSessionPropertiesListener(
new ClientControl.SessionPropertiesListener.Default() {
// Define callbacks
},
Session.ALL_USER_PROPERTIES);
// Define individual session properties to receive _clientControl.SetSessionPropertiesListener(propertiesListener, "$Country", "Department" ); // OR // Receive all fixed properties _clientControl.SetSessionPropertiesListener(propertiesListener, SessionControlConstants.AllFixedProperties ); // OR // Receive all user-defined properties _clientControl.SetSessionPropertiesListener(propertiesListener, SessionControlConstants.AllUserProperties );
// Receive all fixed properties
SET_T *required_properties = set_new_string(5);
set_add(required_properties, PROPERTIES_SELECTOR_ALL_FIXED_PROPERTIES);
SESSION_PROPERTIES_REGISTRATION_PARAMS_T params = {
//Other parameters
.required_properties = required_properties
};
// OR
// Receive all user-defined properties
SET_T *required_properties = set_new_string(5);
set_add(required_properties, PROPERTIES_SELECTOR_ALL_USER_PROPERTIES);
SESSION_PROPERTIES_REGISTRATION_PARAMS_T params = {
//Other parameters
.required_properties = required_properties
};
// OR
// Receive all properties
SET_T *required_properties = set_new_string(5);
set_add(required_properties, PROPERTIES_SELECTOR_ALL_FIXED_PROPERTIES);
set_add(required_properties, PROPERTIES_SELECTOR_ALL_USER_PROPERTIES);
SESSION_PROPERTIES_REGISTRATION_PARAMS_T params = {
//Other parameters
.required_properties = required_properties
};
When the listening client first registers a listener, it receives a notification for every client session that is currently open. When subsequent client sessions open, the listening client receives a notification for those clients.
When the listening client is notified of a session event, it receives the requested session properties as a map of keys and values.
When the listening client is notified of a session closing, it also receives the reason that the session was closed. If the client session becomes disconnected from Diffusion™ Cloud, the listener might not receive notification of session close immediately. If reconnection is configured for the client, when the client disconnects, its session goes into reconnecting state for the configured time (the default is 60 seconds) before going into a closed state.
Getting properties of specific client sessions
Required permissions:
A client can make an asynchronous request the session properties of any client session from Diffusion Cloud, providing the requesting client knows the session ID of the target client.
// Get fixed session properties
session.clients.getSessionProperties(sessionID, diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES)
.then(function{
});
// Get fixed session properties ClientControl clientControl = session.feature(ClientControl.class); clientControl.getSessionProperties(sessionID, Session.ALL_FIXED_PROPERTIES, sessionPropertiesCallback);
var _clientControl = session.ClientControl; _clientControl.GetSessionProperties( sessionID, SessionControlConstants.AllFixedProperties, sessionPropertiesCallback );
GET_SESSION_PROPERTIES_PARAMS_T params = {
.session_id = session_id,
.required_properties = properties,
.on_session_properties = on_session_properties
};
get_session_properties(session, params);
Update the properties of specific client sessions
Required permissions: ,
A client session with the appropriate permissions can update the value of existing user-defined session properties or add new user-defined properties for any client session or set of client sessions.
As part of the update session properties request, provide a map of the keys for the session properties you want to update or add and the new values. If you provide a null value for a session property, that property is deleted from the session. A successful update session properties request returns a map of the updated properties and their old values.
Specify a single session to change the user-defined session properties for the session by providing the session ID.
// Change the session properties of a single session ClientControl clientControl = session.feature(ClientControl.class); final CompletableFuture<Map<String, String>> result = clientControl.setSessionProperties(sessionID, map_of_properties);
Specify a set of client sessions to change the user-defined session properties for by providing a filter query expression. For more information about filter query expressions, see Session filtering.
// Change the session properties of set of sessions defined by a filter expression ClientControl clientControl = session.feature(ClientControl.class); final CompletableFuture<Map<String, String>> result = clientControl.setSessionProperties(filter, map_of_properties);
This page last modified: 2019/11/22