Creates client sessions. More...

Inherited by PushTechnology.ClientInterface.Client.Session.SessionFactory.

Public Member Functions
ISessionFactory	SessionStateChangedHandler (EventHandler< SessionListenerEventArgs > eventHandler)
	Nominates an event handler that will be bound to the StateChanged event on all sessions created by the returned factory (and factories created from that one). More...

ISessionFactory	SessionErrorHandler (EventHandler< SessionErrorHandlerEventArgs > eventHandler)
	Nominates an event handler that will be bound to the ErrorNotified event on all sessions created by the returned factory (and factories created from that one). More...

ISessionFactory	Principal (string principal)
	Sets the security principal. More...

ISessionFactory	Credentials (ICredentials credentials)
	Sets the credentials. More...

ISessionFactory	NoCredentials ()
	Sets credentials to none. More...

ISessionFactory	Password (string password)
	Sets the credentials of type 'password'. More...

ISessionFactory	CustomCredentials (byte[] bytes)
	Sets credentials using an array of bytes. More...

ISessionFactory	ConnectionTimeout (int timeout)
	Sets the connection timeout. More...

ISessionFactory	InputBufferSize (int size)
	Sets the input buffer size. More...

ISessionFactory	OutputBufferSize (int size)
	Sets the output buffer size. More...

ISessionFactory	RecoveryBufferSize (int size)
	Sets the recovery buffer size. More...

ISessionFactory	MaximumQueueSize (int size)
	Sets the maximum size of the outbound message queue for the connection. More...

ISessionFactory	LocalSocketAddress (SocketAddress address)
	Set the optional local socket address, used prior to connection. More...

ISessionFactory	SslContext (RemoteCertificateValidationCallback remoteCertificateValidationCallback)
	Nominates a delegate which will be called to decide whether or not to accept the server certificate when connecting to a server. More...

ISessionFactory	SslContext (RemoteCertificateValidationCallback remoteCertificateValidationCallback, LocalCertificateSelectionCallback localCertificateSelectionCallback)
	Nominates both a delegate which will be called to decide whether or not to accept the server certificate when connecting to a server, and a delegate which will be called to choose which client certificate to present to the server. More...

ISessionFactory	WriteTimeout (int timeout)
	Sets the write timeout value for blocking writes on the connection. More...

ISessionFactory	MaximumMessageSize (int size)
	Set the maximum message size. More...

ISessionFactory	HttpProxy (string host, int port)
	Set the address of the HTTP Proxy that should be used to make connections to the server. More...

ISessionFactory	HttpProxy (string host, int port, IHttpProxyAuthentication authentication)
	A variant of HttpProxy(string, int) that provides authentication details to the HTTP proxy. More...

ISessionFactory	NoReconnection ()
	This will disable reconnection. More...

ISessionFactory	ReconnectionTimeout (int millisecondsTimeout)
	Sets the reconnection timer which determines for how long reconnection will be attempted. More...

ISessionFactory	ReconnectionStrategy (IReconnectionStrategy reconnectionStrategy)
	Sets the IReconnectionStrategy to use by the current session in case of a connection loss. More...

ISession	Open (string url)
	Create an anonymous client session that will connect to a given url. More...

void	Open (string url, ISessionOpenCallback callback)
	Opens a new client session that will connect to a server via a given url. More...

void	Open< TC > (string url, TC context, ISessionOpenContextCallback< TC > callback)
	Opens a new client session that will connect to a server via a given url and using a contextual callback. More...

Detailed Description

Creates client sessions.

Creating a session is a blocking operation. It only returns normally if a connection was accepted by a server. In this case, the session will transition from 'Connecting' to 'Connected_Initialising', and the session id will be assigned.

URL format

URLs takes the formscheme://host:port, where scheme is chosen from the following table and determines the transport protocol used to send Diffusion messages.

Scheme	Transport Protocol
ws	WebSocket. See RFC 6455.
wss	WebSocket over TLS.

TLS is Transport Layer Security. TLS-based protocols use cryptography to provide transport-level privacy, authentication, and integrity, and protects against network-sniffing and man-in-the-middle attacks. We recommend using the TLS variants for all communication. For a typical application, only consider not using TLS for unauthenticated("anonymous") client sessions.

Member Function Documentation

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.ConnectionTimeout ( int timeout )

Sets the connection timeout.

The default connection timeout is 2 seconds.

Parameters

timeout The default connection timeout in milliseconds.

Returns: A new immutable instance of the factory with the connection timeout changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.Credentials ( ICredentials credentials )

Sets the credentials.

Parameters

credentials The credentials.

Returns: A new immutable instance of the factory with the credentials changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.CustomCredentials ( byte[] bytes )

Sets credentials using an array of bytes.

Parameters

bytes The credentials.

Returns: A new immutable instance of the factory with the credentials changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.HttpProxy	(	string	host,
		int	port
	)

Set the address of the HTTP Proxy that should be used to make connections to the server.

This allows connection to a Diffusion Server using HTTP CONNECT tunnelling through the specified proxy.

Parameters

host	the host name of the HTTP proxy
port	the port of the HTTP proxy

Returns: A new immutable instance of the factory which will use the provided HTTP proxy.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.HttpProxy	(	string	host,
		int	port,
		IHttpProxyAuthentication	authentication
	)

A variant of HttpProxy(string, int) that provides authentication details to the HTTP proxy.

This allows connection to a Diffusion Server using HTTP CONNECT tunnelling through the specified proxy.

The authentication parameter only affects communication with the proxy, it is not passed on to the Diffusion server. Diffusion.ProxyAuthentication and IProxyAuthenticationFactory can be used to create a suitable instance. For example, to specify HTTP BASIC authentication with a user name joe and password s3cret:

HTTPProxyAuthentication authentication = Diffusion.ProxyAuthentication.Basic("joe", "s3cret");

The Principal(String) and Credentials(ICredentials) methods control authentication with the Diffusion server and do not affect proxy authentication.

Parameters

host	the host name of the HTTP proxy
port	the port of the HTTP proxy
authentication

Returns: A new immutable instance of the factory which will use the provided HTTP proxy.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.InputBufferSize ( int size )

Sets the input buffer size.

The default input buffer size is 1 MiB.

Parameters

size	The input buffer size in bytes.

Returns: A new immutable instance of the factory with the input buffer size changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.LocalSocketAddress ( SocketAddress address )

Set the optional local socket address, used prior to connection.

By default no local socket address is used.

Parameters

address The local socket address. Setting this to null effectively removes any previous setting.

Returns: A new immutable instance of the factory with the local socket address changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.MaximumMessageSize ( int size )

Set the maximum message size.

This constrains the size of messages that will be accepted from the server and thus the size of any content that can be received. The limit is to protect against unexpectedly large messages.

For maximum efficiency this should be set to a value which will cater for the largest content expected plus an amount for message protocol headers etc.

The default maximum message size is unconstrained - see SessionAttributes.MAXIMUM_MESSAGE_SIZE_MIN.

Parameters

size	The maximum message size in bytes.

Returns: A new immutable instance of the factory with the maximum message size changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.MaximumQueueSize ( int size )

Sets the maximum size of the outbound message queue for the connection.

If not specified then this is assumed to be 1000.

Since 5.9

Parameters

size	The maximum size that the outbound queue can reach before the connection is closed.

Returns: The new immutable instance of the factory that will use the provided maximum queue size.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.NoCredentials ( )

Sets credentials to none.

This is the default.

Returns: A new immutable instance of the factory with the credentials changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.NoReconnection ( )

This will disable reconnection.

This method is effectively the same as setting the reconnection timeout to 0.

Returns: A new immutable instance of the factory which will have the reconnection feature disabled.

ISession PushTechnology.ClientInterface.Client.Session.ISessionFactory.Open ( string url )

Create an anonymous client session that will connect to a given url.

Parameters

url	The server url.

Returns: A new session.

Exceptions

SessionSecurityException If the server rejects the connection for an authentication related reason

void PushTechnology.ClientInterface.Client.Session.ISessionFactory.Open	(	string	url,
		ISessionOpenCallback	callback
	)

Opens a new client session that will connect to a server via a given url.

This is a non-blocking method which will return immediately and the result of the attempt to open the session will be notified to the specified callback .

Parameters

url	The server url.
callback	The callback which will be notified of the result of attempting to open the session.

void PushTechnology.ClientInterface.Client.Session.ISessionFactory.Open< TC >	(	string	url,
		TC	context,
		ISessionOpenContextCallback< TC >	callback
	)

Opens a new client session that will connect to a server via a given url and using a contextual callback.

This is the same as Open(string, ISessionOpenCallback) but with the addition of an arbitrary context object.

Template Parameters

TC	The context type.

Parameters

url	The server url.
context	The context to pass to the callback. May be null.
callback	The callback which will be notified of the result of attempting to open the session.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.OutputBufferSize ( int size )

Sets the output buffer size.

The default output buffer size is 1 MiB.

Parameters

size	The output buffer size in bytes.

Returns: A new immutable instance of the factory with the output buffer size changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.Password ( string password )

Sets the credentials of type 'password'.

Parameters

password The password.

Returns: A new immutable instance of the factory with the password changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.Principal ( string principal )

Sets the security principal.

By default this will be anonymous.

Parameters

principal The principal.

Returns: A new immutable instance of the factory with the principal changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.ReconnectionStrategy ( IReconnectionStrategy reconnectionStrategy )

Sets the IReconnectionStrategy to use by the current session in case of a connection loss.

The reconnection strategy will be applied on a sudden connection loss. The Session state will switch from SessionState.CONNECTED_ACTIVE to SessionState.RECOVERING_RECONNECT for the whole duration of the reconnection attempt. Only after a successful reconnection the session state will switch back to SessionState.CONNECTED_ACTIVE. If the reconnection attempt fails, it will stay in SessionState.RECOVERING_RECONNECT and simply try again. If the reconnection attempt get rejected by the server, the session state will change to SessionState.CLOSED_BY_SERVER and the session will be closed. If the client is still in SessionState.RECOVERING_RECONNECT, after the timeout has been reached, the session will be closed and further attempts to reconnect will be stopped.

Parameters

reconnectionStrategy The reconnection strategy to use in case of a connection loss.

Returns: A new immutable instance of the factory which will use the provided IReconnectionStrategy.

Exceptions

ArgumentNullException The reconnectionStrategy is null.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.ReconnectionTimeout ( int millisecondsTimeout )

Sets the reconnection timer which determines for how long reconnection will be attempted.

The timeout has to be set in milliseconds and it should be set to at least 1 second to give the client an actual chance of reconnection. However, if the timeout is set to 0, no reconnection will be tried. This would be effectively the same as calling NoReconnection.

Parameters

millisecondsTimeout The timeout in milliseconds which will determine for how long the client attempts reconnection. This value is not allowed to be negative.

Returns: A new immutable instance of the factory which will have the reconnection timeout set to millisecondsTimeout .

Exceptions

ArgumentOutOfRangeException The millisecondsTimeout is a negative value.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.RecoveryBufferSize ( int size )

Sets the recovery buffer size.

If the server is configured to support reconnection, a session established with a non-zero reconnection time retains a buffer of sent messages. If the session disconnects and reconnects, this buffer is used to re-send messages that the server has not received.

The default is 128 messages. Higher values increase the chance of successful reconnection, but increase the per-session memory footprint.

Implemented in Version 6.0.

Parameters

size	The recovery buffer size in messages.

Returns: A new immutable instance of the factory with the recovery buffer size changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.SessionErrorHandler ( EventHandler< SessionErrorHandlerEventArgs > eventHandler )

Nominates an event handler that will be bound to the ErrorNotified event on all sessions created by the returned factory (and factories created from that one).

This avoids having to set the error handler on each session created, and also allows errors that occur during connection to be observed.

Because the error handler is bound to the session when it is created, the handler will see the session object as the sender argument, and not the factory.

The eventHandler will replace any previously provided, so if multiple event handlers are needed they should be combined (with the + operator) before passing them to this method.

Parameters

eventHandler An event handler which should be bound on all newly opened sessions. null to remove previously specified handlers.

Returns: A new immutable instance of the factory with the error handler changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.SessionStateChangedHandler ( EventHandler< SessionListenerEventArgs > eventHandler )

Nominates an event handler that will be bound to the StateChanged event on all sessions created by the returned factory (and factories created from that one).

This avoids having to set the event handler on each session created, and also allows the transitions from the Connecting state to be observed.

Because the event handler is bound to the session when it is created, the handler will see the session object as the sender argument, and not the factory.

The eventHandler will replace any previously provided, so if multiple event handlers are needed they should be combined (with the + operator) before passing them to this method.

Parameters

eventHandler An event handler which should be bound on all newly opened sessions. null to remove previously specified handlers.

Returns: A new immutable instance of the factory with the event handler changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.SslContext ( RemoteCertificateValidationCallback remoteCertificateValidationCallback )

Nominates a delegate which will be called to decide whether or not to accept the server certificate when connecting to a server.

If not explicitly supplied, then the default behaviour of is assumed, ie. to accept any certificate presented by the server.

Parameters

remoteCertificateValidationCallback A RemoteCertificateValidationCallback delegate responsible for validating the certificate supplied by the Diffusion server.

Returns: A new immutable instance of the factory with the SSL context changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.SslContext	(	RemoteCertificateValidationCallback	remoteCertificateValidationCallback,
		LocalCertificateSelectionCallback	localCertificateSelectionCallback
	)

Nominates both a delegate which will be called to decide whether or not to accept the server certificate when connecting to a server, and a delegate which will be called to choose which client certificate to present to the server.

If not explicitly supplied, then the default behaviour of is assumed, ie. to accept any certificate presented by the server, and to present no certificate to the server.

Parameters

remoteCertificateValidationCallback	A RemoteCertificateValidationCallback delegate responsible for validating the certificate supplied by the Diffusion server.
localCertificateSelectionCallback	A LocalCertificateSelectionCallback delegate responsible for choosing a certificate to present to the server.

Returns: A new immutable instance of the factory with the SSL context changed.

ISessionFactory PushTechnology.ClientInterface.Client.Session.ISessionFactory.WriteTimeout ( int timeout )

Sets the write timeout value for blocking writes on the connection.

Blocking writes are only used for the initial connection request. If it is not possible to complete the write within this time, the connection is closed.

The default write timeout is 2 seconds.

Parameters

timeout The write timeout in milliseconds.

Returns: A new immutable instance of the factory with the write timeout changed.

The documentation for this interface was generated from the following file:

LegacyModule/Client/Session/ISessionFactory.cs

Public Member Functions

Detailed Description

URL format

Member Function Documentation