Home » Products » FF.FIX Engine » FF.FIX Engine Knowledgebase » FIX Session Handler

FIX Session Callback Handler

FF.FIX Engine contains many FIX session callback handler routines. These routines are invoked as callbacks in response to specific events during FIX sessions. Your Initiator or Acceptor application implementation includes a callback handler. On occurrence of a specific event, the Initiator or Acceptor service notifies the callback handler about it. The callback handler then interacts with the application to retrieve the specific information and take suitable action. As a FIX developer, you need to implement a callback handler and build your business logic based on the callback methods in the callback handler.

Available callback handler classes

You can use the following base callback handler classes for your FF.FIX Engine based applications:

  • FixSessionHandler:
    • Namespace: FF.Fix
    • Description: This class serves as the base class for Initiator and Acceptor callback handlers. Its methods are available to both Initiator and Acceptor applications.
  • FixInitiatorHandler:
    • Namespace: FF.Fix.Initiator
    • Description: This class is derived from the FixSessionHandler class. It deals with only the Initiator-specific events. Its methods are available to Initiator applications only.
  • FixAcceptorHandler:
    • Namespace: FF.Fix.Acceptor
    • Description: This class is derived from the FixSessionHandler class. It deals with only the Acceptor-specific events. Its methods are available to Acceptor applications only.

The following diagram presents the hierarchy of these classes.

Common callback methods for Initiator and Acceptor applications

The following callback methods are available for use in your Acceptor and Initiator applications. They are common to both, the FixInitiatorHandler and the FixAcceptorHandler classes.

  1. OnConnectionBreak
Syntax: public abstract void OnConnectionBreak(FixSession fixSession, string failReason)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • failReason: The text message that explains the reason for the connection failure.
Description:

This callback method is invoked whenever the counterparty associated with the fixSession object abruptly disconnects the connection, usually the socket connection.
  1. OnSessionStateChanged
Syntax: public virtual void OnSessionStateChanged(FixSession fixSession, eSessionState sessionState)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • sessionState: The latest state of the FixSession.
Description: This callback method is invoked whenever the state of a FIX session changes. For example, the sessionState parameter would change from the “Logging out” state to the "Logged out" state after the counterparty accepts the Logout message and responds with counter-Logout message.
  1. OnLogonMessage
Syntax: public virtual void OnLogonMessage(FixSession fixSession, FixMessage message)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • message: Logon message (MsgType=A) received from the counterparty.
Description: This callback method is invoked when a FixSession object receives a Logon message from its counterparty. For a FIX session held by an Acceptor application, this method must be overridden so that it can validate the Logon message received from the counterparty.
  1. OnLogoutMessage
Syntax: public virtual void OnLogoutMessage(FixSession fixSession, FixMessage message)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • message: Logout message (MsgType=5) received from the counterparty.
Description: This callback method is invoked when a FixSession object receives a Logout message from its counterparty. You may override the base implementation of this method, if you want your application to perform any cleaning job after Logout.
  1. OnRejectMessage
Syntax: public abstract void OnRejectMessage(FixSession fixSession, FixMessage message, int rejectedMessageSeqNum)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • message: Reject message (MsgType=3) from the counterparty.
  • rejectedMessageSeqNum: MsgSeqNum (tag 34) of the rejected message.
Description: This callback method is invoked when a FixSession object receives a Reject message (MsgType=3) from the counterparty.
  1. OnInboundWiredMessage
Syntax: public virtual void OnInboundWiredMessage(FixSession fixSession, byte[] bMessageStream)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • bMessageStream: An unparsed FIX Message received from the counterparty.
Description: This callback method is invoked when a FixSession object receives an Inbound Message from its counterparty. The byte array bMessageStream contains the unprocessed bytes received from the counterparty.

This callback enables you to log the unprocessed message that comes to your application directly from the socket (wire).

After this, the FixSession object proceeds to parse and process it. After successful parsing and message validation against the set rules, it again delivers the message to the application in the form of a FixMessage object, provided that the message does not get rejected in the process. Since the rejected messages do not reach the application as FixMessage objects, this callback enables you to look into rejected messages, if required.
  1. OnAdminMessage
Syntax: public virtual void OnAdminMessage(FixSession fixSession, FixMessage message)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • message: An Admin Message received from the counterparty. A message having the MsgType equal to 0, 1, 2, 3, 4, 5 or A is referred to as an Admin Message.
Description: This callback method is invoked when a FixSession object receives an Admin Message from its counterparty.
  1. OnApplicationMessage
Syntax: public abstract void OnApplicationMessage(FixSession fixSession, FixMessage message)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • message: An Application Message received from the counterparty. A message having the MsgType other than 0, 1, 2, 3, 4, 5 and A is referred to as an Application Message.
Description: This callback method is invoked when a FixSession object receives an Application Message from its counterparty. It is important to implement this method in your application as per your business logic because the FF.FIX library includes no business information.
  1. OnInboundMessage
Syntax: public virtual void OnInboundMessage(FixSession fixSession, FixMessage fixMessage)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • fixMessage: The FIX Message received by a FixSession object from its counterparty.
Description: This callback method is invoked whenever the FixSession object receives a message from its counterparty. It is recommended not to use this callback for processing Application Messages. This callback is different from the OnInboundWiredMessage callback because it is invoked only after creating the FixMessage object for the received message.
  1. OnOutboundMessage
Syntax: public virtual void OnOutboundMessage(FixSession fixSession, FixMessage fixMessage)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • fixMessage: The FIX Message to be sent by a FixSession object to its counterparty.
Description: This callback is invoked before the FixSession object sends a FIX Message to its counterparty. It is recommended not to use this callback for the processing of Application Messages.
  1. OnInboundMessageValidationFailed
Syntax: public virtual void OnInboundMessageValidationFailed(FixSession fixSession, FixMessage fixMessage, FixValidationException exp)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • fixMessage: A FIX Message received from the counterparty.
  • exp: FIX validation exception object. Contains information about the encountered error.
Description: This callback is invoked when a FIX Message received from the counterparty fails to get validated against the message validation rules set for the FixSession object.
  1. InBoundQueueSizeThresholdValueReached
Syntax: public virtual void InBoundQueueSizeThresholdValueReached(FixSession fixSession)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
Description: Whenever the set threshold value of unprocessed messages in an Inbound Message queue is reached, the FixSession object invokes this callback to notify the Application about it.

Such a situation is possible if the counterparty sends messages at a rate higher than the message processing rate or if you set a too low value for the InBoundQueueSizeThreshold key in the FIX configuration file. You may take suitable action accordingly.
  1. InBoundQueueThrottleValueReached
Syntax: public virtual void InBoundQueueThrottleValueReached(FixSession fixSession)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
Description: A FixSession object invokes this callback whenever the MessageThrottleValue value set in the FIX configuration file is reached. This FIX configuration setting puts an upper limit (throttles) on the rate of Inbound Messages coming to the FixSession object from its counterparty.
  1. OnInboundMessageMaximumLatencyTimeReached
Syntax: public virtual void OnInboundMessageMaximumLatencyTimeReached(FixSession fixSession, int latencyTime)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • latencyTime: The time interval measured from the SendingTime (tag 52) field value in an Inbound Message to the actual time of receipt of that message by the FixSession object.
Description: A FixSession object invokes this callback whenever the latencyTime value exceeds the value of MaxLatencyTime key in the FIX configuration file.
  1. OnSessionTransmissionFail
Syntax: public abstract void OnSessionTransmissionFail(FixSession fixSession, DateTime lastMessageRecvAt);
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • lastMessageRecvAt: The time when the last FixMessage was received from the counterparty.
Description: A FixSession object invokes this callback whenever it fails to validate a live session after sending a series of Heartbeat and TestRequest messages, as per the session logic settings in the FIX configuration file. After this callback the FIX session is immediately terminated (abnormal termination). It is recommended not to associate any business logic with this callback.
  1. OnGarbledInboundMessageReceived
Syntax: public virtual void OnGarbledInboundMessageReceived(FixSession fixSession, GarbledMessageException garbledMessageException);
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • garbledMessageException: The GarbledMessageException type object that contains details about the exception to be thrown.
Description: A garbled message is the message satisfying any of the following conditions:
  • BeginString (tag 8) is not the first tag in a message or not in the FIX.m.n or FIXT.m.n format. (m = FIX major version, n = FIX minor version)
  • BodyLength (tag 9) is not the second tag in a message or does not contain the correct byte count
  • MsgType (tag 35) is not the third tag in a message.
  • Checksum (tag 10) is not the last tag or contains an incorrect value.
The FIX Protocol presumes garbled messages and the messages failing to get parsed as transmission errors rather than as a problem with the FIX system. It recommends to ignore such messages without incrementing the Inbound Message sequence number. This results in a GapFill situation on receiving the next valid message and the FIX implementation then automatically generates a ResendRequest message to recover the earlier garbled/unparsed message.

If the counterparty sends a series of garbled messages, the ignorance of such messages is not a sufficient action. By default, FF.FIX Engine terminates the FIX session after 5 successive garbled messages. You can change this default behavior of FF.FIX Engine by overwriting the default implementation in this callback. You can also implement your own session logic to take care of possibility of infinite loop.

Callback methods for Initiator applications

The FixInitatorHandler is an abstract class derived from the FixSessionHandler class. It is defined in the FF.Fix.Initiator namespace. An Initiator object takes parameters from FixInitiatorHandler during its initialization and uses them to notify the application about events that occur during a FIX session.All methods defined in the FixSessionHandler class are by default also applicable to the FixInitiatorHandler class.

  1. OnSessionInitialize
Syntax: public abstract void OnSessionInitialize(FixSession fixSession)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
Description: This callback is invoked immediately after the initialization of the FixSession object underlying the Initiator object.
  1. OnConnect
Syntax: public abstract void OnConnect(FixSession fixSession)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
Description: An attempt to establish a connection with the counterparty is made after calling Start() from the Initiator object. This callback is invoked after a connection with the Initiator's counterparty is successfully established.
  1. SendingLogonMessage
Syntax: public virtual void SendingLogonMessage(FixSession fixSession, FixMessage logonMessage)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • logonMessage: A Logon message (MsgType=A).
Description: The default Logon message from an Initiator application contains the fields that are set during the Init() call of the Initiator. The implementation of this callback enables you to decide whether to modify such Logon message before sending it to the counterparty. This callback is invoked before sending a Logon message to the counterparty.
  1. OnConnectionTimeOut
Syntax: public virtual void OnConnectionTimeOut(FixSession fixSession)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
Description: This callback is invoked whenever a connection attempt with the counterparty gets timed out. The timeout value for this callback is the value of the ConnectionTimeOut key in the FIX configuration file for the Initiator application.
  1. OnConnectionFailed
Syntax: public virtual void OnConnectionFailed(FixSession fixSession, string failedReason)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • failedReason: The reason for the connection failure.
Description: This callback method is invoked whenever an established connection with the counterparty fails.
  1. OnLogonTimeOut
Syntax: public virtual void OnLogonTimeOut(FixSession fixSession)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
Description: After sending a Logon request (MsgType=A) to the Acceptor counterparty, the Initiator object waits for a time duration defined by the LogonTimeOut key in the FIX configuration file. The counterparty has to send its counter-Logon message response as an indication of the acceptance of the FIX connection by it within this time.

If the Initiator object does not receive the counter-Logon message within the specified waiting period, it invokes this callback.

If the counterparty responds with a Reject message, the OnLogonMessageRejected(FixSession fixSession, FixMessage message) callback is invoked.
  1. OnLogoutTimeOut
Syntax: public virtual void OnLogoutTimeOut(FixSession fixSession)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
Description: After sending a Logout request (MsgType=5) to the Acceptor counterparty, the Initiator object waits for a time duration defined by the LogoutTimeOut key in the FIX configuration file. If the counterparty fails to respond within this time, the Initiator object invokes this callback.
  1. OnEnrichSessionFixMessageHeader
Syntax: public virtual void OnEnrichSessionFixMessageHeader(FixSession fixSession, FixMessageHeader fixMessageHeader)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • fixMessageHeader: The FixMessageHeader object having default values for Header fields in it.
Description: This callback method is invoked only for the FixSession objects of Initiator type during the Init() call on the Initiator object. The supplied fixMessageHeader parameter contains the default values of Header fields, set through the FixConfig object based on the FIX configuration file.

This callback enables your implementation to decide whether to modify this default Header by adding or deleting tag=value pairs or by modifying the already set values of Header fields. The process of changing the default Header is referred to as Enrichment.

The values set in the Header using this callback are used in the Headers of all subsequent Outbound Messages sent by the FixSession, unless otherwise modified explicitly.
  1. OnLogonMessageRejected
Syntax: public virtual void OnLogonMessageRejected(FixSession fixSession, FixMessage message)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • message: A Reject message (MsgType=3).
Description: This callback method is invoked on receiving a Reject message in response to the Logon message sent by the FixSession object.
  1. OnApplicationMessageNoSendDuringGapFill
Syntax: public virtual void OnApplicationMessageNoSendDuringGapFill(FixSession fixSession, List<FixMessage> messageList)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
  • messageList: A set of Application Messages, which shall not be sent to the counterparty during the GapFill.
Description: During GapFill situations, this callback is invoked in response to a ResendRequest message from the counterparty.

Depending on the value of the ApplicationMessageTypeNotToBeSendAsGapFill key in the FIX configuration file, the Initiator may not resend specific or all Application Messages. For example, a user may configure the Initiator not to send any IOI and Advertisement messages. After compliance with the ResendRequest from the counterparty, the Initiator intimates the list of unsent Application Messages to the trading application using this callback method.
  1. OnStartSessionSchedule
Syntax: public virtual void OnStartSessionSchedule(FixSession fixSession)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
Description: The FF.FIX Engine scheduler invokes this callback on activation of the session start schedule defined in the FIX configuration file.

The default implementation of the method supplied with FF.FIX Engine resets the sequence numbers. For example, a CME session start schedule requires the FixSession object to reset inbound and outbound sequence numbers to 1 on every Monday.

You may modify this callback method to implement your custom start operations.
  1. OnEndSessionSchedule
Syntax: public virtual void OnEndSessionSchedule(FixSession fixSession)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
Description: The FF.FIX Engine scheduler invokes this callback at the time of the scheduled session end, as specified in the FIX configuration file.

The default implementation of the method supplied with FF.FIX Engine resets the sequence numbers.

You may modify this callback method to implement your custom session end operations.

Callback methods for Acceptor applications

The FixAcceptorHandler is an abstract class derived from the FixSessionHandler class. It is defined in the FF.Fix.Acceptor namespace. An Acceptor object takes parameters from FixAcceptorHandler during its initialization and uses them to notify the application about events that occur during a FIX session.

All methods defined in the FixSessionHandler class are by default also applicable to the FixAcceptorHandler class.

  1. OnSessionCreation
Syntax: public virtual void OnSessionCreation(FixSession fixSession)
Parameters:
  • fixSession: The FixSession object that invokes the callback.
Description: This callback method is invoked just after a Logon message from a session initiating counterparty is validated against an Acceptor Target defined by the Acceptor. (Acceptor Target is the TargetCompID of the Acceptor application and the SenderCompID of the session initiating counterparty.)

::FAQ::

  1. What is a callback notification?
  2. How and which method do I use to process business messages?
  3. How do I validate a Logon message from my Initiator counterparty through my Acceptor application?
  1. What is a callback notification?

Application software is often designed around the notion of callbacks. The use of callbacks is a programming technique in which one part of an application sends out notifications to alert the other parts whenever something interesting happens. To be more specific, a callback is a method that is implemented by one or more handlers and is then executed by a notification source.
  1. How and which method do I use to process business messages?

Business messages (also referred to as the Application Messages) are the messages having MsgType (tag 35) field values other than 0, 1, 2, 3, 4, 5 and A.

A FixSession object contains no business logic for reacting to business messages. It simply invokes the OnApplicationMessage callback to notify your trading application about these messages. As a FIX developer, you need to extract information from the business messages using the FF.FIX Engine APIs and then implement your organization's business logic for different business message types.

All inbound business messages must be processed using the callback function OnApplicationMessage.

The following code snippet shows how you can respond to different business message types using override code in the callback:

public override void OnApplicationMessage(FixSession fixSession, FixMessage message)
{
   string msgType = message.MsgType;
   switch(msgType)
   {
      case FixMessageTypes.NewOrder_Single_D:
      ProcessNewOrderBusinessMessage(message.Body);

      break;

      case FixMessageTypes.OrderCancelRequest_F:
      ProcessOrderCancelRequestBusinessMessage(message.Body);

      break;

      ...
      ...
      ...
   }
}
  1. How do I validate a Logon message from my Initiator counterparty through my Acceptor application?

Usually, all Acceptor applications have a very strict authentication mechanism to validate Logon requests from Initiator applications. Based on the specifications agreed with its counterparty, an Acceptor specifically expects certain authentication information like Username (tag 553) and Password (tag 554) in a session initiating Logon message from its counterparty.

An Acceptor application validates a session initiating Logon message based on the implementation of the OnLogonMessage method.

For example:

public override void OnLogonMessage(FixSession fixSession, FixMessage message)
{
   string userName = message.GetFieldAsString(FixFieldTag.Username_553);
   string password = message.GetFieldAsString(FixFieldTag.Password_554);

   //Validate the credential based on internal logic.

   if (Validate(userName, password))
   {
      //Logon message validated, send counter-Logon message as an acknowledgment
      FixMessage fixLogonMessage = fixSession.GetSessionFixMessage("A");
      fixLogonMessage.SetField(FixFieldTag.HeartBtInt_108, "30");
      fixLogonMessage.SetField(FixFieldTag.EncryptMethod_98, "0");
      fixSession.SendMessage(fixLogonMessage);
   }

   else
   {
      //Validation failed. Send a Logout
      FixMessage logoutFixMessage = fixSession.GetLogoutMessage("Invalid Password. Logout Forced");
      fixSession.SendMessage(logoutFixMessage);
      return;
   }
}