Component blpapi_subscriptionlist

Namespaces
namespace	BloombergLP
namespace	BloombergLP::blpapi

Classes
class	SubscriptionList

Detailed Description

Purpose:

Provide a list of subscriptions.

Classes:

blpapi::SubscriptionList

Represents a list of subscriptions.

Description:

This component provides a structure to hold the data used (and returned) by the Session::subscribe, Session::resubscribe, and Session::unsubscribe methods. This structure comprises a list in which each list entry contains two primary fields: a CorrelationId associated with the subscription, and a string, called a subscription string, describing the data to be delivered as a part of the subscription.

Structure of Subscription String:

The simplest form of a subscription string is a fully qualified subscription string, which has the following structure:

"//blp/mktdata/ticker/IBM US Equity?fields=BID,ASK&interval=2"
 \-----------/\------/\-----------/\------------------------/
       |          |         |                  |
    Service    Prefix   Instrument           Suffix

Such a fully-qualified string is composed of:

• Service Identifier: a string matching the expression ^//[-_.a-zA-Z0-9]+/[-_.a-zA-Z0-9]+\$, e.g. //blp/mktdata. See blpapi_abstractsession for further details.
• Prefix: a string matching the expression /([-_.a-zA-Z0-9]+/)?, often used as a symbology identifier. Common examples include /ticker/ and /cusip/. Not all services make use of prefixes. Note than an "empty" topic prefix consists of the string "/", so the topic prefix always separates the service string from the instrument string.
• Instrument: a non-empty string that does not contain the character ? (i.e. a string matching [^?]+) e.g. "IBM US Equity", or "SPX Index". The service, prefix, and instrument together uniquely identify a source for subscription data.
• Suffix: a suffix contains a question mark followed by a list of options which can affect the content delivery. The format of these options is service specific, but they generally follow URI query string conventions: a sequence of "key=value" pairs separated by "&" characters. Further, many common services follow the convention that the value given for the fields key is formatted as a comma-separated list of field names. BLPAPI provides several convenience functions to assist in formatting subscription strings for services that make use of these conventions; see the SubscriptionList::add methods for details.

Subscription strings need not be fully qualified: BLPAPI allows the service and prefix to be omitted from subscription strings, and automatically qualifies these strings using the default subscription service and default topic prefix from SessionOptions.

Qualifying Subscription Strings:

The subscription strings passed to Session::subscribe and Session::resubscribe are automatically qualified if the service identifier is missing (i.e. if the subscription string does not start with "//"). The subscription parameters (i.e. the optional part after instrument identifier) are never modified. The rules for qualifying the subscription string are:

• If the subscription string begins with // then it is assumed to be a a fully qualified subscription string including service identifier, prefix, and instrument. In this case the string will not be modified and session options defaults have no affect on the subscription.
• If the subscription string begins with a / and the second character is not /, then the string is assumed to begin with the topic prefix, but no service identifier. In this case the string is qualified by prepending the SessionOptions::defaultSubscriptionService() to the specified string.
• If the subscription string does not begin with a / it is assumed to begin with an instrument identifier. In this case the string is qualified by prepending the SessionOptions::defaultSubscriptionService() followed by SessionOptions::defaultTopicPrefix() to the specified string. If the defaultTopicPrefix is empty or null, then the prefix used is /. Otherwise (in the case of a nontrivial prefix) if the separator / is not specified at the beginning or the end of the defaultTopicPrefix, then it will be added.

Use of SubscriptionList:

A SubscriptionList is used when calling Session::subscribe(), Session::resubscribe() and Session::unsubscribe(). The entries can be constructed in a variety of ways.

The two important elements when creating a subscription are:

Subscription String: A subscription string represents a topic whose updates user is interested in. A subscription string follows the structure specified above.

CorrelationId: the unique identifier to tag all data associated with this subscription.

The following table describes how various operations use the above elements:

+----------------------------------------------------------------------+
| OPERATION   |  SUBSCRIPTION STRING  |       CORRELATION ID           |
|-------------|-----------------------+--------------------------------|
| 'subscribe' |Used to specify the    |Identifier for the subscription.|
|             |topic to subscribe to. |If uninitialized correlationid  |
|             |                       |was specified an internally     |
|             |                       |generated correlationId will be |
|             |                       |set for the subscription.       |
|-------------+-----------------------+--------------------------------|
|'resubscribe'|Used to specify the new|Identifier of the subscription  |
|             |topic to which the     |which needs to be modified.     |
|             |subscription should be |                                |
|             |modified to.           |                                |
|-------------+-----------------------+--------------------------------|
|'unsubscribe'|        NOT USED       |Identifier of the subscription  |
|             |                       |which needs to be canceled.     |
+----------------------------------------------------------------------+