subscribeSessions and unsubscribeSessions

subscribeSessions

The subscribeSessions function allows subscribing for changes of sessions in the systems of interest. Then it calls the provided <callback> with the operation result.

If the <system> is not provided or is null, all the active sessions of all the systems are returned.

The sessions subscription remains active until the unsubscribeSessions function is called.

Syntax

var result = subscribeSessions(<callback>, <system>, <initialSessions>);

Parameters Usage

Result

If the subscribe operation is successful, the subscribeSessions function returns a SubscribeSessionsResult object containing the result of the subscription. This result must be used to perform the corresponding unsubscription.

If any errors occurred during the subscribe operation, the error property of the SubscribeSessionsResult indicates the reason why the operation failed.

It is necessary to keep this result in a global variable to use as input parameter for the unsubscribeSessions.

The callback is a function declared as follows, and is called when a session change occurs:

function onSessionsChanged(<sessions>)

{

    //... Do callback stuff here ...

}

Where < sessions > is a SessionObjects collection.

Error Handling

Errors can occur in case:

• The <callback> is missing, invalid, null, or empty.
• The specified <system> is not a positive integer, a string, or a SystemObject.
• The specified <initialSessions> is not a Boolean value.

Examples of Use

How to subscribe to session changes for all systems and retrieve the sessions count per system and per station

Note that, since the unsubscribeSessions function is not called, this script remains running until it is manually stopped.

var onSessionsChange = function (sessions) {

    console("----- {0} -----\n", new Date().toLocaleString());

    handleSessions(sessions);

}

var subscribeSessionsResult = subscribeSessions(onSessionsChange);

if (subscribeSessionsResult.error != null)

{

    console(subscribeSessionsResult.error);

}

function handleSessions(sessions)

{

    if (sessions === null)

    {

        console("No active sessions");

        return;

    }

    console("- All sessions:\n{0}\n", sessions);

    // A map for the systemName =>sessionsCount mappings

    var sessionsPerSystem = {};

    // Loop through the sessions

    for (var i = 0; i < sessions.length; i ++) {

        var session = sessions[i];

        var systemName = session.system.systemName;

        var currentCount = 0;

        if (sessionsPerSystem[systemName])

        {

            currentCount = sessionsPerSystem[systemName];

        }

        currentCount += sessions[i].count;

        sessionsPerSystem[systemName] = currentCount;

    }

    console("- Sessions count per System:");

    for (systemName in sessionsPerSystem) {

        console(systemName + ": " + sessionsPerSystem[systemName]);

    }

    console("\n");

}

unsubscribeSessions

The unsubscribeSessions method allows terminating any session subscription created by calling the subscribeSessions function. On this purpose, the result of the subscribeSessions invocation must be provided as parameter.

Syntax

var result = unsubscribeSessions(<subscribeSessionsResult>);

Parameters Usage

Result

If any errors occurred during the unsubscribe operation, the error property of the UnsubscribeSessionsResult object indicates the reason why the operation failed.

Error Handling

Errors can occur in case:

• The SubscribeSessionsResult object is missing, invalid, null, or empty.

Examples of Use

How to subscribe to sessions changes in System1 and unsubscribe after five notifications

var count = 0;

var onSessionsChange = function (sessions) {

    console(sessions);

    count++;

    //Unsubscribe after 5 session changes    

    if (count >= 5)

    {

        unsubscribeSessions(subscribeSessionsResult);

    }

}

var subscribeSessionsResult = subscribeSessions(onSessionsChange, null);

if (subscribeSessionsResult.error != null)

{

    console(subscribeSessionsResult.error);

}

How to monitor the session changes count for two hours

console("{0} - Start monitoring session changes in System2", new Date())

var sessionsChanges = 0;

var subscribeSessionsResult = subscribeSessions(callback, “System2”);

if (subscribeSessionsResult.error != null)

{

    console(subscribeSessionsResult.error);

    terminate();

}

setTimeout(timeoutElapsed, 120 * 60 * 1000);

// Callbacks

function callback(sessions)

{

    sessionsChanges++;

    if (sessions != null)

        console("{0} - {1} active session(s)", new Date(), sessions.length);

    else

        console("{0} - no active sessions");

}

function timeoutElapsed()

{

    unsubscribeSessions(subscribeSessionsResult);

    console("{0} - Stop monitoring session changes", new Date())

    console("Sessions changes notified {0} times.", sessionsChanges);

}

getSessionsByType Function

The getSessionsByType function allows retrieving all the active sessions of the specified type, for the systems of interest.

Syntax

var result = getSessionsByType(sessionTypeId, <system>);

Parameters Usage

Result

The getSessions function returns:

• the number of active sessions of the specified <sessionTypeId>.
• 0, if there are no active sessions of the specified <sessionTypeId> for the requested system, or the specified system is offline or invalid.

Error Handling

Errors can occur in case:

• The specified <system> is not a positive integer, a string, or a SystemObject.

Examples of Use

How to get the number of active Primary Desktop sessions of the current system

var system = getCurrentSystem();

var primaryDesktopSessions = getSessionsByType(0, system);

console("System: {0}\n\t- Primary Desktop Sessions: {1}", system.systemName, primaryDesktopSessions);

How to get the number of active Primary Desktop sessions in all systems

var primaryDesktopSessions = getSessionsByType(0);

console("All systems:\n\t- Primary Desktop Sessions: {0}", primaryDesktopSessions);