Interface ISessionFactory
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.
Namespace: PushTechnology.ClientInterface.Client.Session
Assembly: Diffusion.Client.dll
Syntax
public interface ISessionFactory
Remarks
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 |
---|---|
|
WebSocket. See RFC 6455. |
|
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.
Methods
ConnectionTimeout(Int32)
Sets the connection timeout.
Declaration
ISessionFactory ConnectionTimeout(int timeout)
Parameters
Type | Name | Description |
---|---|---|
Int32 | timeout | The default connection timeout in milliseconds. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the connection timeout changed. |
Remarks
The default connection timeout is 2 seconds.
Credentials(ICredentials)
Sets the credentials.
Declaration
ISessionFactory Credentials(ICredentials credentials)
Parameters
Type | Name | Description |
---|---|---|
ICredentials | credentials | The credentials. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the credentials changed. |
CustomCredentials(Byte[])
Sets credentials using an array of bytes.
Declaration
ISessionFactory CustomCredentials(byte[] bytes)
Parameters
Type | Name | Description |
---|---|---|
Byte[] | bytes | The credentials. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the credentials changed. |
HttpProxy(String, Int32)
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 tunneling through the specified proxy.
Declaration
ISessionFactory HttpProxy(string host, int port)
Parameters
Type | Name | Description |
---|---|---|
String | host | the host name of the HTTP proxy |
Int32 | port | the port of the HTTP proxy |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory which will use the provided HTTP proxy. |
HttpProxy(String, Int32, IHttpProxyAuthentication)
A variant of HttpProxy(String, Int32) that provides authentication details to the HTTP proxy.
This allows connection to a Diffusion Server using HTTP CONNECT tunneling through the specified proxy.
The authentication
parameter only affects communication with the
proxy, it is not passed on to the Diffusion server.
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
Declaration
ISessionFactory HttpProxy(string host, int port, IHttpProxyAuthentication authentication)
Parameters
Type | Name | Description |
---|---|---|
String | host | the host name of the HTTP proxy |
Int32 | port | the port of the HTTP proxy |
IHttpProxyAuthentication | authentication |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory which will use the provided HTTP proxy. |
InputBufferSize(Int32)
Sets the input buffer size.
Declaration
ISessionFactory InputBufferSize(int size)
Parameters
Type | Name | Description |
---|---|---|
Int32 | size | The input buffer size in bytes. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the input buffer size changed. |
Remarks
The default input buffer size is 1 MiB.
LocalSocketAddress(SocketAddress)
Set the optional local socket address, used prior to connection.
By default no local socket address is used.
Declaration
ISessionFactory LocalSocketAddress(SocketAddress address)
Parameters
Type | Name | Description |
---|---|---|
SocketAddress | address | The local socket address. Setting this to null effectively removes any previous setting. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the local socket address changed. |
MaximumMessageSize(Int32)
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 and so on.
Declaration
ISessionFactory MaximumMessageSize(int size)
Parameters
Type | Name | Description |
---|---|---|
Int32 | size | The maximum message size in bytes. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the maximum message size changed. |
Remarks
The default maximum message size is unconstrained - see MAXIMUM_MESSAGE_SIZE_MIN.
MaximumQueueSize(Int32)
Sets the maximum size of the outbound message queue for the connection.
Declaration
ISessionFactory MaximumQueueSize(int size)
Parameters
Type | Name | Description |
---|---|---|
Int32 | size | The maximum size that the outbound queue can reach before the connection is closed. |
Returns
Type | Description |
---|---|
ISessionFactory | The new immutable instance of the factory that will use the provided maximum queue size. |
Remarks
If not specified then this is assumed to be 1000.
Since 5.9
NoCredentials()
Sets credentials to none.
This is the default.
Declaration
ISessionFactory NoCredentials()
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the credentials changed. |
NoReconnection()
This will disable reconnection.
Declaration
ISessionFactory NoReconnection()
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory which will have the reconnection feature disabled. |
Remarks
This method is effectively the same as setting the reconnection timeout to 0.
Open(String)
Create an anonymous client session that will connect to a given URL.
Declaration
ISession Open(string url)
Parameters
Type | Name | Description |
---|---|---|
String | url | The server URL. |
Returns
Type | Description |
---|---|
ISession | A new session. |
Exceptions
Type | Condition |
---|---|
SessionSecurityException | If the server rejects the connection for an authentication related reason |
Open(String, ISessionOpenCallback)
Opens a new client session that will connect to a server through 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
.
Declaration
void Open(string url, ISessionOpenCallback callback)
Parameters
Type | Name | Description |
---|---|---|
String | url | The server URL. |
ISessionOpenCallback | callback | The callback which will be notified of the result of attempting to open the session. |
Open<TC>(String, TC, ISessionOpenContextCallback<TC>)
Opens a new client session that will connect to a server through 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.
Declaration
void Open<TC>(string url, TC context, ISessionOpenContextCallback<TC> callback)
Parameters
Type | Name | Description |
---|---|---|
String | url | The server URL. |
TC | context | The context to pass to the callback. May be null. |
ISessionOpenContextCallback<TC> | callback | The callback which will be notified of the result of attempting to open the session. |
Type Parameters
Name | Description |
---|---|
TC | The context type. |
OutputBufferSize(Int32)
Sets the output buffer size.
Declaration
ISessionFactory OutputBufferSize(int size)
Parameters
Type | Name | Description |
---|---|---|
Int32 | size | The output buffer size in bytes. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the output buffer size changed. |
Remarks
The default output buffer size is 1 MiB.
Password(String)
Sets the credentials of type 'password'.
Declaration
ISessionFactory Password(string password)
Parameters
Type | Name | Description |
---|---|---|
String | password | The password. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the password changed. |
Principal(String)
Sets the security principal.
By default this will be anonymous.
Declaration
ISessionFactory Principal(string principal)
Parameters
Type | Name | Description |
---|---|---|
String | principal | The principal. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the principal changed. |
Properties(IDictionary<String, String>)
Sets user-defined session property values.
Declaration
ISessionFactory Properties(IDictionary<string, string> properties)
Parameters
Type | Name | Description |
---|---|---|
IDictionary<String, String> | properties | The collection of user-defined session properties. |
Returns
Type | Description |
---|---|
ISessionFactory | The new immutable instance of the factory with the supplied properties set. |
Remarks
Supplied session properties will be provided to the server when a session is created using this session factory. The supplied properties will be validated during authentication and may be discarded or changed.
The specified properties will be added to any existing properties set for this session factory. If any of the keys have been previously declared then they will be overwritten with the new values.
For details of how session properties are used see ISession.
Property(String, String)
Sets a user-defined session property value.
Declaration
ISessionFactory Property(string name, string value)
Parameters
Type | Name | Description |
---|---|---|
String | name | The property name. |
String | value | The property value. |
Returns
Type | Description |
---|---|
ISessionFactory | The new immutable instance of the factory with the named property set. |
Remarks
Supplied session properties will be provided to the server when a session is created using this session factory. The supplied properties will be validated during authentication and may be discarded or changed.
The specified property will be added to any existing properties set for this session factory.
If the property was already set it will be overwritten.
For details of how session properties are used see ISession.
ReconnectionStrategy(IReconnectionStrategy)
Sets the IReconnectionStrategy to use by the current session in case of a connection loss.
Declaration
ISessionFactory ReconnectionStrategy(IReconnectionStrategy reconnectionStrategy)
Parameters
Type | Name | Description |
---|---|---|
IReconnectionStrategy | reconnectionStrategy | The reconnection strategy to use in case of a connection loss. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory which will use the provided IReconnectionStrategy. |
Remarks
The reconnection strategy will be applied on a sudden connection loss. The Session state will switch from CONNECTED_ACTIVE to RECOVERING_RECONNECT for the whole duration of the reconnection attempt. Only after a successful reconnection the session state will switch back to CONNECTED_ACTIVE. If the reconnection attempt fails, it will stay in RECOVERING_RECONNECT and simply try again. If the reconnection attempt get rejected by the server, the session state will change to CLOSED_BY_SERVER and the session will be closed. If the client is still in RECOVERING_RECONNECT, after the timeout has been reached, the session will be closed and further attempts to reconnect will be stopped.
ReconnectionTimeout(Int32)
Sets the reconnection timer which determines for how long reconnection will be attempted.
Declaration
ISessionFactory ReconnectionTimeout(int millisecondsTimeout)
Parameters
Type | Name | Description |
---|---|---|
Int32 | millisecondsTimeout | The timeout in milliseconds which will determine for how long the client attempts reconnection. This value is not allowed to be negative. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory which will have the reconnection
timeout set to |
Remarks
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().
RecoveryBufferSize(Int32)
Sets the recovery buffer size.
Declaration
ISessionFactory RecoveryBufferSize(int size)
Parameters
Type | Name | Description |
---|---|---|
Int32 | size | The recovery buffer size in messages. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the recovery buffer size changed. |
Remarks
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.
SessionErrorHandler(EventHandler<SessionErrorHandlerEventArgs>)
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.
Declaration
ISessionFactory SessionErrorHandler(EventHandler<SessionErrorHandlerEventArgs> eventHandler)
Parameters
Type | Name | Description |
---|---|---|
EventHandler<SessionErrorHandlerEventArgs> | eventHandler | An event handler which should be bound on all newly opened sessions. to remove previously specified handlers.
|
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the error handler changed. |
SessionStateChangedHandler(EventHandler<SessionListenerEventArgs>)
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.
Declaration
ISessionFactory SessionStateChangedHandler(EventHandler<SessionListenerEventArgs> eventHandler)
Parameters
Type | Name | Description |
---|---|---|
EventHandler<SessionListenerEventArgs> | eventHandler | An event handler which should be bound on all newly opened sessions. to remove previously specified handlers.
|
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the event handler changed. |
SslContext(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 behavior of is assumed, that is to accept any certificate presented by the server.
Declaration
ISessionFactory SslContext(RemoteCertificateValidationCallback remoteCertificateValidationCallback)
Parameters
Type | Name | Description |
---|---|---|
RemoteCertificateValidationCallback | remoteCertificateValidationCallback | A |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the SSL context changed. |
WriteTimeout(Int32)
Sets the write timeout value for blocking writes on the connection.
Declaration
ISessionFactory WriteTimeout(int timeout)
Parameters
Type | Name | Description |
---|---|---|
Int32 | timeout | The write timeout in milliseconds. |
Returns
Type | Description |
---|---|
ISessionFactory | A new immutable instance of the factory with the write timeout changed. |
Remarks
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.