B2BITS FIX Antenna C++  2.27.0
Basic Concepts

Table of Contents

Main components

The main FIX Antenna components are:

Engine description

The engine is represented by the Engine::FixEngine class. This class is responsible for:

Engine initialization is performed using the void Engine::FixEngine::init() method. This method must be called before any other FIX Antenna methods. At the end of the process void Engine::FixEngine::destroy() method must be called to deallocate the consumed resources.

For example:

#include <iostream>
#include <B2BITS_V12.h>
using namespace std;
int main(int argc, char* argv[]) {
try {
// initialization
// ... - main functionality
// destruction
}
catch(const Utils::Exception& ex) {
cout << "EXCEPTION: " << ex.what() << endl;
}
return 0;
}

The Engine::FixEngine class, as well as several other FIX Antenna C++ API classes, implements the Singleton Design Pattern. Therefore you should, first of all, get a pointer to the instance of the class, using the FixEngine* Engine::FixEngine::singleton() static method to access non-static methods of the class.

For example:

FixEngine::singleton()->createSession(...)

Sessions Manager

The SessionsManager manages the creation of unregisted acceptor sessions. When CreateUnregisteredAcceptorSession is set to true engine accepts all incoming logons and creates sessions-acceptors. It is possible though to implement custom logic and introduce more sophisticated criteria of accepting such sessions. To do this you need to create and register your own instance of SessionsManager.

Create a class derived from the Engine::SessionsManager class and override the Engine::SessionsManager::onUnregisteredAcceptor() method to control acceptor session creation. Return "true" if you agree with the creation of unregistered acceptor; otherwise return "false".

Use Engine::FixEngine::registerSessionsManager() method to register custom session manager. Only one Sessions Manager can be registered to the FIX Engine.

For example:

class SsnManager : public Engine::SessionsManager{
public:
virtual bool onUnregisteredAcceptor(Session* pSn, const FIXMessage& logonMsg) {
clog << "Incoming logon: " << *logonMsg.toString() << endl;
return true;
}
};
// The FixEngine initialization
FixEngine::init("engine.properties");
// create and register SessionsManager
SsnManager *g_mySM = new SsnManager();
FixEngine::singleton()->registerSessionsManager(g_mySM);
...
// unregister and destroy SessionsManager
FixEngine::singleton()->registerSessionsManager(NULL);
delete g_mySM;
// destruct FixEngine
FixEngine::destroy();
Warning
Do not delete the registered sessions’ manager until you unregister it.

Session description

The FIX session is represented by the Engine::Session class. This class is responsible for:

In earlier versions of FIX Antenna (2.10.14 and earlier) Session object could be uniquely identified by SenderCompId/TargetCompId pair. Starting from version 2.10.15.5 extra string identifier - SessionQualifier has been introduced in addition to SenderCompId/TargetCompId pair. The idea is to give user ability to create several sessions with the same SenderCompId and TargetCompId and to give ability to address these sessions by unique ID. See Session identifier for more details.

Each session encapsulates message storage that is used to store the sent and received messages. There are two types of storages:

Unregistered acceptors

When engine receives FIX logon message it extracts SenderCompID and TargetCompID fields from the message and tries to find previously created acceptor with corresponding session ID (i.e. session SenderCompID equal to TargetCompID extracted from message and session TargetCompID equal to the SenderCompID extracted from messages). Refer to the FIX Session Acceptor for more information about how to create session acceptor. If engine cannot find corresponding acceptor the incoming logon is declined and connection is not established.

Engine though can also work in "trusted mode" i.e. if corresponding session acceptor cannot be found then session is created automatically. To enable this mode set CreateUnregisteredAcceptorSession property to "true" (refer to the section Common parameters for more details about property).

Application description

The Application class is responsible for:

Create a new class derived from the Application class and override the Application::process method in this class to process incoming messages. Then pass the instance of your class to the session to start receiving incoming messages.

Engine delivers incoming messages to the Application by calling Application::process method and analyzing its return value to make sure that incoming message was processed and Application is ready to process next incoming message.

If the Engine::Application::process method does not return "true" (i.e. returns "false" or throws an exception), the engine passes the same incoming message to the Application::process again and again until either Application::process returns "true" or number of attempts is exceeded (DelayedProcessing.MaxDeliveryTries, refer to Common parameters for more information). The interval between attempts is specified by property DelayedProcessing.DeliveryTriesInterval (refer to Common parameters for more information). If the number of unsuccessful attempts exceeds the MaxDeliveryTries, a Logout message with the reason "Application is not available" is sent to the counterparty and session is closed.

Other useful methods to override are: onLogonEvent, onLogoutEvent, onSequenceGapEvent, onSessionLevelRejectEvent, etc. These are the call-back methods called to notify about the corresponding session-level events. Note that all pure virtual methods of Application must be overridden (implementation can be just empty body).

The Engine::Application::process method is called only when application-level message is received. All session-level messages (Heartbeats, Test Requests, Resend Requests, etc.) are handled by FIX Antenna. However you can modify default behavior overriding call-back methods in Application and providing your own logic.

Note
if you need to keep FIX message for future processing create a copy of the message and save a copy instead of saving original message (refer to the Engine::FIXMsgProcessor::clone method).

Below is an example of custom implementation of Application interface:

class Appl : public Engine::Application{
public:
virtual bool process(const FIXMessage & aMsg, const Engine::Session& aSn) {
clog << "aMsg: " << *aMsg.toString() << endl;
return true;
}
virtual void onLogonEvent(const LogonEvent* apEvent, const Session& aSn) {
clog << "LogonEvent, the Logon message was received: " << apEvent->m_pLogonMsg->toString() << endl;
}
virtual void onLogoutEvent(const LogoutEvent* apEvent, const Session& aSn) {
clog << "LogoutEvent, the Logout message was received: " << apEvent->m_pLogoutMsg->toString() << endl;
}
virtual void onSequenceGapEvent(const SequenceGapEvent* apEvent, const Session& aSn) {
clog << "SequenceGapEvent" << endl;
}
virtual void onSessionLevelRejectEvent(const SessionLevelRejectEvent* apEvent, const Session& aSn) {
clog << "SessionLevelRejectEvent" << endl;
}
virtual void onMsgRejectEvent(const MsgRejectEvent* event, const Session& sn){
clog << "MsgRejectEvent" << endl;
}
virtual void onResendRequestEvent(const ResendRequestEvent &,const Session &) {
clog << "ResendRequestEvent" << endl;
}
virtual void onNewStateEvent(const NewStateEvent &,const Session &) {
clog << "NewStateEvent" << endl;
}
virtual void onUnableToRouteMessage(const UnableToRouteMessageEvent &,const Session &) {
clog << "UnableToRouteMessage" << endl;
}
virtual bool onResend(const FIXMessage &,const Session &) {
clog << "Resend" << endl;
return true;
}
virtual void onHeartbeatWithTestReqIDEvent(const HeartbeatWithTestReqIDEvent &,const Session &) {
clog << "HeartbeatWithTestReqIDEvent" << endl;
}
};
Note
It is not recommended to put lock inside the Application::process, synchronize different call-back methods unless you are absolutely confident in what you are doing. Also it is not recommended to perform time-consuming operations inside Application::process as it blocks receiving following messages.
If a pointer to the same Application is sent to several sessions, being established, synchronize the Application::process() method.
Warning
Do not delete the registered Application until you unregister it.

Message description

The FIX message (specified by the FIX protocol) is represented by the Engine::FIXMessage class.

The Engine::FIXMessage class provides the following functionality:

Repeating Groups description

Please read the FIX Protocol explanation of the Repeating group first (refer to the section About FIX messages).

The FIX message may contain repeating groups. Each group contains:

Repeating groups are usually referred by the leading tag.

To add new group to the message you simply should add leading field to the message. In the result the new group will be added with the number of entries according to the value of leading field.

To access fields inside a repeating group you should

To resize group simply modify the value of leading tag. Pay attention that this operation re-creates the group so you should populate values again.

To remove group simply remove leading tag from the message.