Session Class

Session Class

This class provides a session for making requests and subscriptions to services.

Inheritance Hierarchy

SystemObject
Bloomberglp.BlpapiAbstractSession
Bloomberglp.BlpapiSession

Namespace: Bloomberglp.Blpapi
Assembly: Bloomberglp.Blpapi (in Bloomberglp.Blpapi.dll) Version: 3.24.10.1

Syntax

C++

Copy

public class Session : AbstractSession, ISession, 
	IAbstractSession, IDisposable

Public Class Session
	Inherits AbstractSession
	Implements ISession, IAbstractSession, IDisposable

public ref class Session : public AbstractSession, 
	ISession, IAbstractSession, IDisposable

type Session =  
    class
        inherit AbstractSession
        interface ISession
        interface IAbstractSession
        interface IDisposable
    end

The Session type exposes the following members.

Constructors

	Name	Description
	Session	Same as calling Session(new SessionOptions(), null, null)
	Session(SessionOptions)	Creates a session with the specified sessionOptions. Remarks Same as calling Session(sessionOptions, null, null). Values in sessionOptions are used for configuring this session.
	Session(SessionOptions, EventHandler)	Creates a session with the specified sessionOptions and dispatch events on this session to the specified handler Remarks Same as calling Session(sessionOptions, handler, null) Values in sessionOptions are used for configuring this session. The event handler to which all events are delivered.
	Session(SessionOptions, EventHandler, EventDispatcher)	Creates a session with the specified sessionOptions and dispatch events on this session using the provided dispatcher to the specified handler Remarks See SessionOptions for information on what options can be specified. If the specified eventHandler is not null then this Session will operate in asynchronous mode, otherwise the Session will operate in Synchronous mode. If eventDispatcher is null then the Session will create a default EventDispatcher for this Session which will use a single thread for dispatching events. For more control over event dispatching a specific instance of EventDispatcher can be supplied. This can be used to share a single EventDispatcher among multiple Session objects. If an eventDispatcher is supplied which uses more than one thread the Session will ensure that events which should be ordered are passed to callbacks in a correct order. For example, updates to a single subscription. Each EventDispatcher uses its own thread or pool of threads so if you want to ensure that a session which receives very large messages and takes a long time to process them does not delay a session that receives small messages and processes each one very quickly then give each one a separate EventDispatcher. Values in sessionOptions are used for configuring this session. The event handler to which all events are delivered. The dispatcher to be used for dispatching events.

Top

Properties

	Name	Description
	SessionName	Returns the session name. (Inherited from AbstractSession.)

Top

Methods

	Name	Description
	Cancel(CorrelationID)	Cancels an outstanding request or a subscription represented by the specified correlationId. (Inherited from AbstractSession.)
	Cancel(IListCorrelationID)	Cancels outstanding requests or subscriptions represented by the specified list of correlationIds. (Inherited from AbstractSession.)
	Cancel(CorrelationID, String)	Cancels an outstanding request or a subscription represented by the specified correlationId. (Inherited from AbstractSession.)
	Cancel(IListCorrelationID, String)	Cancels outstanding requests or subscriptions represented by the specified list of correlationIds. (Inherited from AbstractSession.)
	CreateIdentity	Returns a new Identity which is valid but has not been authorized. (Inherited from AbstractSession.)
	createSnapshotRequestTemplate(String, CorrelationID)	Same as calling createSnapshotRequestTemplate( subscriptionString, statusCid, null) The session identity will be used if it's been authorized.
	createSnapshotRequestTemplate(String, CorrelationID, Identity)	Create a snapshot service request template for getting subscription data specified by the 'subscriptionString' using the optionally specified 'identity' if all the following conditions are met: the session is established, 'subscriptionString' is a valid subscription string and 'statusCid' is not used in this session. If one or more conditions are not met, an exception is thrown. The provided 'statusCid' will be used for an implied subscription associated with the create request template. The created request template status updates will be delivered using ADMIN events. The benefit of the snapshot service request templates is that these requests may be serviced from a cache and the user may expect to see significantly lower response time. There are 3 possible states for a created request template: 'Pending', 'Available', and 'Terminated'. A 'RequestTemplate' is initially in the 'Pending' state. The user may send a request using a template that is in 'Pending' state. If this succeeds, the state of that template changes to 'Available'. Note that response times to receive data may be longer than a response time for a request in the 'Available' state since request caches may not yet have been established. A template may transition back into 'Pending' state from the 'Available' state, in which case a 'RequestTemplatePending' message will be generated. If state is 'Available', all requests will be serviced from a cache and the user may expect to see significantly reduced latency. Note, that a snapshot request template can transition out of the 'Available' state concurrently with requests being sent, so no guarantee of service from the cache can be provided. Request template may transition into 'Available' state only from the 'Pending' state. In this case the 'RequestTemplateAvailable' message is generated. This message will also contain information about currently used connection in the 'boundTo' field. Note that it is possible to get the 'RequestTemplateAvailable' message with a new connection information, even if a request template is already in the 'Available' state. If state is 'Terminated', sending request will always result in a failure response. Request template may transition into this state from any other state. This is a final state and it is guaranteed that the last message associated with the provided 'statusCid' will be the 'RequestTemplateTerminated' message which is generated when a request template transitions into this state. If a request template transitions into this state, all outstanding requests will be failed and appropriate messages will be generated for each request. After receiving the 'RequestTemplateTerminated' message, 'statusCid' may be reused. Note that resources used by a snapshot service request template are released only when request template transitions into the 'Terminated' state or when session is destroyed. In order to release resources when request template is not needed anymore, user should call Cancel(CorrelationID) or close unless the 'RequestTemplateTerminated' message was already received due to some problems. If the 'Session.cancel' method is used, all outstanding requests are canceled and the underlying subscription is closed immediately. If the handle is closed with the 'RequestTemplate.close' method, the underlying subscription is closed only when all outstanding requests are served. Note that it is possible to have a situation when response contain data that were sent by a backend before user actually sends a request template. For example it is possible if user requested data were already in an incoming TCP queue.
	CreateUserHandle	Obsolete. Deprecated since 3.3.0.0. Use CreateIdentity instead. (Inherited from AbstractSession.)
	DispatchEvent	Dispatches event with event handler if it has been set otherwise do nothing. Event handlers are set by a library client in case of async session. SetEventHandler(ISessionEventHandler), SetEventHandler(ISessionEventHandler, EventEventType), EventEventType (Inherited from AbstractSession.)
	Dispose	Dispose this Session object. It calls AbstractSession.Stop() to close the opened socket. (Inherited from AbstractSession.)
	GenerateAuthorizedIdentity	Generates an authorized Identity with the specified authOptions and cid. One or more AUTHORIZATION_STATUS events, zero or more TOKEN_STATUS events and zero or more SERVICE_STATUS events are generated. If this is an asynchronous AbstractSession then an Event may be processed by the registered EventHandler before GenerateAuthorizedIdentity(AuthOptions, CorrelationID) has returned. The behavior is undefined when authOptions is null. (Inherited from AbstractSession.)
	GenerateToken	Return a generated token to be used for authorization. (Inherited from AbstractSession.)
	GenerateToken(CorrelationID)	Return a generated token to be used for authorization. (Inherited from AbstractSession.)
	GenerateToken(CorrelationID, IEventQueue)	Return a generated token to be used for authorization. (Inherited from AbstractSession.)
	GenerateToken(String, String, CorrelationID, IEventQueue)	Return a generated token to be used for authorization. (Inherited from AbstractSession.)
	GetAuthorizedIdentity	Gets the authorized Identity associated with the specified cid. If cid is omitted and the session identity is authorized, the function will return the session identity. (Inherited from AbstractSession.)
	GetService	Returns the Service identified by serviceName. (Inherited from AbstractSession.)
	GetSubscriptions	Returns an enumerable collection for iterating over the subscriptions.
	GetSubscriptionStatus	Returns the subscription status for the specified correlationId.
	GetSubscriptionString	Returns the subscription string for the specified correlationId.
	Init	Initialize AbstractSession. Must be called from the constructor(s) of the derived class. (Inherited from AbstractSession.)
	NextEvent	Returns the next event available for processing on this session. (Inherited from AbstractSession.)
	NextEvent(Int64)	Returns the next event available for processing on this session. (Inherited from AbstractSession.)
	OpenService	Opens the service identified by serviceName. (Inherited from AbstractSession.)
	OpenServiceAsync(String)	Issues an asynchronous request to open a service. (Inherited from AbstractSession.)
	OpenServiceAsync(String, CorrelationID)	Initiates an asynchronous request to open a service. (Inherited from AbstractSession.)
	Resubscribe(IListSubscription)	This is the same as calling Resubscribe(subscriptionList, requestLabel: null) .
	Resubscribe(IListSubscription, SubscriptionPreprocessMode)	This is the same as calling Subscribe(subscriptionList, requestLabel: null, mode)
	Resubscribe(IListSubscription, Int32)	This is the same as calling Resubscribe(subscriptionList, resubId, requestLabel: null) .
	Resubscribe(IListSubscription, String)	Modifies each subscription in the specified subscriptionList to reflect the modified options specified for it.
	Resubscribe(IListSubscription, Int32, SubscriptionPreprocessMode)	This is the same as calling Subscribe(subscriptionList, resubId, requestLabel: null, mode)
	Resubscribe(IListSubscription, Int32, String)	Modifies each subscription in the specified subscriptionList to reflect the modified options specified for it.
	Resubscribe(IListSubscription, String, SubscriptionPreprocessMode)	Modifies each subscription in the subscriptionList to reflect the modified options specified for it.
	Resubscribe(IListSubscription, Int32, String, SubscriptionPreprocessMode)	Modifies each subscription in the subscriptionList to reflect the modified options specified for it.
	SendAuthorizationRequest(Request, Identity, CorrelationID)	Sends the specified authorizationRequest and update the specified identity with the results. (Inherited from AbstractSession.)
	SendAuthorizationRequest(Request, UserHandle, CorrelationID)	Obsolete. Deprecated since 3.3.0.0. Use SendAuthorizationRequest(Request, Identity, CorrelationID)instead. (Inherited from AbstractSession.)
	SendAuthorizationRequest(Request, Identity, CorrelationID, String)	Sends the specified authorizationRequest and update the specified identity with the results. (Inherited from AbstractSession.)
	SendAuthorizationRequest(Request, Identity, IEventQueue, CorrelationID)	Sends the specified authorizationRequest and update the specified identity with the results. (Inherited from AbstractSession.)
	SendAuthorizationRequest(Request, UserHandle, CorrelationID, String)	Obsolete. Deprecated since 3.3.0.0. Use SendAuthorizationRequest(Request, Identity, CorrelationID, String) instead. (Inherited from AbstractSession.)
	SendAuthorizationRequest(Request, UserHandle, IEventQueue, CorrelationID)	Obsolete. Deprecated since 3.3.0.0. Use SendAuthorizationRequest(Request, Identity, IEventQueue, CorrelationID) instead. (Inherited from AbstractSession.)
	SendAuthorizationRequest(Request, Identity, IEventQueue, CorrelationID, String)	Sends the specified authorizationRequest and update the specified identity with the results. (Inherited from AbstractSession.)
	SendAuthorizationRequest(Request, UserHandle, IEventQueue, CorrelationID, String)	Obsolete. Deprecated since 3.3.0.0. Use SendAuthorizationRequest(Request, UserHandle, IEventQueue, CorrelationID, String) instead. (Inherited from AbstractSession.)
	SendRequest(RequestTemplate)	Same as calling 'SendRequest(requestTemplate, null)'
	SendRequest(Request, CorrelationID)	Sends the specified request to a service using this session. The session identity will be used if it's been authorized.
	SendRequest(RequestTemplate, CorrelationID)	Send a request defined by the specified 'requestTemplate'. If the optionally specified 'correlationId' is supplied, use it otherwise create a new 'CorrelationId'. The actual 'CorrelationId' used is returned. A successful request will generate zero or more 'PARTIAL_RESPONSE' events followed by exactly one 'RESPONSE' event. Once the final 'RESPONSE' event has been received the 'CorrelationId' associated with this request may be re-used. If the request fails at any stage a 'REQUEST_STATUS' will be generated after which the 'CorrelationId' associated with the request may be re-used.
	SendRequest(Request, CorrelationID, String)	Sends the specified request to a service using this session. The session identity will be used if it's been authorized.
	SendRequest(Request, Identity, CorrelationID)	Sends the specified request to a service using this session.
	SendRequest(Request, IEventQueue, CorrelationID)	Sends the specified request to a service using this session. The session identity will be used if it's been authorized.
	SendRequest(Request, UserHandle, CorrelationID)	Obsolete. Deprecated since 3.3.0.0. Use SendRequest(Request, Identity, CorrelationID) instead.
	SendRequest(Request, Identity, CorrelationID, String)	Sends the specified request to a service using this session.
	SendRequest(Request, Identity, IEventQueue, CorrelationID)	Sends the specified request to a service using this session.
	SendRequest(Request, IEventQueue, CorrelationID, String)	Sends the specified request to a service using this session.
	SendRequest(Request, UserHandle, CorrelationID, String)	Obsolete. Deprecated since 3.3.0.0. Use SendRequest(Request, Identity, CorrelationID, String) instead.
	SendRequest(Request, UserHandle, IEventQueue, CorrelationID)	Obsolete. Deprecated since 3.3.0.0. Use SendRequest(Request, Identity, IEventQueue, CorrelationID) instead.
	SendRequest(Request, Identity, IEventQueue, CorrelationID, String)	Sends the specified request to a service using this session.
	SendRequest(Request, UserHandle, IEventQueue, CorrelationID, String)	Obsolete. Deprecated since 3.3.0.0. Use SendRequest(Request, Identity, IEventQueue, CorrelationID, String) instead.
	SetEventHandler	Set event specific event handlers
	Start	Issues a blocking call to start the session. (Inherited from AbstractSession.)
	StartAsync	Initiates a non blocking call to start the session. (Inherited from AbstractSession.)
	Stop	Stops this session. (Inherited from AbstractSession.)
	Stop(AbstractSessionStopOption)	Stops the operation of this session. (Inherited from AbstractSession.)
	Subscribe(IListSubscription)	This is the same as calling Subscribe(subscriptionList, identity: null, requestLabel: null) .
	Subscribe(IListSubscription, Identity)	This is the same as calling Subscribe(subscriptionList, identity, requestLabel: null) .
	Subscribe(IListSubscription, SubscriptionPreprocessMode)	This is the same as calling Subscribe(subscriptionList, identity: null, requestLabel: null, mode)
	Subscribe(IListSubscription, UserHandle)	Obsolete. Deprecated since 3.3.0.0. Use Subscribe(IListSubscription, Identity) instead.
	Subscribe(IListSubscription, String)	This is the same as calling Subscribe(subscriptionList, identity: null, requestLabel) .
	Subscribe(IListSubscription, Identity, SubscriptionPreprocessMode)	This is the same as calling Subscribe(subscriptionList, identity, requestLabel: null, mode)
	Subscribe(IListSubscription, Identity, String)	Initiates a request to receive asynchronous updates to the specified topics in the subscriptionList.
	Subscribe(IListSubscription, UserHandle, String)	Obsolete. Deprecated since 3.3.0.0. Use Subscribe(IListSubscription, Identity, String) instead.
	Subscribe(IListSubscription, String, SubscriptionPreprocessMode)	This is the same as calling Subscribe(subscriptionList, identity: null, requestLabel, mode)
	Subscribe(IListSubscription, Identity, String, SubscriptionPreprocessMode)	Initiates a request to receive asynchronous updates to the specified topics in the subscriptionList.
	TryNextEvent	Tries to retrieve the next event available for processing on this session (Inherited from AbstractSession.)
	Unsubscribe(CorrelationID)	Obsolete. Cancels a previous request for asynchronous topic updates associated with the specified correlationId.
	Unsubscribe(IListSubscription)	Cancels previous requests for asynchronous topic updates associated with the correlation ids listed in the specified subscriptionList.
	Unsubscribe(IListSubscription, String)	Cancels previous requests for asynchronous topic updates associated with the correlation ids listed in the specified subscriptionList.

Top

Remarks

Sessions manage access to services either by requests and responses or subscriptions. A Session can dispatch events and replies in either a synchronous or asynchronous mode. The mode of a Session is determined when it is constructed and cannot be changed subsequently.

A Session is asynchronous if an EventHandler object is supplied whenit is constructed. The SetEventHandler() method may be called to adjust the way events are handled subsequently and the NextEvent() method may not be called. All incoming events are delivered to the EventHandler(s) supplied on construction or subsequently using SetEventHandler().

A Session is synchronous if an EventHandler object is not supplied when it is constructed. The NextEvent() method must be called to read incoming events and the SetEventHandler() method may not be called. Several methods in Session take a CorrelationID parameter. The application may choose to supply its own CorrelationID values or allow the Session to create values. If the application supplies its own CorrelationID values it must manage their lifetime such that the same value is not reused for more than one operation at a time. The lifetime of a CorrelationID begins when it is supplied in a method invoked on a Session and ends either when it is explicitly cancelled using Cancel(CorrelationID), when a Event.EventType.RESPONSE Event (not a PARTIAL_RESPONSE) containing it is received or when a Event.EventType.SUBSCRIPTION_STATUS Event which indicates that the subscription it refers to has been terminated is received.

When using an asynchronous Session the application must be aware that because the callbacks are generated from another thread they may be processed before the call which generates them has returned. For example, the Event.EventType.SESSION_STATUS Event generated by the StartAsync may be processed before StartAsync() has returned (even though StartAsync() itself will not block).

This becomes more significant when Session generated CorrelationIds are in use. For example, if a call to Subscribe() which returns a Session generated CorrelationID has not completed before the first Events which contain that CorrelationID arrive the application may not be able to interpret those events correctly. For this reason, it is preferable to use user generated CorrelationIDs when using asynchronous Sessions. This issue does not arise when using a synchronous Session as long as the calls to Subscribe() etc are made on the same thread as the calls to NextEvent().

Thread Safety

Static members of this type are safe for multi-threaded operations. Instance members of this type are safe for multi-threaded operations.

Thread Safety

Static members of this type are safe for multi-threaded operations. Instance members of this type are safe for multi-threaded operations.

Reference

Bloomberglp.Blpapi Namespace