Diffusion 6.2.2 User Manual

Connecting to the Diffusion server

One of the first actions your Diffusion™ client takes is to connect to the Diffusion server. Clients connect to the Diffusion server by
opening a session. A session represents a logical context between a client and the Diffusion server. All interactions with the Diffusion server
happen within a session.

Sessions

The act of opening the session establishes a connection with the the Diffusion server. When a session is
opened it is assigned a unique session identifier by the Diffusion server, which identifies the session even if it
becomes connected to another server.

The session does not receive input from the Diffusion server until it
is started, but can be used to obtain features and perform certain setup actions
before it is started.

Session state

The session between a client and the Diffusion server can be in one of a
number of states.

The following diagram shows the session state model: Figure 1. Session state model

CONNECTING

The client session is in this state while it attempts to connect to the Diffusion server. If the connection attempt is
successful, the session changes to CONNECTED_ACTIVE
state. If the connection is not successful, the session changes to one
of the closed states.

CONNECTED_ACTIVE

The client session is in this state while it is connected to the Diffusion server. The session spends the majority of
its lifetime in this state. If the session becomes disconnected and
reconnect is enabled, the session changes to
RECOVERING_CONNECT state. If the session closes, it
changes to one of the closed states.

RECOVERING_CONNECT

The client session is in this state while it attempts to reconnect to
the Diffusion server after a disconnection. If the
reconnection attempt is successful, the session changes back to
CONNECTED_ACTIVE state. If the reconnection attempt
is not successful, the session changes to one of the closed states.

CLOSED_BY_CLIENT

The client session is in this state when it is closed by the client. If
a session is in closed state, it cannot be reopened. A new session must
be established.

CLOSED_BY_SERVER

The client session is in this state when it is closed by the Diffusion server. If a session is in closed state, it
cannot be reopened. A new session must be established.

CLOSED_FAILED

The client session is in this state when it is closed for any reason
other than a close by the client or by the Diffusion server. If a session is in closed state, it cannot be reopened. A new
session must be established.

Session properties

When you connect to the Diffusion server by opening a session, the
session is assigned a set of properties. These properties are assigned by either the Diffusion server or an authentication handler and can be used by
clients to filter the set of connected client sessions to take actions on.

A client can propose session properties. The proposed session properties are passed
to the authentication handler which can accept the properties, modify the properties, or ignore them entirely.

Session roles

When a session authenticates with the Diffusion server, the session is
assigned a set of roles. These roles are assigned by either the Diffusion server or an authentication handler and define the set of
permissions a client session has.

Connecting basics
To make a connection to the Diffusion server the client must specify the host name and port number of the Diffusion server, the transport to use to connect, and whether that connection is secure.

Reconnect to the Diffusion server
When clients connect to the Diffusion server over unreliable networks these connections can be lost. Clients can attempt to reconnect to the Diffusion server after they lose connection.

Pinging the Diffusion server
Ping the Diffusion server from your client. If the ping is successful it reports the round-trip time between your client and the Diffusion server.