All Handler classes are encapsulated into the OnixS::CboeCFE::Trading::BOE namespace. Header files are collected in the master
"OnixS/CboeCFE/Trading/BOE.h" header file.
The typical way of using the Handler is as follows:
The OnixS::CboeCFE::Trading::BOE::Handler constructor accepts an instance of the OnixS::CboeCFE::Trading::BOE::HandlerSettings class which defines values for various parameters that affect Handler's behavior. The section below describes the most important parameters.
By default,the Handler logs all important aspects of its activity while processing market data. Therefore, it must know where on local file system it can store this kind of information. The OnixS::CboeCFE::Trading::BOE::HandlerSettings::logDirectory parameter value must be defined to point the Handler in which directory it can place its log files.
The Handler needs a license for successful execution. If the Handler is not able to find a valid License, it will throw an exception at the initialization stage.
The OnixS::CboeCFE::Trading::BOE::HandlerSettings structure exposes the OnixS::CboeCFE::Trading::BOE::HandlerSettings::licenseDirectory parameter which allows to instruct the Handler where to look for a valid license. By default, the Handler looks for a license in the current directory for the application which uses the Handler.
Following example demonstrates how to setup primary settings for the Handler:
Before sending application messages an authorized connection must be established. This assumes providing username, password along with host and port and exchange protocol setup.
Most of the fields of the messages sent by the exchange are optional. The setup assumes choosing the fields the used want to recieve.
Each incoming message has a correspondent class to select fields the user interested in. For example, OrderAcknowledgment has correspondent OrderAcknowledgmentReturnFields class. To receive 'capacity' (Corresponds to OrderCapacity(47) in CFE FIX) field OrderAcknowledgmentReturnFields::enableCapacity() must be invoked. Then the object of OrderAcknowledgmentReturnFields must be passed to Handler::connect call.
After this setup, OrderAcknowledgment messages will have the following form:
The other messages can be configured the same way.
Being C++ class library, the Handler uses exceptions to Cashrt about error occurred while performing certain action. For example, the Handler will raise regular exception to Cashrt about inability to find actual license for the product. However, the Handler processes market data asynchronously, therefore it is not able to Cashrt about any further errors since market data processing is started. For this reason, the Handler exposes the OnixS::CboeCFE::Trading::BOE::ErrorListener interface and the OnixS::CboeCFE::Trading::BOE::Handler::registerErrorListener member to be able to subscribe and handle errors.
Once instance of OnixS::CboeCFE::Trading::BOE::ErrorListener is assigned to the Handler, it will invoke the OnixS::CboeCFE::Trading::BOE::ErrorListener::onError member each time error occurs. The OnixS::CboeCFE::Trading::BOE::ErrorListener::onError member has several incoming parameters one of which defines human-readable explanation (description) of the error.
Following sample demonstrates how to receive error notifications:
Miscellaneous non-critical issues may occur while the Handler is being executed. The Handler will handle such issues by itself, thus no special handling is required for such cases. However, sometimes it's reasonable to be notified about such events. For this reason, a handler exposes the OnixS::CboeCFE::Trading::BOE::WarningListener class and will invoke its OnixS::CboeCFE::Trading::BOE::WarningListener::onWarning member each time a non-critical issue will take place.
Once the Handler is started, it listens to a message from the Mts Cash/SDP message flow, processes it and invokes client code for further processing.
The Handler processes messages asynchronously and uses concept of events and event listeners to notify client code about a particular occasion like reception of record.
For each event like Error Occurred Handler provides an interface (C++ class with pure virtual members) like OnixS::CboeCFE::Trading::BOE::ErrorListener. Client code must implement this interface (C++ class) to be able to handle events of a particular type. The Handler also exposes a member like OnixS::CboeCFE::Trading::BOE::Handler::registerErrorListener which allows to associate an instance of the event handler with an appropriate event in bounds of a particular instance of the OnixS::CboeCFE::Trading::BOE::Handler class.
Associating event listener with an instance of the OnixS::CboeCFE::Trading::BOE::Handler class is also called subscribing to an event.