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.

Return type:

None

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.

cancel(correlationId)

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

Parameters:

correlationId (Union[CorrelationId, Sequence[CorrelationId], None]) – 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.

Return type:

None

Note

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

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.

Return type:

None

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.

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.

isValid()

Returns: True if this class holds a handle and the handle is not None.

Return type:

bool

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

sessionName()
Return type:

str

Returns:

The session name.

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.