#include <blpapi_providersession.h>

Inheritance diagram for blpapi::ProviderSession:

Public Types
enum	ResolveMode { AUTO_REGISTER_SERVICES = BLPAPI_RESOLVEMODE_AUTO_REGISTER_SERVICES, DONT_REGISTER_SERVICES = BLPAPI_RESOLVEMODE_DONT_REGISTER_SERVICES }
Public Member Functions
	ProviderSession (const SessionOptions &options=SessionOptions(), ProviderEventHandler eventHandler=0, EventDispatcher eventDispatcher=0)
	ProviderSession (blpapi_ProviderSession_t *handle)
virtual	~ProviderSession ()
virtual bool	start ()
virtual bool	startAsync ()
virtual void	stop ()
virtual void	stopAsync ()
virtual Event	nextEvent (int timeout=0)
virtual int	tryNextEvent (Event *event)
bool	registerService (const char *serviceName, const Identity &providerIdentity=Identity(), const ServiceRegistrationOptions &registrationOptions=ServiceRegistrationOptions())
void	activateSubServiceCodeRange (const char *serviceName, int begin, int end, int priority)
void	deactivateSubServiceCodeRange (const char *serviceName, int begin, int end)
CorrelationId	registerServiceAsync (const char *serviceName, const Identity &providerIdentity=Identity(), const CorrelationId &correlationId=CorrelationId(), const ServiceRegistrationOptions &registrationOptions=ServiceRegistrationOptions())
bool	deregisterService (const char *serviceName)
void	resolve (ResolutionList *resolutionList, ResolveMode resolveMode=DONT_REGISTER_SERVICES, Identity providerIdentity=Identity())
void	resolveAsync (const ResolutionList &resolutionList, ResolveMode resolveMode=DONT_REGISTER_SERVICES, const Identity &providerIdentity=Identity())
Topic	createTopic (const Message &message)
Topic	getTopic (const Message &message)
Topic	createServiceStatusTopic (const Service &service)
void	publish (const Event &event)
void	sendResponse (const Event &event, bool isPartialResponse=false)
void	createTopics (TopicList *topicList, ResolveMode resolveMode=DONT_REGISTER_SERVICES, Identity providerIdentity=Identity())
void	createTopicsAsync (const TopicList &topicList, ResolveMode resolveMode=DONT_REGISTER_SERVICES, const Identity &providerIdentity=Identity())
void	deleteTopic (const Topic &topic)
void	deleteTopics (const std::vector< Topic > &topics)
void	deleteTopics (const Topic *topics, size_t numTopics)
void	terminateSubscriptionsOnTopic (const Topic &topic, const char *message=0)
void	terminateSubscriptionsOnTopics (const std::vector< Topic > &topics, const char *message=0)
void	terminateSubscriptionsOnTopics (const Topic topics, size_t numTopics, const char message=0)
blpapi_ProviderSession_t *	handle () const
bool	flushPublishedEvents (int timeoutMsecs)
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)
CorrelationId	generateToken (const char userId, const char ipAddress, 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	blpapi_providerEventHandlerAdapter (blpapi_Event_t event, blpapi_ProviderSession_t session, void *userData)

Detailed Description

This class provides a session that can be used for providing services.

It inherits from AbstractSession. In addition to the AbstractSession functionality a ProviderSession provides the following functions to applications.

A provider can register to provide services using ProviderSession::registerService*. Before registering to provide a service the provider must have established its identity. Then the provider can create topics and publish events on topics. It can also get requests from the event queue and send reponses back.

After users have registered a service they will start receiving subscription requests (TopicSubscribed message in TOPIC_STATUS) for topics which belong to the service. If the resolver has specified subServiceCode for topics in PermissionResponse, then only providers who have activated the subServiceCode will get the subscription request. Where multiple providers have registered the same service and sub-service code (if any), the provider that registered the highest priority for the sub-service code will receive subscription requests; if multiple providers have registered the same sub-service code with the same priority (or the resolver did not set a sub-service code for the subscription), the subscription request will be routed to one of the providers with the highest service priority.

Member Enumeration Documentation

enum blpapi::ProviderSession::ResolveMode

Enumerator:

AUTO_REGISTER_SERVICES	Try to register services found in ResolutionList if necessary.
DONT_REGISTER_SERVICES	Fail to resolve a topic if the service has not already been registered.

Constructor & Destructor Documentation

blpapi::ProviderSession::ProviderSession	(	const SessionOptions &	options = `SessionOptions()`,
		ProviderEventHandler *	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 null then this Session will operation in asynchronous mode, otherwise the Session will operate in synchronous mode.

If eventDispatcher is null and a not null eventHandler is provided, then the Session will create an 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.

The behavior is undefined if eventHandler is null and the eventDispatcher is not null.

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::ProviderSession::ProviderSession ( blpapi_ProviderSession_t * handle ) [explicit]

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

Destructor.

Member Function Documentation

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

See AbstractSession::start().

Implements blpapi::AbstractSession.

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

See AbstractSession::startAsync().

Implements blpapi::AbstractSession.

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

See AbstractSession::stop().

Implements blpapi::AbstractSession.

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

See AbstractSession::stopAsync().

Implements blpapi::AbstractSession.

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

See AbstractSession::nextEvent().

Implements blpapi::AbstractSession.

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

See AbstractSession::tryNextEvent()

Implements blpapi::AbstractSession.

bool blpapi::ProviderSession::registerService	(	const char *	serviceName,
		const Identity &	providerIdentity = `Identity()`,
		const ServiceRegistrationOptions &	registrationOptions = `ServiceRegistrationOptions()`
	)

Attempt to register the service identified by the specified serviceName and block until the service is either registered successfully or has failed to be registered. The optionally specified providerIdentity is used to verify permissions to provide the service being registered. The optionally specified registrationOptions is used to specify the group ID and service priority of the service being registered. Returns true if the service is registered successfully and false if the service cannot be registered successfully.

The serviceName must be a full qualified service name. That is it must be of the form //<namespace>/<local-name>.

This function does not return until a SERVICE_STATUS event has been generated. Note that if the session was created in asynchronous mode, the event may be processed before the function returns.

void blpapi::ProviderSession::activateSubServiceCodeRange	(	const char *	serviceName,
		int	begin,
		int	end,
		int	priority
	)

Register to receive, with the specified priority, subscriptions for the specified service that the resolver has mapped to a service code between the specified begin and the specified end values, inclusive. Numerically greater values of priority indicate higher priorities. The behavior of this function is undefined unless service has already been successfully registered, 0 <= begin <= end < (1 << 24), and priority is

void blpapi::ProviderSession::deactivateSubServiceCodeRange	(	const char *	serviceName,
		int	begin,
		int	end
	)

De-register to receive subscriptions for the specified service that the resolver has mapped to a service code between the specified begin and the specified end values, inclusive. The behavior of this function is undefined unless service has already been successfully registered and 0 <= begin <= end < (1 << 24).

CorrelationId blpapi::ProviderSession::registerServiceAsync	(	const char *	serviceName,
		const Identity &	providerIdentity = `Identity()`,
		const CorrelationId &	correlationId = `CorrelationId()`,
		const ServiceRegistrationOptions &	registrationOptions = `ServiceRegistrationOptions()`
	)

Begin the process of registering the service identified by the specified serviceName and return immediately. The optionally specified providerIdentity is used to verify permissions to provide the service being registered. The optionally specified correlationId is used to track Event objects generated as a result of this call. Return the actual CorrelationId object that will identify Event objects. The optionally specified registrationOptions is used to specify the group ID and service priority of the service being registered.

The serviceName must be a full 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 registered or registration has failed.

bool blpapi::ProviderSession::deregisterService ( const char * serviceName )

Deregister the service, including all registered parts, identified by the specified serviceName. The identity in the service registration is reused to verify permissions for deregistration. If the service is not registered nor in pending registration, return false; return true otherwise. If the service is in pending registration, cancel the pending registration. If the service is registered, send a deregistration request; generate TOPIC_STATUS events containing a TopicUnsubscribed message for each subscribed topic, a TopicDeactivated message for each active topic and a TopicDeleted for each created topic; generate REQUEST_STATUS events containing a RequestFailure message for each pending incoming request; and generate a SERVICE_STATUS Event containing a ServiceDeregistered message. All published events on topics created on this service will be ignored after this method returns.

void blpapi::ProviderSession::resolve	(	ResolutionList *	resolutionList,
		ResolveMode	resolveMode = `DONT_REGISTER_SERVICES`,
		Identity	providerIdentity = `Identity()`
	)

Resolves the topics in the specified resolutionList and updates the resolutionList with the results of the resolution process. If the specified resolveMode is DONT_REGISTER_SERVICES (the default) then all the services referenced in the topics in the resolutionList must already have been registered using registerService(). If resolveMode is AUTO_REGISTER_SERVICES then the specified providerIdentity should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the resolutionList that have not already been registered. Once resolveSync() returns each entry in the resolutionList will have been updated with a new status.

Before resolveSync() returns one or more RESOLUTION_STATUS events and, if resolveMode is AUTO_REGISTER_SERVICES, zero or more SERVICE_STATUS events are generated. If this is an asynchronous ProviderSession then these Events may be processed by the registered EventHandler before resolve() has returned.

void blpapi::ProviderSession::resolveAsync	(	const ResolutionList &	resolutionList,
		ResolveMode	resolveMode = `DONT_REGISTER_SERVICES`,
		const Identity &	providerIdentity = `Identity()`
	)

Begin the resolution of the topics in the specified resolutionList. If the specified resolveMode is DONT_REGISTER_SERVICES (the default) then all the services referenced in the topics in the resolutionList must already have been registered using registerService(). If resolveMode is AUTO_REGISTER_SERVICES then the specified providerIdentity should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the resolutionList that have not already been registered.

One or more RESOLUTION_STATUS events will be delivered with the results of the resolution. These events may be generated before or after resolve() returns. If AUTO_REGISTER_SERVICES is specified SERVICE_STATUS events may also be generated before or after resolve() returns.

Topic blpapi::ProviderSession::createTopic ( const Message & message )

Create a topic from the specified message, which must be of type ResolutionSuccess. This method is deprecated; use createTopics or createTopicsAsync, which handle resolution automatically.

Topic blpapi::ProviderSession::getTopic ( const Message & message )

Finds a previously created Topic object based on the specified message. The message must be one of the following types: TopicCreated, TopicActivated, TopicDeactivated, TopicSubscribed, TopicUnsubscribed, TopicRecap. If the message is not valid then invoking isValid() on the returned Topic will return false.

Topic blpapi::ProviderSession::createServiceStatusTopic ( const Service & service )

Creates a Service Status Topic which is to be used to provide service status. On success invoking isValid() on the returned Topic will return false.

void blpapi::ProviderSession::publish ( const Event & event )

Publish messages contained in the specified event.

void blpapi::ProviderSession::sendResponse	(	const Event &	event,
		bool	isPartialResponse = `false`
	)

Send the response event for previously received request

void blpapi::ProviderSession::createTopics	(	TopicList *	topicList,
		ResolveMode	resolveMode = `DONT_REGISTER_SERVICES`,
		Identity	providerIdentity = `Identity()`
	)

Creates the topics in the specified topicList and updates the topicList with the results of the creation process. If service needs to be registered, providerIdentity should be supplied. Once a call to this function returns, each entry in the topicList will have been updated with a new topic creation status.

Before createTopics() returns one or more RESOLUTION_STATUS events, zero or more SERVICE_STATUS events and one or more TOPIC_STATUS events are generated. If this is an asynchronous ProviderSession then these Events may be processed by the registered EventHandler before createTopics() has returned.

void blpapi::ProviderSession::createTopicsAsync	(	const TopicList &	topicList,
		ResolveMode	resolveMode = `DONT_REGISTER_SERVICES`,
		const Identity &	providerIdentity = `Identity()`
	)

Creates the topics in the specified topicList and updates the topicList with the results of the creation process. If service needs to be registered, providerIdentity should be supplied.

One or more RESOLUTION_STATUS events, zero or more SERVICE_STATUS events and one or more TOPIC_STATUS events are generated. If this is an asynchronous ProviderSession then these Events may be processed by the registered EventHandler before createTopics() has returned.

void blpapi::ProviderSession::deleteTopic ( const Topic & topic )

Remove one reference from the specified topic. If the number of times this function and terminateSubscriptionsOnTopic are called is the same as the number of times topic was created by createTopics, then topic is deleted: a TopicDeleted message is delivered, preceded by TopicDeactivated message (See "Topic Life Cycle", above, for additional details). The behavior of this function is undefined if topic has already been deleted. Further, the behavior is undefined if a provider attempts to publish a message on a deleted topic.

void blpapi::ProviderSession::deleteTopics ( const std::vector< Topic > & topics )

Delete each topic in the specified topics. See deleteTopic(const Topic&) for additional details.

void blpapi::ProviderSession::deleteTopics	(	const Topic *	topics,
		size_t	numTopics
	)

Delete the first numTopics elements of the specified topics array. See deleteTopic(const Topic&) for additional details.

void blpapi::ProviderSession::terminateSubscriptionsOnTopic	(	const Topic &	topic,
		const char *	message = `0`
	)

Delete the specified topic (See deleteTopic(const Topic&) for additional details). Furthermore, proactively terminate all current subscriptions on topic. The optionally specified message can be used to convey additional information to subscribers regarding the termination. This message is contained in the description of reason in a SubscriptionTerminated message.

void blpapi::ProviderSession::terminateSubscriptionsOnTopics	(	const std::vector< Topic > &	topics,
		const char *	message = `0`
	)

Terminate subscriptions on each topic in the specified topics. See terminateSubscriptionsOnTopic(const Topic&, const char* message) for additiona details.

void blpapi::ProviderSession::terminateSubscriptionsOnTopics	(	const Topic *	topics,
		size_t	numTopics,
		const char *	message = `0`
	)

Terminate subscriptions on the first numTopics topics in the specified topics. See terminateSubscriptionsOnTopic(const Topic&, const char* message) for additional details.

blpapi_ProviderSession_t* blpapi::ProviderSession::handle ( ) const

Return the handle to this provider session

bool blpapi::ProviderSession::flushPublishedEvents ( int timeoutMsecs )

Wait at most timeoutMsecs milliseconds for all the published events to be sent through the underlying channel. The method returns either as soon as all the published events have been sent out or when it has waited timeoutMs milliseconds. Return true if all the published events have been sent; false otherwise. The behavior is undefined unless the specified timeoutMsecs is a non-negative value. When timeoutMsecs is 0, the method checks if all the published events have been sent and returns without waiting.

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, or if the authentication mode is MANUAL for a user or user and application authentication, then an InvalidArgumentException is thrown.

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

Generate a token to be used for authorization, using the specified userId and ipAddress. If the authentication mode is not MANUAL, if the userId or ipAddress are not valid or if there's a problem obtaining the authentication information based on the authentication options in SessionOptions, 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 blpapi_providerEventHandlerAdapter	(	blpapi_Event_t *	event,
		blpapi_ProviderSession_t *	session,
		void *	userData
	)			`[friend]`

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

blpapi_providersession.h

blpapi::ProviderSession 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