Session Adapter Interface

The Session Manager Library communicates with your adapter via the AP_SESSION_AdapterInterface structure. You must initialize an AP_SESSION_AdapterInterface structure with working functions before the library is initialized.

Session Manager Library Initialization

The Session Manager Library is initialized by a call to AP_SESSION_Init() in the event transport constructor of the adapter, where you provide an AP_SESSION_AdapterInterface and a pointer to the transport internals. This will initialize a AP_SESSION_Interface which is then used in all subsequent Session Manager API calls. During the event transport destructor, call AP_SESSION_DeInit().

See also: Session Initialization and Cleanup API

Session Registration

The adapter should find out the sources it wishes to advertise upon start-up, either programmatically or they can be hard coded. Once the sources are identified, they need to be registered with the correlator instance. Sources can be added dynamically.

Sessions are added using AP_SESSION_AddSession() and their parameters using AP_SESSION_AddSessionParams(). By default every session has this parameter:-

Parameter	Description	Type	Allowed Values	Default
HEARTBEAT_TIMEOUT	Correlator heartbeat timeout in seconds	`float`	-	20

Once all the Sessions have been added with their parameters and capabilities, the adapter calls AP_SESSION_RegisterSessions() or AP_SESSION_RegisterSession() and the library will attempt the register them with the MDA Session Manager running in the correlator. If a Session is successfully registered, the transport registered onSessionRegistrationSuccess will be called that was provided in the AP_SESSION_AdapterInterface structure. If a Session fails to register, the transport registered AP_SESSION_AdapterInterface::onSessionRegistrationError() is called.

See also: Session and Parameter addition API; Session Register API

Session Capabilities

Session Capabilities are the MDA data types that a session can provide, the Market Data Library offers APIs for:-

Type	Description	API
STREAMTYPE_BBA	Best Bid and Ask	BBA Processing API
STREAMTYPE_TRADE	Trade	Trade Processing API
STREAMTYPE_MBP	Market by Price / Depth	Depth Processing API
STREAMTYPE_MBO	Market by Order / Orderbook	Orderbook Processing API
STREAMTYPE_QUOTEBOOK	Quotebook	Quotebook Processing API
STREAMTYPE_NEWS	News	News Processing API
STREAMTYPE_EP	Extra Parameters	Extra Params Processing API

also see Session Capabilities. A adapter however can add it's own capabilities, such as OHLC or Market Phase.

Once a Session has been added, all its capabilities are then provided to the Session Manager Library using the AP_SESSION_AddCapabilities() or AP_SESSION_AddCapabilitiesById() API calls. Then each of the capabilities should have its parameters set using AP_SESSION_AddCapabilityParams() or AP_SESSION_AddCapabilityParamsById() API calls.

By default every capability has these parameter:-

Parameter	Description	Type	Allowed Values	Default
TRANSFER_MODE	The mode which updates are sent	`string`	'COMPOUND_DELTA' or 'SNAPSHOT_ONLY'	'COMPOUND_DELTA'
NUM_LEVELS	The maximum number of levels a book data type will send (applies to Depth, Orderbook and Quotebook)	`integer`	-	5
DISABLE_EP	Whether to disable Extra Parameter output	`boolean`	true/false	false
INCLUDE_INDICATIVE_PRICES	Whether to include indicative prices in the Quotebook	`boolean`	true/false	true

See also: Supported Capabilities; Session Capabilities API

Session Start, Stop and Configuration

When a user wants to start a session, the transport registered AP_SESSION_AdapterInterface::onSessionStart() is called and the adapter should connect to the external source. Once connected, set the Session state to SESSION_CONNECTED using AP_SESSION_SetSessionStateByName() or AP_SESSION_SetSessionStateById() and then call the Session start success callback AP_SESSION_SessionStartSuccess(). If the Session fails to start, call AP_SESSION_SessionStartError().

User configuration for the session is provided in the configParams in the transport registered AP_SESSION_AdapterInterface::onSessionStart().

The the transport registered AP_SESSION_AdapterInterface::onSessionReconfigure will be called when a user wants a Session to be reconfigured with the supplied configParams. If the reconfiguration is successful call AP_SESSION_SessionReconfigureSuccess(), else call AP_SESSION_SessionReconfigureError().

When a user wants to stop a session, the transport registered AP_SESSION_AdapterInterface::onSessionStop is called and the adapter should disconnect from the external source. Once disconnected, set the Session state to SESSION_DISCONNECTED using AP_SESSION_SetSessionStateByName() or AP_SESSION_SetSessionStateById() and then call the Session stop success callback AP_SESSION_SessionStopSuccess(). If the Session fails to stop, call AP_SESSION_SessionStopError().

There are some other states that a Session can be set to depending on the complexity of the adapter (such as Logged In), see AP_SESSION_State.

See also: Session Callbacks API; Session State API; AP_SESSION_State

Session Reset and Heartbeats

Heartbeat events are passed between the correlator and adapter so each component knows about the continued existence of the other. If the correlator does not receive a heartbeat response, which could be due to unavailability of the adapter or network delay, the transport registered AP_SESSION_AdapterInterface::onSessionReset is called. The adapter should then clean up it's subscriptions and return to an initial state. The correlator will then attempt to re-start the Session and re-subscribe to symbols. The transport registered AP_SESSION_AdapterInterface::onCorrelatorWatchDogTimedOut() is called when the library fails to receive heartbeats from the correlator. The adapter should then:-

Stop processing any messages from external sources.
Clear all subscriptions.
Clear all Sessions.
Disconnect all sources.

The adapter can update the heartbeat timeout interval that the library waits by using the AP_SESSION_SetCorrelatorHBTimeout().