ISession Interface

In blocking mode, the calling thread is blocked until either the session connection attempt succeeds or is determined to have failed. If the connection succeeds, SOLCLIENT_OK is returned. If the session could not connect, SOLCLIENT_NOT_READY is returned.

In non-blocking mode, SOLCLIENT_IN_PROGRESS is returned upon a successful session connect request, and the connection attempt proceeds in the background. In both non-blocking and blocking mode, a session event is generated for the session: UpNotice, if the session successfully connects; or ConnectFailedError, if the session fails to connect.

For blocking mode, the session event is issued before the call to Connect returns. For non-blocking mode, the timing is undefined (that is, it could occur before or after the call returns, but it is typically after). A session connection timer, controlled by the session property ConnectTimeoutInMsecs, controls the maximum amount of time a session connect attempt lasts for. If this amount time is exceeded, a ConnectFailedError event is issued for the session.

If there is an error when Connect is invoked, SOLCLIENT_FAIL is returned, and a session event is not subsequently issued. Therefore, the caller must check for a return code of SOLCLIENT_FAIL if it has logic that depends upon a subsequent session event to be issued. For a non-blocking session connect invocation, if the session connect attempt eventually fails, the last error information to indicate the reason for the failure cannot be determined by the calling thread, rather it must be discovered through the session event delegate (and GetLastSDKErrorInfo can be called in the session event delegate to get further information). For a blocking session connect invocation, if the session connect attempt does not return SOLCLIENT_OK, then the calling thread can determine the failure reason by immediately calling GetLastSDKErrorInfo.

Note: Client applications must keep IDispatchTarget object references accessible if they want to Unsubscribe from the given IMessageDispatcher, and remove already added Topic subscriptions. IDispatchTarget internal object ID constitutes a unique key. Forgetting to keep a reference to IDispatchTarget objects make subsequent Unsubscribe(IDispatchTarget, Int32, Object) calls impossible.

The message receive delegate is invoked for each received message on this flow. The flow event delegate is invoked when flow events occur, such as the flow going up or down. Both delegates are invoked in the context of the context thread to which this session belongs.

Note: disposing the corresponding context (IContext) or any of its contained context timers (TimerTask), sessions (ISession) or flows (IFlow) must not be performed from within the registered delegates (messageEventHandler or flowEventHandler).

An endpoint is a holding area which allows a client to attract Guaranteed messages matching a given subscription to a destination. There are two types of endpoints: "durable" and "non-durable". Durable in this context means that the client that is bound to the given endpoint does not have to be online to attract messages. Non-durable endpoints are disposed when the bound client disconnects.

A destination can be either temporary or non-temporary. A temporary destination is used as a "reply to" field in request/reply message exchange patterns. Wildcard subscription capabilities do not apply to temporary destinations.

With the exception of durable endpoint with temporary destination, the following cases are supported:

The message receive delegate is invoked for each received message on this flow. The flow event delegate is invoked when flow events occur, such as the flow going up or down. Both delegates are invoked in the context of the context thread to which this session belongs.

Note: disposing the corresponding context (IContext) or any of its contained context timers (TimerTask), sessions (ISession) or flows (IFlow) must not be performed from within the registered delegates (messageEventHandler or flowEventHandler).

This method is simply provided for convenience's sake. There is no lifecycle dependency between ISession and IMessage.

The non-durable endpoint is created on the appliance when a consumer is bound on this session.

The non-durable endpoint is created on the appliance when a consumer is bound on this session.

A temporary Queue can only be used to bind to non-durable endpoints. The non-durable endpoint is created on the appliance when a consumer is bound on this session.

Connect must be called before calling this method.

A temporary queue can only be used to bind to non-durable endpoints. The non-durable endpoint is created on the appliance when a consumer is bound on this session.

Connect must be called before calling this method.

Temporary topics can only be used to bind to non-durable endpoints.

Connect must be called before calling this method.

An Endpoint provision timer, controlled by the property ProvisionTimeoutInMsecs, controls the maximum amount of time a deprovsion attempt lasts for. Upon expiry of this timer, a ProvisionError event is returned in the session event delegate.

• ClientDescription
• ClientName

The property modifications can be carried out in a blocking or non-blocking mode, depending on the flag ModifyPropertyFlag Attempting to specify other Session properties will result in SOLCLIENT_FAIL being returned.

Note that only one outstanding client info modification request is allowed. Note that changing client name property would trigger the P2P topic changes. To avoid message loss, it is recommended that this API is used only at the initialization time.

An Endpoint provision timer, controlled by the property ProvisionTimeoutInMsecs, controls the maximum amount of time a provision attempt lasts for. Upon expiry of this timer, a ProvisionError event is returned in the session event delegate.

Note that the number of messages which can be sent through a single call to this method is limited to 50.

For sessions in which Send(IMessage[],...) is used, it is recommended that TcpNoDelay be set to true (it is enabled by default). In this case, multiple messages are sent at once onto a TCP connection, and therefore there is no need to have the operating system carry out the TCP delay algorithm to cause fuller IP packets.

Note: In order to use this feature, the parent ISession's SessionProperties must have TopicDispatch set to true.

Note: To use this feature, the parent ISession's SessionProperties must have TopicDispatch set to true.