Managing sessions

A client session with the appropriate permissions can receive notifications and information about other client sessions. A client session with the appropriate permissions can also manage other client sessions.

Closing client sessions

Required permissions:view_session, modify_session

A client can close any client session, providing the requesting client knows the session ID of the target client.

Requests are routed to the correct server within a Diffusion™ server cluster.

A client can close all sessions specified by a session filter.

If applied to a server cluster, this closes sessions matching the filter on all the servers.

JavaScript

const numClosed = await session.clients.close(sessions);

.NET

WriteLine($"Closing session with id '{clientSession.SessionId}'");

await session.ClientControl.CloseAsync(clientSession.SessionId);

Java and Android

final ClientControl clientControl = session.feature(ClientControl.class);

// close a session using the session id
clientControl.close(session.getSessionId());

// close multiple sessions using a session filter
clientControl.close("$Principal is 'client'");

static int on_session_closed(
    void *context)
{
    // session has been closed
    return HANDLER_SUCCESS;
}

void close_session(
    SESSION_T *session,
    SESSION_ID_T *session_id)
{
    DIFFUSION_CLIENT_CLOSE_WITH_SESSION_PARAMS_T params = {
        .session_id = session_id,
        .on_closed = on_session_closed,
    };

    diffusion_client_close_with_session(session, params, NULL);
}

static int on_sessions_closed(
    int number_of_matching_sessions,
    void *context)
{
    // sessions have been closed
    return HANDLER_SUCCESS;
}

void close_sessions_with_filter(
    SESSION_T *session,
    char *session_filter)
{
    DIFFUSION_CLIENT_CLOSE_WITH_FILTER_PARAMS_T params = {.filter = session_filter, .on_clients_closed = on_sessions_closed};

    diffusion_client_close_with_filter(session, params, NULL);
}

Changing security roles

Required permissions:view_session, modify_session

A client can change the security roles of another session identified by session ID, or a group of sessions that matches a session filter expression.

Requests identified by session ID are routed to the correct server within a Diffusion server cluster; requests using a session filter are applied to sessions matching the filter on all the servers in a cluster.

JavaScript

session.clients.changeRoles(sessions, ['ROLES_TO_ADD'], ['ROLES_TO_REMOVE']);

.NET

WriteLine("Removing the Administrator role for the session.");

await session.ClientControl.ChangeRolesAsync(adminSession.SessionId, new Collection<string>() { "ADMINISTRATOR" }, new Collection<string>());

Java and Android

final ClientControl clientControl = session.feature(ClientControl.class);

final Set<String> rolesToRemove =  Collections.singleton("CLIENT");
final Set<String> rolesToAdd = Collections.singleton("OPERATOR");

//change roles with a session id
clientControl.changeRoles(
    session.getSessionId(),
    rolesToRemove,
    rolesToAdd
);

// change roles with a session filter
clientControl.changeRoles(
    "$Principal is 'client'",
    rolesToRemove,
    rolesToAdd
);

static int on_roles_changed(
    void *context)
{
    // roles have been successfully changed
    return HANDLER_SUCCESS;
}

void change_roles(
    SESSION_T *session,
    SESSION_ID_T *session_id,
    SET_T *roles_to_add,
    SET_T *roles_to_remove)
{
    DIFFUSION_CHANGE_ROLES_WITH_SESSION_ID_PARAMS_T params =
        {.session_id = session_id, .roles_to_add = roles_to_add, .roles_to_remove = roles_to_remove, .on_roles_changed = on_roles_changed};
    diffusion_change_roles_with_session_id(session, params, NULL);
}

static int on_roles_changed_filter(
    int number_of_matching_sessions,
    void *context)
{
    // roles have been successfully changed
    return HANDLER_SUCCESS;
}

void change_roles_with_filter(
    SESSION_T *session,
    char *session_filter,
    SET_T *roles_to_add,
    SET_T *roles_to_remove)
{
    DIFFUSION_CHANGE_ROLES_WITH_FILTER_PARAMS_T params = {
        .filter = session_filter,
        .roles_to_add = roles_to_add,
        .roles_to_remove = roles_to_remove,
        .on_roles_changed = on_roles_changed_filter};
    diffusion_change_roles_with_filter(session, params, NULL);
}