blpapi.ProviderSession

class blpapi.ProviderSession(options=None, eventHandler=None, eventDispatcher=None)

Bases: AbstractSession

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 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 also can get requests from the event queue and send back responses.

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.

AUTO_REGISTER_SERVICES = 1

DONT_REGISTER_SERVICES = 0

__init__(options=None, eventHandler=None, eventDispatcher=None)

Constructor.

Parameters

options – Options used to construct the sessions
eventHandler – Handler for the events generated by this session
eventDispatcher – Dispatcher for the events generated by this session

Raises

InvalidArgumentException – If eventHandler is None and the eventDispatcher is not None

Construct a Session using the optionally specified ‘options’, the optionally specified ‘eventHandler’ and the optionally specified ‘eventDispatcher’. See SessionOptions for details on what can be specified in the options.

If eventHandler is not None then this Session will operate in asynchronous mode, otherwise the Session will operate in synchronous mode. If supplied, eventHandler is a callable object that takes two arguments: received event and related session.

If eventDispatcher is None 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.

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.

activateSubServiceCodeRange(serviceName, begin, end, priority)

Parameters

serviceName (str) – Name of the service
begin (int) – Start of sub-service code range
end (int) – End of sub-service code range
priority (int) – Priority with which to receive subscriptions

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.

Note

The behavior of this function is undefined unless service has already been successfully registered, 0 <= begin <= end < (1 << 24), and priority is non-negative.

Return type: None

cancel(correlationId)

Cancel request(s) with a single correlationId or a list.

Parameters: correlationId (Union[CorrelationId, Sequence[CorrelationId]]) – Correlation id(s) associated with the request(s) to cancel

For all specified correlationId values that identify an ongoing request 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.

Return type: None

createIdentity()

Create an Identity which is valid but has not been authorized.

Returns: Identity which is valid but has not been authorized
Return type: Identity

createServiceStatusTopic(service)

Create a Service Status Topic which is to be used to provide service status.

Parameters: service – Service for which to create the topic
Returns: A service status topic

On success invoking isValid() on the returned Topic will return False.

createTopics(topicList, resolveMode=0, identity=None)

Create the topics in the specified topicList.

Parameters

topicList – List of topics to create
resolveMode – Mode to use for topic resolution
identity – Identity to use for authorization

Create the topics in the specified topicList, which must be an object of type TopicList, and update topicList with the results of the creation process. If service needs to be registered, identity 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.

When identity is not provided, the session identity will be used if it has been authorized.

createTopicsAsync(topicList, resolveMode=0, identity=None)

Create the topics in the specified topicList.

Parameters

topicList – List of topics to create
resolveMode – Mode to use for topic resolution
identity – Identity to use for authorization

Create the topics in the specified topicList, which must be an object of type TopicList, and update topicList with the results of the creation process. If service needs to be registered, identity 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.

When identity is not provided, the session identity will be used if it has been authorized.

deactivateSubServiceCodeRange(serviceName, begin, end)

Parameters

serviceName (str) – Name of the service
begin (int) – Start of sub-service code range
end (int) – End of sub-service code range

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.

Note

The behavior of this function is undefined unless service has already been successfully registered and 0 <= begin <= end < (1 << 24).

Return type: None

deleteTopic(topic)

Remove one reference from the specified ‘topic’.

Parameters: topic (Topic) – Topic to remove the reference from

If this function has been called the same number of times that topic was created by createTopics, then topic is deleted: a TopicDeleted message is delivered, preceded by TopicUnsubscribed and TopicDeactivated if topic was subscribed.

Note

The behavior of this function is undefined if topic has already been deleted the same number of times that it has been created. Further, the behavior is undefined if a provider attempts to publish a message on a deleted topic.

Return type: None

deleteTopics(topics)

Delete each topic in the specified topics container.

Parameters: deleteTopics – Topics to delete

See deleteTopic() above for additional details.

Return type: None

deregisterService(serviceName)

De-register the service, including all registered parts.

Parameters: serviceName (str) – Service to de-register
Return type: bool
Returns: False if the service is not registered nor in pending registration, True otherwise.

The identity in the service registration is reused to verify permissions for deregistration. 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 ~Event.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.

destroy()

Destroy the handle using stored dtor

Return type: None

flushPublishedEvents(timeoutMsecs)

Wait at most timeoutMsecs milliseconds for all the published events to be sent through the underlying channel.

Parameters: timeoutMsecs (int) – Timeout threshold in milliseconds
Return type: bool
Returns: True if all the published events have been sent, False otherwise

The method returns either as soon as all the published events have been sent out or when it has waited timeoutMsecs milliseconds. 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.

generateAuthorizedIdentity(authOptions, correlationId=None)

Generates an authorized Identity with the specified authOptions and correlationId.

Parameters

authOptions – Used to generate the Identity.
correlationId – Optional. Will identify the messages associated with the generated Identity.

Returns

Identifies the aforementioned events and the generated Identity.

Return type

CorrelationId

If this is an asynchronous session then an Event may be delivered to the registered EventHandler before generateAuthorizedIdentity() has returned.

One or more Event.AUTHORIZATION_STATUS events, zero or more Event.TOKEN_STATUS events, and zero or more Event.SERVICE_STATUS events are generated.

The behavior is undefined if either authOptions or correlationId is None.

generateToken(correlationId=None, eventQueue=None, authId=None, ipAddress=None)

Generate a token to be used for authorization.

Parameters

correlationId – Correlation id to be associated with the request
eventQueue – Event queue on which to receive Events related to this request
authId – The id used for authentication
ipAddress – IP of the machine used for authentication

Returns

The correlation id used to identify the Events generated as a result of this call

Return type

CorrelationId

Raises

InvalidArgumentException – If the authentication options in SessionOptions or the arguments to the function are invalid.

The authId and ipAddress must be provided together and can only be provided if the authentication mode is MANUAL.

getAuthorizedIdentity(correlationId=None)

Returns the authorized Identity associated with correlationId. If correlationId is not given, returns the session identity.

Parameters: correlationId (Optional[CorrelationId]) – Optional. Associated with an Identity.
Returns: the Identity associated with correlationId.
Return type: Identity
Raises: NotFoundException – If there is no Identity associated with correlationId, if the associated Identity is not authorized, or if correlationId is not given and the session identity is not authorized.

getService(serviceName)

Return a Service object representing the service.

Parameters: serviceName (str) – Name of the service to retrieve
Returns: Service identified by the service name
Return type: Service
Raises: InvalidStateException – If the service identified by the specified serviceName is not open already

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

getTopic(message)

Find a previously created Topic based on the message.

Parameters: message – Message to get the topic from
Returns: The topic the message was published on

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.

nextEvent(timeout=0)

Parameters: timeout (int) – Timeout threshold in milliseconds
Return type: Event
Returns: Next available event for this session
Raises: InvalidStateException – If invoked on a session created in asynchronous mode

If there is no Event available this will block for up to the specified timeout milliseconds for an Event to arrive. A value of 0 for timeout (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 TIMEOUT.

openService(serviceName)

Open the service identified by the specified serviceName.

Parameters: serviceName (str) – Name of the service
Return type: bool
Returns: True if the service is opened successfully, False otherwise.

Attempt to open the service identified by the specified serviceName 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 serviceName must contain a fully qualified service name. That is, it must be of the form //<namespace>/<service-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.

openServiceAsync(serviceName, correlationId=None)

Begin the process to open the service and return immediately.

Parameters

serviceName (str) – Name of the service
correlationId (Optional[CorrelationId]) – Correlation id to associate with events generated as a result of this call

Returns

The correlation id used to identify the Events generated as a result of this call

Return type

CorrelationId

Begin the process to open the service identified by the specified serviceName and return immediately. The optional specified correlationId is used to track Events generated as a result of this call.

The serviceName must contain a fully qualified service name. That is, it must be of the form //<namespace>/<service-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.

publish(event)

Publish the specified event.

Parameters: event (Event) – Event to publish
Return type: None

registerService(uri, identity=None, options=None)

Attempt to register the service and block until it is done.

Parameters

uri – Name of the service
identity – Identity used to verify permissions to provide the service being registered
options – Options used to register the service

Returns

True if the service registered successfully, else False

Attempt to register the service identified by the specified uri and block until the service is either registered successfully or has failed to be registered. The optionally specified identity is used to verify permissions to provide the service being registered. The optionally specified options is used to specify the group ID and service priority of the service being registered.

The uri must begin with a full qualified service name. That is it must begin with //<namespace>/<service-name>[/]. Any portion of the uri after the service name is ignored.

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

When identity is not provided, the session identity will be used if it has been authorized.

registerServiceAsync(uri, identity=None, correlationId=None, options=None)

Begin the process of registering the service immediately.

Parameters

uri – Name of the service
identity – Identity used to verify permissions to provide the service being registered
correlationId – Correlation id to associate with this operation
options – Options used to register the service

Returns

Correlation id associated with events generated by this operation

Begin the process of registering the service identified by the specified uri and return immediately. The optionally specified identity is used to verify permissions to provide the service being registered. The optionally specified correlationId is used to track Events generated as a result of this call. The actual correlationId that will identify Events generated as a result of this call is returned. The optionally specified options is used to specify the group ID and service priority of the service being registered.

The uri must begin with a full qualified service name. That is it must begin with //<namespace>/<service-name>[/]. Any portion of the uri after the service name is ignored.

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.

When identity is not provided, the session identity will be used if it has been authorized.

resolve(resolutionList, resolveMode=0, identity=None)

Resolve the topics in the specified resolutionList.

Parameters

resolutionList – List of topics to resolve
resolveMode – Mode to resolve in
identity – Identity used for authorization

Resolve the topics in the specified resolutionList, which must be an object of type ResolutionList, and update 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 identity 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 resolve() returns each entry in the resolutionList will have been updated with a new status.

Before resolve() 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.

When identity is not provided, the session identity will be used if it has been authorized.

resolveAsync(resolutionList, resolveMode=0, identity=None)

Begin the resolution of the topics in the specified list.

Parameters

resolutionList – List of topics to resolve
resolveMode – Mode to resolve in
identity – Identity used for authorization

Begin the resolution of the topics in the specified resolutionList, which must be an object of type 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 identity 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 resolveAsync() returns. If AUTO_REGISTER_SERVICES is specified SERVICE_STATUS events may also be generated before or after resolveAsync() returns.

When identity is not provided, the session identity will be used if it has been authorized.

sendAuthorizationRequest(request, identity, correlationId=None, eventQueue=None)

Send the specified authorizationRequest.

Parameters

request – Authorization request to send
identity – Identity to update with the results
correlationId – Correlation id to associate with the request
eventQueue – Event queue on which the events related to this request will arrive

Returns

The correlation id used to identify the Events generated as a result of this call

Return type

CorrelationId

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 and must not be the session identity.

sendResponse(event, isPartialResponse=False)

Send the response event for previously received request.

Parameters

event (Event) – Response event to send
isPartialResponse (bool) – Whether the response is partial or not

Return type

None

start()

Start this Session in synchronous mode.

Return type: bool
Returns: True if the Session started successfully, False otherwise.

Attempt to start this Session and block until the Session has started or failed to start. Before start() returns a SESSION_STATUS Event is generated. A Session may only be started once.

startAsync()

Start this Session in asynchronous mode.

Return type: bool
Returns: True if the process to start a Session began successfully, False otherwise.

Attempt to begin the process to start this Session. 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. The SESSION_STATUS Event may be processed by the registered eventHandler before startAsync() has returned. A Session may only be started once.

stop()

Stop operation of this Session and wait until it stops.

Return type: bool
Returns: True if the Session stopped successfully, False otherwise.

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 this call generates). Once this returns no further callbacks to eventHandlers will occur. If stop() is called from within an eventHandler callback it is silently converted to a stopAsync() in order to prevent deadlock. Once a Session has been stopped it can only be destroyed.

stopAsync()

Begin the process to stop this Session and return immediately.

Return type: bool
Returns: True if the process to stop a Session began successfully, False otherwise.

The application must monitor events for a SESSION_STATUS Event which will be generated once the Session has been stopped. After this SESSION_STATUS Event no further callbacks to eventHandlers will occur. Once a Session has been stopped it can only be destroyed.

terminateSubscriptionsOnTopic(topic, message=None)

Delete the specified topic (See deleteTopic() for additional details).

Parameters

topic – Topic to delete
message – Message to convey additional information to subscribers regarding the termination

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.

terminateSubscriptionsOnTopics(topics, message=None)

Terminate subscriptions on the specified topics.

Parameters

topics – Topics to delete
message – Message to convey additional information to subscribers regarding the termination

See terminateSubscriptionsOnTopic() for additional details.

tryNextEvent()

Return type: Optional[Event]
Returns: Next available event for this session

If there are Events available for the session, return the next Event If there is no event available for the Session, return None. This method never blocks.