blpapi_providersession Component

Provide a session that can be used for providing services. More...

Namespaces
namespace	blpapi

Detailed Description

Provide a session that can be used for providing services.

Outline

Classes:

blpapi::ProviderSession	Session with providing(publishing) services.
blpapi::ProviderEventHandler	Event handler for ProviderSession
blpapi::ServiceRegistrationOptions	Container holding registration options.

Description:: ProviderSession inherits from AbstractSession. In addition to AbstractSession functionality, ProviderSession provides functions that are needed to support publishing like registerService, createTopics and publish.

Topic Life Cycle:: A provider wishing to publish subscription data must explicitly open each topic on which they publish using ProviderSession::createTopics (or ProviderSession::createTopicsAsync). Creating a topic prepares the distribution and caching infrastructure for new data associated with the topic's resolved identifier. (Note that several different topics could resolve to the same ID.) Independent of a topic's creation status is its subscription status, i.e. whether there are subscribers ready to receive the data published. A topic that is both created and subscribed is activated.

: There are two models for managing topic creation: broadcast and interactive. Broadcast publishers proactively call ProviderSession::createTopic* for each topic on which they intend to publish, while interactive publishers wait to receive a TopicSubscribed message (within an Event of type Event::TOPIC_STATUS) before calling ProviderSession::createTopic* in response. Topics are resolved before they are created---it is possible that multiple different topic strings will map to the same underlying topic. See below for the behavior of the SDK when the same topic is created multiple times.

: For applications using multiple broadcast publishers with the same priority for the same service in the same group, note that successfully calling createTopic* in a publisher does not mean that the topic will be subscribed or activated as the infrastructure can select a different publisher for the subscription. That is, there's no guarantee of TopicSubscribed and TopicActivated events following TopicCreated. All broadcast publisher instances in the same publisher group should call createTopic* for the same topics and be able to handle TopicSubscribed before TopicCreated is received.

: After ProviderSession::createTopic* is called, the publisher will receive a TopicCreated message (within an Event::TOPIC_STATUS event), and when there is at least one subscriber to the topic the publisher will then receive a TopicActivated message (also within an Event::TOPIC_STATUS event). As subscribers come and go, additional TopicSubscribed, TopicActivated, TopicUnsubscribed, and TopicDeactivated messages may be received by the publisher. A Topic object can be retrieved from each of these messages using the ProviderSession::getTopic method, and this object can be used for subsequent calls to EventFormatter::appendMessage and ProviderSession::deleteTopic. In the case that the same resolved topic is created multiple times by a publisher using different names, it is unspecified which of those names will be returned by Message::topicName for these (or other) messages.

: If a publisher no longer intends to publish data on a topic, it can call ProviderSession::deleteTopic* to free the internal caching and distribution resources associated with the topic. When a resolved topic has been deleted the same number of times that it has been created, a TopicDeleted message will be delivered, preceded by TopicDeactivated message. No further messages can be published on a deleted topic. Existing subscriptions are not affected and the publisher can call ProviderSession::createTopic* to recreate the topic and proceed publishing.

: If a topic is no longer supported, the publisher can call ProviderSession::terminateSubscriptionsOnTopics to terminate all existing subscriptions and delete the topics. Subscribers will be delivered a SubscriptionTerminated message indicating that the subscription has been terminated.

: Deregistering a service forces unsubscribes and deletes all topics associated with that service.

: Note that TopicActivated and TopicDeactivated messages are entirely redundant with TopicCreated, TopicSubscribed, TopicDeleted, and TopicUnsubscribed messages, and are provided only for the convenience of publishers that do not maintain per-topic state.