#include <blpapi_session.h>

Inheritance diagram for blpapi::Session:

Public Types
enum	SubscriptionStatus { UNSUBSCRIBED = BLPAPI_SUBSCRIPTIONSTATUS_UNSUBSCRIBED, SUBSCRIBING = BLPAPI_SUBSCRIPTIONSTATUS_SUBSCRIBING, SUBSCRIBED = BLPAPI_SUBSCRIPTIONSTATUS_SUBSCRIBED, CANCELLED = BLPAPI_SUBSCRIPTIONSTATUS_CANCELLED, PENDING_CANCELLATION = BLPAPI_SUBSCRIPTIONSTATUS_PENDING_CANCELLATION }
Public Member Functions
	Session (const SessionOptions &options=SessionOptions(), EventHandler eventHandler=0, EventDispatcher eventDispatcher=0)
	Session (blpapi_Session_t *handle)
virtual	~Session ()
virtual bool	start ()
virtual bool	startAsync ()
virtual void	stop ()
virtual void	stopAsync ()
virtual Event	nextEvent (int timeout=0)
virtual int	tryNextEvent (Event *event)
void	subscribe (const SubscriptionList &subscriptionList, const Identity &identity, const char *requestLabel=0, int requestLabelLen=0)
void	subscribe (const SubscriptionList &subscriptionList, const char *requestLabel=0, int requestLabelLen=0)
void	unsubscribe (const SubscriptionList &subscriptionList)
void	resubscribe (const SubscriptionList &subscriptions)
void	resubscribe (const SubscriptionList &subscriptions, const char *requestLabel, int requestLabelLen)
void	resubscribe (const SubscriptionList &subscriptions, int resubscriptionId)
void	resubscribe (const SubscriptionList &subscriptions, int resubscriptionId, const char *requestLabel, int requestLabelLen)
void	setStatusCorrelationId (const Service &service, const CorrelationId &correlationID)
void	setStatusCorrelationId (const Service &service, const Identity &identity, const CorrelationId &correlationID)
CorrelationId	sendRequest (const Request &request, const CorrelationId &correlationId=CorrelationId(), EventQueue eventQueue=0, const char requestLabel=0, int requestLabelLen=0)
CorrelationId	sendRequest (const Request &request, const Identity &user, const CorrelationId &correlationId=CorrelationId(), EventQueue eventQueue=0, const char requestLabel=0, int requestLabelLen=0)
blpapi_Session_t *	handle () const
bool	openService (const char *serviceIdentifier)
CorrelationId	openServiceAsync (const char *serviceIdentifier, const CorrelationId &correlationId=CorrelationId())
CorrelationId	sendAuthorizationRequest (const Request &authorizationRequest, Identity identity, const CorrelationId &correlationId=CorrelationId(), EventQueue eventQueue=0)
void	cancel (const CorrelationId &correlationId)
void	cancel (const std::vector< CorrelationId > &correlationIds)
void	cancel (const CorrelationId *correlationIds, size_t numCorrelationIds)
CorrelationId	generateToken (const CorrelationId &correlationId=CorrelationId(), EventQueue *eventQueue=0)
Service	getService (const char *serviceIdentifier) const
UserHandle	createUserHandle ()
Identity	createIdentity ()
blpapi_AbstractSession_t *	abstractSessionHandle () const
Protected Member Functions
void	initAbstractSessionHandle (blpapi_AbstractSession_t *handle)
Friends
void	eventHandlerAdapter (blpapi_Event_t event, blpapi_Session_t , void *userData)

Detailed Description

This class provides a consumer session for making requests for Bloomberg services.

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 when it 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() or unsubscribe(), when a RESPONSE Event (not a PARTIAL_RESPONSE) containing it is received or when a 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 SESSION_STATUS Event generated by a 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().

Member Enumeration Documentation

enum blpapi::Session::SubscriptionStatus

Enumerator:

UNSUBSCRIBED	No longer active, terminated by API.
SUBSCRIBING	Initiated but no updates received.
SUBSCRIBED	Updates are flowing.
CANCELLED	No longer active, terminated by Application.
PENDING_CANCELLATION

Constructor & Destructor Documentation

blpapi::Session::Session	(	const SessionOptions &	options = `SessionOptions()`,
		EventHandler *	eventHandler = `0`,
		EventDispatcher *	eventDispatcher = `0`
	)

Construct a Session using the optionally specified options, the optionally specified eventHandler and the optionally specified eventDispatcher.

See the SessionOptions documentation for details on what can be specified in the options.

If eventHandler is not 0 then this Session will operation in asynchronous mode, otherwise the Session will operate in synchronous mode.

If eventDispatcher is 0 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 amongst 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, partial response to a request or updates to a single subscription.

If eventHandler is 0 and the eventDispatcher is not 0 an exception is thrown.

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.

blpapi::Session::Session ( blpapi_Session_t * handle ) [explicit]

virtual blpapi::Session::~Session ( ) [virtual]

Destructor.

Member Function Documentation

virtual bool blpapi::Session::start ( ) [virtual]

Attempt to start this Session and blocks until the Session has started or failed to start. If the Session is started successfully true is returned, otherwise false is returned. Before start() returns a SESSION_STATUS Event is generated. If this is an asynchronous Session then the SESSION_STATUS may be processed by the registered EventHandler before start() has returned. A Session may only be started once.

Implements blpapi::AbstractSession.

virtual bool blpapi::Session::startAsync ( ) [virtual]

Attempt to begin the process to start this Session and return true if successful, otherwise return false. The application must monitor events for a SESSION_STATUS Event which will be generated once the Session has started or if it fails to start. If this is an asynchronous Session then the SESSION_STATUS Event may be processed by the registered EventHandler before startAsync() has returned. A Session may only be started once.

Implements blpapi::AbstractSession.

virtual void blpapi::Session::stop ( ) [virtual]

Stop operation of this session and block until all callbacks to EventHandler objects relating to this Session which are currently in progress have completed (including the callback to handle the SESSION_STATUS Event with SessionTerminated message this call generates). Once this returns no further callbacks to EventHandlers will occur. If stop() is called from within an EventHandler callback the behavior is undefined and may result in a deadlock. Once a Session has been stopped it can only be destroyed.

Implements blpapi::AbstractSession.

virtual void blpapi::Session::stopAsync ( ) [virtual]

Begin the process to stop this Session and return immediately. The application must monitor events for a SESSION_STATUS Event with SessionTerminated message which will be generated once the Session has been stopped. After this SESSION_STATUS Event no further callbacks to EventHandlers will occur. This method can be called from within an EventHandler callback to stop Sessions using non-default (external) EventDispatcher. Once a Session has been stopped it can only be destroyed.

Implements blpapi::AbstractSession.

virtual Event blpapi::Session::nextEvent ( int timeout = 0 ) [virtual]

Returns the next available Event for this session. If there is no event available this will block for up to the specified timeoutMillis milliseconds for an Event to arrive. A value of 0 for timeoutMillis (the default) indicates nextEvent() should not timeout and will not return until the next Event is available.

If nextEvent() returns due to a timeout it will return an event of type EventType::TIMEOUT.

If this is invoked on a Session which was created in asynchronous mode an InvalidStateException is thrown.

Implements blpapi::AbstractSession.

virtual int blpapi::Session::tryNextEvent ( Event * event ) [virtual]

If there are Events available for the session, load the next Event into event and return 0 indicating success. If there is no event available for the session, return a non-zero value with no effect on event. This method never blocks.

Implements blpapi::AbstractSession.

void blpapi::Session::subscribe	(	const SubscriptionList &	subscriptionList,
		const Identity &	identity,
		const char *	requestLabel = `0`,
		int	requestLabelLen = `0`
	)

Begin subscriptions for each entry in the specified subscriptionList using the specified identity for authorization. If the optional requestLabel and requestLabelLen are provided they define a string which will be recorded along with any diagnostics for this operation. There must be at least requestLabelLen printable characters at the location requestLabel.

A SUBSCRIPTION_STATUS Event will be generated for each entry in the subscriptionList.

void blpapi::Session::subscribe	(	const SubscriptionList &	subscriptionList,
		const char *	requestLabel = `0`,
		int	requestLabelLen = `0`
	)

Begin subscriptions for each entry in the specified subscriptionList using the default authorization information. If the optional requestLabel and requestLabelLen are provided they define a string which will be recorded along with any diagnostics for this operation. There must be at least requestLabelLen printable characters at the location requestLabel.

A SUBSCRIPTION_STATUS Event will be generated for each entry in the subscriptionList.

void blpapi::Session::unsubscribe ( const SubscriptionList & subscriptionList )

Cancel each of the current subscriptions identified by the specified subscriptionList. If the correlation ID of any entry in the subscriptionList does not identify a current subscription then that entry is ignored. All entries which have valid correlation IDs will be cancelled.

Once this call returns the correlation ids in the subscriptionList will not be seen in any subsequent Message obtained from a MessageIterator by calling next(). However, any Message currently pointed to by a MessageIterator when unsubscribe() is called is not affected even if it has one of the correlation IDs in the subscriptionList. Also any Message where a reference has been retained by the application may still contain a correlation ID from the subscriptionList. For these reasons, although technically an application is free to re-use the correlation IDs as soon as this method returns it is preferable not to aggressively re-use correlation IDs, particularly with an asynchronous Session.

void blpapi::Session::resubscribe ( const SubscriptionList & subscriptions )

Modify each subscription in the specified subscriptionList to reflect the modified options specified for it.

For each entry in the subscriptionList which has a correlation ID which identifies a current subscription the modified options replace the current options for the subscription and a SUBSCRIPTION_STATUS event will be generated in the event stream before the first update based on the new options. If the correlation ID of an entry in the subscriptionList does not identify a current subscription then an exception is thrown.

void blpapi::Session::resubscribe	(	const SubscriptionList &	subscriptions,
		const char *	requestLabel,
		int	requestLabelLen
	)

Modify each subscription in the specified subscriptionList to reflect the modified options specified for it. The specified requestLabel and requestLabelLen define a string which will be recorded along with any diagnostics for this operation. There must be at least requestLabelLen printable characters at the location requestLabel.

For each entry in the subscriptionList which has a correlation ID which identifies a current subscription the modified options replace the current options for the subscription and a SUBSCRIPTION_STATUS event will be generated in the event stream before the first update based on the new options. If the correlation ID of an entry in the subscriptionList does not identify a current subscription then an exception is thrown.

void blpapi::Session::resubscribe	(	const SubscriptionList &	subscriptions,
		int	resubscriptionId
	)

Modify each subscription in the specified subscriptionList to reflect the modified options specified for it.

For each entry in the subscriptionList which has a correlation ID which identifies a current subscription the modified options replace the current options for the subscription and a SUBSCRIPTION_STATUS event containing the specified resubscriptionId will be generated in the event stream before the first update based on the new options. If the correlation ID of an entry in the subscriptionList does not identify a current subscription then an exception is thrown.

void blpapi::Session::resubscribe	(	const SubscriptionList &	subscriptions,
		int	resubscriptionId,
		const char *	requestLabel,
		int	requestLabelLen
	)

Modify each subscription in the specified subscriptionList to reflect the modified options specified for it. The specified requestLabel and requestLabelLen define a string which will be recorded along with any diagnostics for this operation. There must be at least requestLabelLen printable characters at the location requestLabel.

For each entry in the subscriptionList which has a correlation ID which identifies a current subscription the modified options replace the current options for the subscription and a SUBSCRIPTION_STATUS event containing the specified resubscriptionId will be generated in the event stream before the first update based on the new options. If the correlation ID of an entry in the subscriptionList does not identify a current subscription then an exception is thrown.

void blpapi::Session::setStatusCorrelationId	(	const Service &	service,
		const CorrelationId &	correlationID
	)

void blpapi::Session::setStatusCorrelationId	(	const Service &	service,
		const Identity &	identity,
		const CorrelationId &	correlationID
	)

Set the CorrelationID on which service status messages will be received. Note: No service status messages are received prior to this call

CorrelationId blpapi::Session::sendRequest	(	const Request &	request,
		const CorrelationId &	correlationId = `CorrelationId()`,
		EventQueue *	eventQueue = `0`,
		const char *	requestLabel = `0`,
		int	requestLabelLen = `0`
	)

Send the specified request. If the optionally specified correlationId is supplied use it otherwise create a CorrelationId. The actual CorrelationId used is returned. If the optionally specified eventQueue is supplied all events relating to this Request will arrive on that EventQueue. If the optional requestLabel and requestLabelLen are provided they define a string which will be recorded along with any diagnostics for this operation. There must be at least requestLabelLen printable characters at the location requestLabel.

A successful request will generate zero or more PARTIAL_RESPONSE Messages followed by exactly one RESPONSE Message. Once the final RESPONSE Message has been received the correlation ID associated with this request may be re-used. If the request fails at any stage a REQUEST_STATUS will be generated after which the correlation ID associated with the request may be re-used.

CorrelationId blpapi::Session::sendRequest	(	const Request &	request,
		const Identity &	user,
		const CorrelationId &	correlationId = `CorrelationId()`,
		EventQueue *	eventQueue = `0`,
		const char *	requestLabel = `0`,
		int	requestLabelLen = `0`
	)

Send the specified request using the specified identity for authorization. If the optionally specified correlationId is supplied use it otherwise create a CorrelationId. The actual CorrelationId used is returned. If the optionally specified eventQueue is supplied all events relating to this Request will arrive on that EventQueue. If the optional requestLabel and requestLabelLen are provided they define a string which will be recorded along with any diagnostics for this operation. There must be at least requestLabelLen printable characters at the location requestLabel.

A successful request will generate zero or more PARTIAL_RESPONSE Messages followed by exactly one RESPONSE Message. Once the final RESPONSE Message 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.

blpapi_Session_t* blpapi::Session::handle ( ) const

void blpapi::AbstractSession::initAbstractSessionHandle ( blpapi_AbstractSession_t * handle ) [protected, inherited]

Initialize the handle of this abstract session.

bool blpapi::AbstractSession::openService ( const char * serviceIdentifier ) [inherited]

Attempt to open the service identified by the specified serviceIdentifier and block until the service is either opened successfully or has failed to be opened. Return true if the service is opened successfully and false if the service cannot be successfully opened.

The serviceIdentifier must contain a fully qualified service name. That is, it must be of the form "//<namespace>/<local-name>".

Before openService() returns a SERVICE_STATUS Event is generated. If this is an asynchronous Session then this Event may be processed by the registered EventHandler before openService() has returned.

CorrelationId blpapi::AbstractSession::openServiceAsync	(	const char *	serviceIdentifier,
		const CorrelationId &	correlationId = `CorrelationId()`
	)			`[inherited]`

Begin the process to open the service identified by the specified serviceIdentifier and return immediately. The optional specified correlationId is used to track Events generated as a result of this call. The actual correlationId which will identify Events generated as a result of this call is returned.

The serviceIdentifier must contain a fully qualified service name. That is, it must be of the form "//<namespace>/<local-name>".

The application must monitor events for a SERVICE_STATUS Event which will be generated once the service has been successfully opened or the opening has failed.

CorrelationId blpapi::AbstractSession::sendAuthorizationRequest	(	const Request &	authorizationRequest,
		Identity *	identity,
		const CorrelationId &	correlationId = `CorrelationId()`,
		EventQueue *	eventQueue = `0`
	)			`[inherited]`

Send the specified authorizationRequest and update the specified identity with the results. If the optionally specified correlationId is supplied, it is used; otherwise create a CorrelationId. The actual CorrelationId used is returned. If the optionally specified eventQueue is supplied all Events relating to this Request will arrive on that EventQueue.

The underlying user information must remain valid until the Request has completed successfully or failed.

A successful request will generate zero or more PARTIAL_RESPONSE Messages followed by exactly one RESPONSE Message. Once the final RESPONSE Message has been received the specified identity will have been updated to contain the users entitlement information and the CorrelationId associated with the request may be re-used. If the request fails at any stage a REQUEST_STATUS will be generated, the specified identity will not be modified and the CorrelationId may be re-used.

The identity supplied must have been returned from this Session's createIdentity() method. For example

         Identity handle(session.createIdentity());
         session.sendAuthorizationRequest(authRequest, &handle, ...)

void blpapi::AbstractSession::cancel ( const CorrelationId & correlationId ) [inherited]

If the specified correlationId identifies a current request then cancel that request.

Once this call returns the specified correlationId will not be seen in any subsequent Message obtained from a MessageIterator by calling next(). However, any Message currently pointed to by a MessageIterator when cancel() is called is not affected even if it has the specified correlationId. Also any Message where a reference has been retained by the application may still contain the correlationId. For these reasons, although technically an application is free to re-use correlationId as soon as this method returns it is preferable not to aggressively re-use correlation IDs, particularly with an asynchronous Session.

void blpapi::AbstractSession::cancel ( const std::vector< CorrelationId > & correlationIds ) [inherited]

For each value in the specified correlationIds which identifies a current request then cancel that request. Any values in the specified correlationIds which do not identify a current request are ignored.

Once this call returns the specified correlationIds will not be seen in any subsequent Message obtained from a MessageIterator by calling next(). However, any Message currently pointed to by a MessageIterator when cancel() is called is not affected even if it has one of the specified correlationIds. Also any Message where a reference has been retained by the application may still contain one of the correlationIds. For these reasons, although technically an application is free to re-use any of the correlationIds as soon as this method returns it is preferable not to aggressively re-use correlation IDs, particularly with an asynchronous Session.

void blpapi::AbstractSession::cancel	(	const CorrelationId *	correlationIds,
		size_t	numCorrelationIds
	)			`[inherited]`

For each value specified correlationIds and numCorrelationIds which identifies a current request then cancel that request. Any specified CorrelationId's which do not identify a current request are ignored.

Once this call returns the specified correlationIds will not be seen in any subsequent Message obtained from a MessageIterator by calling next(). However, any Message currently pointed to by a MessageIterator when cancel() is called is not affected even if it has one of the specified correlationIds. Also any Message where a reference has been retained by the application may still contain one of the correlationIds. For these reasons, although technically an application is free to re-use any of the correlationIds as soon as this method returns it is preferable not to aggressively re-use correlation IDs, particularly with an asynchronous Session.

CorrelationId blpapi::AbstractSession::generateToken	(	const CorrelationId &	correlationId = `CorrelationId()`,
		EventQueue *	eventQueue = `0`
	)			`[inherited]`

Generate a token to be used for authorization. If invalid authentication option is specified in session option or there is failure to get authentication information based on authentication option, then an InvalidArgumentException is thrown.

Service blpapi::AbstractSession::getService ( const char * serviceIdentifier ) const [inherited]

Return a Service object representing the service identified by the specified serviceIdentifier

The serviceIdentifier must contain a fully qualified service name. That is, it must be of the form "//<namespace>/<local-name>".

If the service identified by serviceIdentifier is not open or registered already then a NotFoundException is thrown.

UserHandle blpapi::AbstractSession::createUserHandle ( ) [inherited]

Deprecated: Use createIdentity() instead. TODO: doxy Return a UserHandle which is valid but has not been authorized.

Identity blpapi::AbstractSession::createIdentity ( ) [inherited]

Return a Identity which is valid but has not been authorized.

blpapi_AbstractSession_t* blpapi::AbstractSession::abstractSessionHandle ( ) const [inherited]

Return the handle of this abstract session.

Friends And Related Function Documentation

void eventHandlerAdapter	(	blpapi_Event_t *	event,
		blpapi_Session_t *	,
		void *	userData
	)			`[friend]`

Adapter blpapi_EventHandler_t implementation that dispatches the specified event to a blpapi::Session pointed by userData.

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

blpapi_session.h

blpapi::Session Class Reference

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation