Listening to Market Data

Events in the Handler

Once the Handler is started, it listens to a market data from the network, processes it (decodes messages, validates message order, updates order books) and invokes client code for further processing.

The Handler processes market data asynchronously and uses concept of events and event listeners to notify client code about a particular occasion like reception of security definition or direct book update.

Listening for a particular Event

For each event like Error Occurred Handler provides an interface (C++ class with pure virtual members) like OnixS::CME::MarketData::ErrorListener. Client code must implement this interface (C++ class) to be able to handle events of a particular type. Handler also exposes a member like OnixS::CME::MarketData::Handler::registerErrorListener which allows to associate an instance of the event handler with a appropriate event in bounds of a particular instance of the OnixS::CME::MarketData::Handler class.

Note

Associating listener for a particular event with an instance of the OnixS::CME::MarketData::Handler class must be performed while the Handler is in stopped stated. Once the Handler is started, changing listener-event associations is not allowed and may lead to unpredictable behavior as well as may cause unexpected errors.

Associating event listener with an instance of the OnixS::CME::MarketData::Handler class is also called subscribing to an event.

Primary High-level Events

There're multiple events exposed by the Handler. All events can be logically divided onto high- and low- level event sub-set. High-level events reflect various results of market data processing done by the Handler like Security Definition Received, Market Book Updated, and Trading occurred. Low-level events are designed for more control over data processing as well for more flexibility and described in different section of this documentation including Advanced Programming section.

Below table describes primary high-level events exposed by the Handler as well as depicts correspondence between events, interfaces for listeners and the Handler's members to subscribe to an event:

Event	Listener (C++ class) to be implemented	Handler's member to register listener	Description
Security Definition Received	OnixS::CME::MarketData::SecurityDefinitionListener	OnixS::CME::MarketData::Handler::registerSecurityDefinitionListener	Fired if a definition of a new security is received. Security definitions normally are received at the beginning of the Handler's execution and before any other high-level event like Book Updated event. Once a Handler receives definitions for all securities (instruments) available in a particular market data channel, no more events of this type will be fired. Handler may start firing events of this type again in case of inability to recover from error occurred during market data processing.
Security Status Changed	OnixS::CME::MarketData::SecurityStatusListener	OnixS::CME::MarketData::Handler::registerSecurityStatusListener	Fired if the remote system reports about changes in a status of a particular security. An example of such change is update of upper price or trading status.
Direct Book Updated	OnixS::CME::MarketData::DirectBookUpdateListener	OnixS::CME::MarketData::Handler::registerDirectBookUpdateListener	Occurs when direct book of a particular security is updated.
Implied Book Updated	OnixS::CME::MarketData::ImpliedBookUpdateListener	OnixS::CME::MarketData::Handler::registerImpliedBookUpdateListener	Occurs when implied book of a particular security is updated.
Consolidated Book Updated	OnixS::CME::MarketData::ConsolidatedBookUpdateListener	OnixS::CME::MarketData::Handler::registerConsolidatedBookUpdateListener	Occurs when consolidated book of a particular security is updated.
Trade Information Received	OnixS::CME::MarketData::Listener	OnixS::CME::MarketData::Handler::registerTradeListener	Occurs if trade information is received for a particular security. Trade attributes are collected into an instance of OnixS::CME::MarketData::Trade class which is supplied as a parameter to the listener by the Handler.
Security Status Received	OnixS::CME::MarketData::SecurityStatusListener	OnixS::CME::MarketData::Handler::registerSecurityStatusListener	Occurs if security status message (MsgType=f) is received for a particular security. Status attributes attributes are encapsulated into an instance of OnixS::CME::MarketData::SecurityStatus class which is supplied as a parameter to the listener by the Handler.
Statistics Changed	OnixS::CME::MarketData::StatisticsListener	OnixS::CME::MarketData::Handler::registerStatisticsListener	Occurs when attributes like opening or closing price for a particular security is changed.
News Received	OnixS::CME::MarketData::NewsListener	OnixS::CME::MarketData::Handler::registerNewsListener	Fired when the system spreads arbitrary news to the Handler. Headline and full text of the news are exposed via an instance of OnixS::CME::MarketData::News class.

Example

Following sample demonstrates how to listen to notifications about security definition reception:

class MyListener : SecurityDefinitionListener
{
public:
    MyListener(Handler& handler)
    {
        handler.registerSecurityDefinitionListener(this);
    }

private:
    virtual void onSecurityDefinition(const SecurityDefinition& definition, const ChannelId& channelId)
    {
        cout << channelId << ": " << definition.toString() << endl;
    }

    virtual void onSecurityDefinitionDeleted(const SecurityId& securityId, const ChannelId& channelId)
    {
        cout << channelId << ": " << "Definition deleted [securityId=" << securityId << "]." << endl;
    }

    virtual void onSecurityDefinitionsRecoveryStarted(const ChannelId&  channelId) 
    {
        cout << channelId << ": Starting processing security definitions." << endl;
    }

    virtual void onSecurityDefinitionsRecoveryFinished(const ChannelId&  channelId) 
    {
        cout << channelId << ": Finished processing security definitions." << endl;
    }
};

...

HandlerSettings handlerSettings;

// HandlerSettings initialization goes here.
...

Handler handler(handlerSettings);

MyListener listener(handler);

handler.start();

...