Session.h

Go to the documentation of this file.

/*
* Copyright Onix Solutions Limited [OnixS]. All rights reserved.
*
* This software owned by Onix Solutions Limited [OnixS] and is protected by copyright law
* and international copyright treaties.
*
* Access to and use of the software is governed by the terms of the applicable OnixS Software
* Services Agreement (the Agreement) and Customer end user license agreements granting
* a non-assignable, non-transferable and non-exclusive license to use the software
* for it's own data processing purposes under the terms defined in the Agreement.
*
* Except as otherwise granted within the terms of the Agreement, copying or reproduction of any part
* of this source code or associated reference material to any other location for further reproduction
* or redistribution, and any amendments to this copyright notice, are expressly prohibited.
*
* Any reproduction or redistribution for sale or hiring of the Software not in accordance with
* the terms of the Agreement is a violation of copyright law.
*/

#pragma once

#include <string>
#include <set>
#include <vector>
#include <utility>
#include <iosfwd>
#include <limits>

#include <OnixS/FIXEngine/Compiler.h>
#include <OnixS/FIXEngine/FIX/Engine.h>
#include <OnixS/FIXEngine/Cryptography/SecureString.h>


#include <OnixS/FIXEngine/Sockets/Definitions.h>

#include <OnixS/FIXEngine/FIX/SessionState.h>
#include <OnixS/FIXEngine/FIX/SessionStorageType.h>
#include <OnixS/FIXEngine/FIX/SessionRole.h>
#include <OnixS/FIXEngine/FIX/ThreadingModel.h>
#include <OnixS/FIXEngine/FIX/EncryptionMethod.h>
#include <OnixS/FIXEngine/FIX/SessionSendMode.h>
#include <OnixS/FIXEngine/FIX/SequenceNumber.h>
#include <OnixS/FIXEngine/FIX/ISessionReactor.h>

#include <OnixS/FIXEngine/FIX/Timestamp.h>

#include <OnixS/FIXEngine/FIX/FlatMessage.h>

#include <OnixS/FIXEngine/Threading/Thread.h>
#include <OnixS/FIXEngine/Threading/Future.h>


namespace OnixS {
namespace FIX {
ONIXS_FIXENGINE_API_DECL(class, Message);
ONIXS_FIXENGINE_API_DECL(class, Dictionary);
ONIXS_FIXENGINE_API_DECL(class, Engine);
ONIXS_FIXENGINE_API_DECL(class, ISessionListener);
ONIXS_FIXENGINE_API_DECL(class, ISessionStorage);

/// Session message mode.
struct MessageMode {
    enum Enum {
        /// The default mode. The `Message` class is used in inbound callbacks.
        Message = 1,

        /// The `FlatMessage` class is used in inbound callbacks.
        FlatMessage
    };
};

namespace Core {
namespace Messaging {
class Message;
}
}

template<typename MsgType>
struct MsgBatchTraits
{
    typedef typename PtrTraits<MsgType>::UniquePtr MessagePtr;
    typedef std::vector<FlatMessage*> MsgBatchType;
    typedef std::vector<OnixS::FIX::Core::Messaging::Extras::FlatMessage*> CoreMsgBatchType;
};

template<>
struct MsgBatchTraits<Message>
{
    typedef PtrTraits<Message>::UniquePtr MessagePtr;
    typedef std::vector<Message*> MsgBatchType;
    typedef std::vector<OnixS::FIX::Core::Messaging::Message*> CoreMsgBatchType;
};

/**
* FIX Session - a bi-directional stream of ordered messages between two parties within a continuous sequence number series.
*/
class ONIXS_FIXENGINE_API Session
{
public:
    /**
    * Creates the FIX Session.
    *
    * @param senderCompId Assigned value used to identify firm sending message (SenderCompID (tag=49) field value in outgoing messages).
    * @param targetCompId Assigned value used to identify receiving firm (TargetCompID (tag=56) field value in outgoing messages).
    * @param dictionary FIX dictionary to be used by the session.
    * @param listener Instance of ISessionListener interface which will receive and handle miscellaneous Session events.
    * @param storageType Session storage type.
    * @param storage Pluggable Session storage.
    */
    Session(
        const std::string & senderCompId,
        const std::string & targetCompId,
        const Dictionary & dictionary,
        ISessionListener * listener,
        SessionStorageType::Enum storageType = SessionStorageType::FileBased,
        ISessionStorage * storage = ONIXS_FIXENGINE_NULLPTR);

    /**
    * Creates the FIX Session.
    *
    * @param reactor An instance of an externally managed reactor.
    * @param senderCompId Assigned value used to identify firm sending message (SenderCompID (tag=49) field value in outgoing messages).
    * @param targetCompId Assigned value used to identify receiving firm (TargetCompID (tag=56) field value in outgoing messages).
    * @param dictionary FIX dictionary to be used by the session.
    * @param listener Instance of ISessionListener interface which will receive and handle miscellaneous Session events.
    * @param storageType Session storage type.
    * @param storage Pluggable Session storage.
    */
    Session(
        ISessionReactor * reactor,
        const std::string & senderCompId,
        const std::string & targetCompId,
        const Dictionary & dictionary,
        ISessionListener * listener,
        SessionStorageType::Enum storageType = SessionStorageType::FileBased,
        ISessionStorage * storage = ONIXS_FIXENGINE_NULLPTR);

    /**
    * Creates the FIX Session.
    *
    * @param senderCompId Assigned value used to identify firm sending message (SenderCompID (tag=49) field value in outgoing messages).
    * @param targetCompId Assigned value used to identify receiving firm (TargetCompID (tag=56) field value in outgoing messages).
    * @param dictionary FIX dictionary to be used by the session.
    * @param keepSequenceNumbersAfterLogout Option to keep sequence numbers after the exchange of Logout (MsgType=5) messages.
    * @param listener Instance of ISessionListener interface which will receive and handle miscellaneous Session events.
    * @param storageType Session storage type.
    * @param storage Pluggable Session storage.
    */
    Session(
        const std::string & senderCompId,
        const std::string & targetCompId,
        const Dictionary & dictionary,
        bool keepSequenceNumbersAfterLogout,
        OnixS::FIX::ISessionListener * listener,
        SessionStorageType::Enum storageType = SessionStorageType::FileBased,
        ISessionStorage * storage = ONIXS_FIXENGINE_NULLPTR);


    /**
    * Creates the FIX Session.
    *
    * @param reactor An instance of an externally managed reactor.
    * @param senderCompId Assigned value used to identify firm sending message (SenderCompID (tag=49) field value in outgoing messages).
    * @param targetCompId Assigned value used to identify receiving firm (TargetCompID (tag=56) field value in outgoing messages).
    * @param dictionary FIX dictionary to be used by the session.
    * @param keepSequenceNumbersAfterLogout Option to keep sequence numbers after the exchange of Logout (MsgType=5) messages.
    * @param listener Instance of ISessionListener interface which will receive and handle miscellaneous Session events.
    * @param storageType Session storage type.
    * @param storage Pluggable Session storage.
    */
    Session(
        ISessionReactor * reactor,
        const std::string & senderCompId,
        const std::string & targetCompId,
        const Dictionary & dictionary,
        bool keepSequenceNumbersAfterLogout,
        OnixS::FIX::ISessionListener * listener,
        SessionStorageType::Enum storageType = SessionStorageType::FileBased,
        ISessionStorage * storage = ONIXS_FIXENGINE_NULLPTR);

    /**
    * Creates the FIX Session.
    *
    * @param senderCompId Assigned value used to identify firm sending message (SenderCompID (tag=49) field value in outgoing messages).
    * @param targetCompId Assigned value used to identify receiving firm (TargetCompID (tag=56) field value in outgoing messages).
    * @param dictionary FIX dictionary to be used by the session.
    * @param keepSequenceNumbersAfterLogout Option to keep sequence numbers after the exchange of Logout (MsgType=5) messages.
    * @param listener Instance of ISessionListener interface which will receive and handle miscellaneous Session events.
    * @param customSessionKey Custom key that can be used to distinguish sessions with the same values of the SenderCompID, TargetCompID and the FIX Protocol version.
    * @param storageType Session storage type.
    * @param storage Pluggable Session storage.
    */
    Session(
        const std::string & senderCompId,
        const std::string & targetCompId,
        const Dictionary & dictionary,
        bool keepSequenceNumbersAfterLogout,
        OnixS::FIX::ISessionListener * listener,
        const std::string & customSessionKey,
        SessionStorageType::Enum storageType = SessionStorageType::FileBased,
        ISessionStorage * storage = ONIXS_FIXENGINE_NULLPTR);

    /**
    * Creates the FIX Session.
    *
    * @param reactor An instance of an externally managed reactor.
    * @param senderCompId Assigned value used to identify firm sending message (SenderCompID (tag=49) field value in outgoing messages).
    * @param targetCompId Assigned value used to identify receiving firm (TargetCompID (tag=56) field value in outgoing messages).
    * @param dictionary FIX dictionary to be used by the session.
    * @param keepSequenceNumbersAfterLogout Option to keep sequence numbers after the exchange of Logout (MsgType=5) messages.
    * @param listener Instance of ISessionListener interface which will receive and handle miscellaneous Session events.
    * @param customSessionKey Custom key that can be used to distinguish sessions with the same values of the SenderCompID, TargetCompID and the FIX Protocol version.
    * @param storageType Session storage type.
    * @param storage Pluggable Session storage.
    */
    Session(
        ISessionReactor * reactor,
        const std::string & senderCompId,
        const std::string & targetCompId,
        const Dictionary & dictionary,
        bool keepSequenceNumbersAfterLogout,
        OnixS::FIX::ISessionListener * listener,
        const std::string & customSessionKey,
        SessionStorageType::Enum storageType = SessionStorageType::FileBased,
        ISessionStorage * storage = ONIXS_FIXENGINE_NULLPTR);

    /**
    * Destructor.
    */
    ~Session();

    /**
    * Removes all messages from the outbound queue.
    *
    * @param removeFragmentedPacket - specifies whether to remove last packet which is partly sent.
    *
    * @note This call is thread-safe.
    */
    Session & clearOutboundQueue(bool removeFragmentedPacket = false);

    /**
    * Returns Session's state.
    *
    * @note This call is thread-safe.
    */
    SessionState::Enum state() const;

    /**
    * Returns the current encryption method.
    *
    * @note This call is thread-safe.
    */
    EncryptionMethod::Enum encryptionMethod() const;

    /**
    * Sets the encryption method.
    *
    * @note This call is thread-safe.
    */
    Session & encryptionMethod(EncryptionMethod::Enum newEncryptionMethod);

    /**
    * Returns the port to listen on for incoming FIX Connections in Acceptor mode.
    *
    * @note This call is thread-safe.
    */
    int listenPort() const;

    /**
    * Sets the port to listen on for incoming FIX Connections in Acceptor mode.
    *
    * @note This call is thread-safe.
    */
    Session & listenPort(int listenPort);

    /**
    * Returns the local network interface from which you intend to send and receive data.
    *
    * @note This call is thread-safe.
    */
    std::string localNetworkInterface() const;

    /**
    * Sets the local network interface from which you intend to send and receive data.
    *
    * @note This call is thread-safe.
    */
    Session & localNetworkInterface(const std::string & localNetworkInterface);

    /**
    * Returns the local port from which you intend to send and receive data.
    *
    * @note This call is thread-safe.
    */
    unsigned short localPort() const;
    /**
    * Local port range type.
    */
    typedef std::pair<unsigned short, unsigned short> LocalPortRange;

    /**
    * Returns the local port range, the first available port from this range will be used to send and receive data.
    *
    * @note This call is thread-safe.
    */
    LocalPortRange localPortRange() const;

    /**
    * Sets the local port range, the first available port from this range will be used to send and receive data.
    *
    * @note This call is thread-safe.
    */
    Session & localPortRange(LocalPortRange portRange);

    /**
    * Returns option to improve latency at the expense of message throughput (TCP_NODELAY socket option).
    * When it is not set, the corresponding Engine setting's value is used ('true' by default).
    */
    bool tcpNoDelayOption() const;

    /**
    * Sets value of option to improve latency at the expense of message throughput (TCP_NODELAY socket option).
    */
    Session & tcpNoDelayOption(bool improveLatency = true);

    /**
    * Returns the option that controls whether to send the logout message before
    * dropping the telecommunication link, in case of exception.
    * When it is not set, the corresponding Engine setting's value is used ('false' by default).
    */
    bool sendLogoutOnException() const;

    /**
    * Sets value of the option that controls whether to send the logout message before
    * dropping the telecommunication link, in case of exception.
    */
    Session & sendLogoutOnException(bool sendLogoutOnException);

    /**
    * Returns option to validate the presence of unknown FIX messages.
    * When it is not set, the corresponding Engine setting's value is used ('false' by default).
    */
    bool validateUnknownMessages() const;

    /**
    * Sets option to validate the presence of unknown FIX messages.
    */
    Session & validateUnknownMessages(bool);

    /**
    * Returns option to validate the presence of unknown fields.
    * When it is not set, the corresponding Engine setting's value is used ('false' by default).
    */
    bool validateUnknownFields() const;

    /**
    * Sets option to validate the presence of unknown fields.
    */
    Session & validateUnknownFields(bool);

    /**
    * Returns option to validate the presence of required fields in inbound and outbound messages.
    * When it is not set, the corresponding Engine setting's value is used ('false' by default).
    */
    bool validateRequiredFields() const;

    /**
    * Sets option to validate the presence of required fields in inbound and outbound messages.
    */
    Session & validateRequiredFields(bool);

    /**
    * Returns option to validate the field values of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
    * When it is not set, the corresponding Engine setting's value is used ('false' by default).
    */
    bool validateFieldValues() const;

    /**
    * Sets option to validate the field values of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
    */
    Session & validateFieldValues(bool);

    /**
    * Returns option to validate the empty field values of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
    * When it is not set, the corresponding Engine setting's value is used ('false' by default).
    */
    bool validateEmptyFieldValues() const;

    /**
    * Sets option to validate the empty field values of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
    */
    Session & validateEmptyFieldValues(bool);

    /**
    * Returns the option that controls repeating group entry count validation.
    * When it is not set, the corresponding Engine setting's value is used ('true' by default).
    */
    bool validateRepeatingGroupEntryCount() const;

    /**
    * Sets value of the option that controls repeating group entry count validation.
    */
    Session & validateRepeatingGroupEntryCount(bool);

    /**
    * Returns the option that controls repeating group leading tag validation.
    * When it is not set, the corresponding Engine setting's value is used ('false' by default).
    */
    bool validateRepeatingGroupLeadingTag() const;

    /**
    * Sets value of the option that controls repeating group leading tag validation.
    */
    Session & validateRepeatingGroupLeadingTag(bool);

    /**
    * Returns the option that controls duplicated field validation.
    * When it is not set, the corresponding Engine setting's value is used ('false' by default).
    */
    bool validateDuplicatedField() const;

    /**
    * Sets value of the option that controls duplicated field validation.
    */
    Session & validateDuplicatedField(bool);

    /**
    * Returns the option that controls the validation of the checksum of the incoming message.
    * When it is not set, the corresponding Engine setting's value is used ('false' by default).
    */
    bool validateChecksum() const;

    /**
    * Sets the validation of the checksum of the incoming message.
    */
    Session & validateChecksum(bool);

    /**
    * Returns the number of messages that should be written to the outgoing TCP buffer together.
    * When it is not set, the corresponding Engine setting's value is used (0 by default).
    */
    unsigned messageGrouping() const;

    /**
    * Sets the number of messages that should be written to the outgoing TCP buffer together.
    */
    Session & messageGrouping(unsigned numberOfMessagesToGroup);

    /**
    * Returns the connection mode.
    */
    ThreadingModel::Enum threadingModel() const;

    /**
    * Sets the connection mode.
    */
    Session & threadingModel(ThreadingModel::Enum value);

    /**
    * Returns the reasonable transmission time as % from heartbeatIntervalSec value.
    * When it is not set, the corresponding Engine setting's value is used (20% by default).
    */
    int reasonableTransmissionTime() const;

    /**
    * Sets the reasonable transmission time as % from heartbeatIntervalSec value.
    *
    * When either end of the connection has not received any data for (heartbeatIntervalSec() * (100 + reasonableTransmissionTime())/100) seconds,
    * it will transmit a Test Request message.
    *
    * If there is still no Heartbeat message received after (heartbeatIntervalSec * (100 + reasonableTransmissionTime())/100) seconds
    * then the connection should be considered lost and corrective action be initiated.
    */
    Session & reasonableTransmissionTime(int value);

    /**
    * Sets the number of attempts to restore the telecommunication link.
    */
    Session & reconnectAttempts(int value);

    /**
    * Returns the number of attempts to restore the telecommunication link.
    * When it is not set, the corresponding Engine setting's value is used (3 by default).
    */
    int reconnectAttempts() const;

    /**
    * Sets the time interval between the attempts to restore the telecommunication link (in seconds).
    */
    Session & reconnectInterval(int value);

    /**
    * Returns the time interval between the attempts to restore the telecommunication link (in seconds).
    * When it is not set, the corresponding Engine setting's value is used (180 by default).
    */
    int reconnectInterval() const;

    /**
    * Sets the non-blocking receive spinning timeout (in microseconds) before the receiving thread enters into the blocking wait mode.
    *
    * @note Should not be greater than 1 sec (minimal heartbeatIntervalSec()).
    */
    Session & receiveSpinningTimeoutUsec(int usec);

    /**
    * Returns the current receive spinning timeout value (in microseconds).
    * By default, the value is zero and receive spinning is not used.
    */
    int receiveSpinningTimeout() const;

    /**
    * Sets the send spinning timeout (in microseconds) of the Session::send(..) method to wait for the socket sending buffer availability
    * in the spin loop mode before placing the message to the outgoing queue (to be sent later by the sending thread).
    *
    * @note Should not be greater than 1 sec (minimal heartbeatIntervalSec()).
    */
    Session & sendSpinningTimeoutUsec(int usec);

    /**
    * Returns the current send spinning timeout value (in microseconds).
    * By default, the value is zero and send spinning is not used.
    */
    int sendSpinningTimeout() const;

    /**
    * Sets NextExpectedMsgSeqNum field (tag 789) support in Logon messages.
    */
    Session & supportNextExpectedMsgSeqNum(bool support);

    /**
    * Returns 'true' if NextExpectedMsgSeqNum field (tag 789) is supported in Logon messages, otherwise - 'false'.
    * By default, the option value is false.
    */
    bool supportNextExpectedMsgSeqNum() const;

    /**
     * Returns the SSL certificate file.
     *
     * @note This call is thread-safe.
     */
    std::string sslCertificateFile() const;

    /**
    * Sets the SSL certificate file.
    *
    * @note Only the (Privacy Enhanced Mail) Base 64 Encoded (.pem) SSL certificates are supported.
    *
    * @note This call is thread-safe.
    */
    Session & sslCertificateFile(const std::string & file);

    /**
     * Returns the SSL private key file.
     *
     * @note This call is thread-safe.
     */
    std::string sslPrivateKeyFile() const;

    /**
    * Sets the SSL private key file.
    *
    * @note Only the (Privacy Enhanced Mail) Base 64 Encoded (.pem) SSL certificates are supported.
    *
    * @note This call is thread-safe.
    */
    Session & sslPrivateKeyFile(const std::string & file);

    /**
     * Returns the SSL private key file password.
     *
     * @note This call is thread-safe.
     */
    Cryptography::SecureString sslPrivateKeyPassword() const;

    /**
    * Sets the SSL private key file password.
    *
    * @note This call is thread-safe.
    */
    Session & sslPrivateKeyPassword(const Cryptography::SecureString & password);

    /**
    * Set option to request peer certificates and perform the certificate verification.
    *
    * @note This call is thread-safe.
    */
    Session & sslVerifyPeer(bool verify);

    /**
    * Returns option to request peer certificates and perform the certificate verification.
    * When it is not set, the corresponding Engine setting's value is used ('false' by default).
    *
    * @note This call is thread-safe.
    */
    bool sslVerifyPeer() const;

    /**
    * Sets the path to the trusted certification authority certificate file in (Privacy Enhanced Mail) Base64 encoded (.pem) format.
    *
    * @note This call is thread-safe.
    */
    Session & sslCaFile(const std::string & value);

    /**
    * Returns the path to trusted certification authority certificate file in (Privacy Enhanced Mail) Base64 encoded (.pem) format.
    *
    * @note This call is thread-safe.
    */
    std::string sslCaFile() const;

    /**
    * Establishes the FIX Connection as Acceptor.
    *
    * Acceptor is the receiving party of the FIX session. It listens for the incoming connection on the pre-defined port.
    * The acceptor has responsibility to perform first level authentication and formally declare
    * the connection request "accepted" through transmission of an acknowledgment Logon message.
    *
    * @note This call is thread-safe.
    */
    Session & logonAsAcceptor();

    /**
    * Establishes FIX Connection as Initiator using the ResetSeqNumFlag (tag 141) field.
    *
    * Initiator establishes the telecommunications link and initiates the session via transmission
    * of the initial Logon message.
    * The method is blocked until the acknowledgment Logon message is received or the timeout expired.
    * The timeout value is equal to the triple heartbeat interval.
    *
    * @note This call is thread-safe.
    */
    Session & logonAsInitiator(const std::string & host, int port, bool setResetSeqNumFlag);

    /**
    * Establishes FIX Connection as Initiator.
    *
    * Initiator establishes the telecommunications link and initiates the session via transmission
    * of the initial Logon message.
    * The method is blocked until the acknowledgment Logon message is received or the timeout expired.
    * The timeout value is equal to the triple heartbeat interval.
    *
    * @note This call is thread-safe.
    */
    Session & logonAsInitiator(const std::string & host, int port);

    /**
    * Establishes FIX Connection as Initiator using the given Heartbeat interval (seconds).
    * The method is blocked until the acknowledgment Logon message is received or the timeout expired.
    * The timeout value is equal to the triple heartbeat interval.
    *
    * @note This call is thread-safe.
    */
    Session & logonAsInitiator(const std::string & host, int port, int heartbeatIntervalSec);

    /**
    * Establishes FIX Connection as Initiator using the given Heartbeat interval (seconds) and the ResetSeqNumFlag(141) field.
    * The method is blocked until the acknowledgment Logon message is received or the timeout expired.
    * The timeout value is equal to the triple heartbeat interval.
    *
    * @note This call is thread-safe.
    */
    Session & logonAsInitiator(const std::string & host, int port, int heartbeatIntervalSec, bool setResetSeqNumFlag);

    /**
    * Establishes FIX Connection as Initiator using the custom Logon message.
    * The method is blocked until the acknowledgment Logon message is received or the timeout expired.
    * The timeout value is equal to the triple heartbeat interval.
    *
    * @note This call is thread-safe.
    */
    Session & logonAsInitiator(const std::string & host, int port, int heartbeatIntervalSec, Message * customLogonMsg);

    /**
    * Establishes FIX Connection as Initiator using the custom Logon message and the ResetSeqNumFlag(141) field.
    * The method is blocked until the acknowledgment Logon message is received or the timeout expired.
    * The timeout value is equal to the triple heartbeat interval.
    *
    * @note This call is thread-safe.
    */
    Session & logonAsInitiator(const std::string & host, int port, int heartbeatIntervalSec, Message * customLogonMsg, bool setResetSeqNumFlag);

    /**
    * Establishes FIX Connection asynchronously as Initiator using the custom Logon message and the ResetSeqNumFlag(141) field.
    * The method returns immediately without waiting the acknowledgment Logon message.
    * Returns the `SharedFuture` object that can be used to wait for the result of the asynchronous logon method.
    *
    * @note This call is thread-safe.
    */
    Threading::SharedFuture<void> logonAsInitiatorAsync(const std::string & host, int port, int heartbeatIntervalSec, Message * customLogonMsg, bool setResetSeqNumFlag);

    /**
    * Terminates the FIX Connection.
    *
    * The initial Logout message is sent to the counterparty and the method is blocked until the acknowledgment
    * Logout message is received or the timeout expired.
    * The timeout value is equal to the triple heartbeat interval or,
    * in case there are no incoming messages, heartbeat interval plus reasonable transmission time.
    *
    * @note This call is thread-safe.
    */
    Session & logout();

    /**
    * Terminates the FIX Connection.
    *
    * The initial Logout message is sent to the counterparty and the method is blocked until the acknowledgment
    * Logout message is received or the timeout expired.
    * The timeout value is equal to the triple heartbeat interval or,
    * in case there are no incoming messages, heartbeat interval plus reasonable transmission time.
    *
    * @param text Free format text string that is sent to the counterparty in the Text(58) field of the initial
    * Logout message.
    *
    * @note This call is thread-safe.
    */
    Session & logout(const std::string & text);

    /**
    * Terminates the FIX Connection.
    *
    * The initial Logout message is sent to the counterparty and the method returns immediately
    * without waiting the acknowledgment Logout message.
    * Returns the `SharedFuture` object that can be used to wait for the result of the asynchronous logout method.
    *
    * @param text Free format text string that is sent to the counterparty in the Text(58) field of the initial
    * Logout message.
    *
    * @note This call is thread-safe.
    */
    Threading::SharedFuture<void> logoutAsync(const std::string & text);

    /**
    * Terminates the FIX Connection.
    *
    * The initial Logout message is sent to the counterparty and the method is blocked until the acknowledgment
    * Logout message is received or the timeout expired.
    * The timeout value is equal to the triple heartbeat interval or,
    * in case there are no incoming messages, heartbeat interval plus reasonable transmission time.
    *
    * @param customLogoutMessage Custom Logout message that is sent to the counterparty.
    *
    * @note This call is thread-safe.
    */
    Session & logout(Message * customLogoutMessage);
    Session & logout(FlatMessage * customLogoutMessage);

    /**
    * Terminates the FIX Connection.
    *
    * The initial Logout message is sent to the counterparty and the method returns immediately
    * without waiting the acknowledgment Logout message.
    * Returns the `SharedFuture` object that can be used to wait for the result of the asynchronous logout method.
    *
    * @param customLogoutMessage Custom Logout message that is sent to the counterparty.
    *
    * @note This call is thread-safe.
    */
    Threading::SharedFuture<void> logoutAsync(Message * customLogoutMessage);
    Threading::SharedFuture<void> logoutAsync(FlatMessage * customLogoutMessage);

    /**
    * Terminates the FIX connection in the non-graceful way (without the exchange of Logout (MsgType=5) messages).
    *
    * @note This call is thread-safe.
    */
    Session & breakConnection();

    /**
    * Sends the message to the counterparty.
    *
    * As soon as a session is created, it is possible to start sending messages via the session.
    * If the session is not established, the messages are stored in the session storage and will be sent in replay to the resend request
    * when the connection is established with the counterparty and the sequence numbers mismatch is detected.
    *
    * @note This call is asynchronous.
    *
    * @note This call is thread-safe.
    */
    Session & send(Message * msg);
    Session & send(FlatMessage * msg);

    /**
    * Performs sending via a specific API (e.g. zero-copy send) of the message to the counterparty.
    *
    * As soon as a session is created, it is possible to start sending messages via the session.
    * If the session is not established, the messages are stored in the session storage and will be sent in replay to the resend request
    * when the connection is established with the counterparty and the sequence numbers mismatch is detected.
    *
    * @note This call is asynchronous.
    *
    * @note This call is thread-safe.
    */
    Session & send(FlatMessage * msg, SessionSendMode::Enum mode);

    /**
    * Message batch types.
    */
    template<typename MsgType> class MsgBatch;

    class ONIXS_FIXENGINE_API MsgBatchHelper
    {
        typedef MsgBatchTraits<Message> MBT;
        typedef MsgBatchTraits<FlatMessage> SBT;

        static void init(MBT::CoreMsgBatchType & coreBatch);
        static void init(SBT::CoreMsgBatchType & coreBatch);
        static void add(MBT::MsgBatchType & batch, MBT::CoreMsgBatchType & coreBatch, MBT::MessagePtr & msg);
        static void add(SBT::MsgBatchType & batch, SBT::CoreMsgBatchType & coreBatch, SBT::MessagePtr & msg);
        static void clear(MBT::MsgBatchType & batch);
        static void clear(SBT::MsgBatchType & batch);

        template<typename MsgType> friend class MsgBatch;
    };

    template<typename MsgType>
    class MsgBatch
    {
        typedef MsgBatchTraits<MsgType> Traits;

        friend class Session;

        typename Traits::MsgBatchType batch_;
        typename Traits::CoreMsgBatchType coreBatch_;

        MsgBatch(const MsgBatch&);
        MsgBatch & operator=(const MsgBatch&);

    public:

        typedef typename Traits::MessagePtr MessagePtr;
        typedef typename Traits::MsgBatchType::iterator iterator;
        typedef typename Traits::MsgBatchType::const_iterator const_iterator;

        MsgBatch() { MsgBatchHelper::init(coreBatch_); }
        ~MsgBatch() { MsgBatchHelper::clear(batch_); }

        void add(MessagePtr & msg) { MsgBatchHelper::add(batch_, coreBatch_, msg); }

        MsgType & operator[](size_t index) { return *batch_[index]; }
        const MsgType & operator[](size_t index) const { return *batch_[index]; }

        size_t size() const { return batch_.size(); }

        const_iterator begin() const { return batch_.begin(); }
        iterator begin() { return batch_.begin(); }

        const_iterator end() const { return batch_.end(); }
        iterator end() { return batch_.end(); }
    };

    typedef MsgBatch<Message> MessageBatch;
    typedef MsgBatch<FlatMessage> FlatMessageBatch;
    typedef FlatMessageBatch SerializedMessageBatch;

    /**
    * Sends messages in a batch to the counterparty.
    *
    * As soon as a session is created, it is possible to start sending messages via the session.
    * If the session is not established, the messages are stored in the session storage and will be sent in replay to the resend request
    * when the connection is established with the counterparty and the sequence numbers mismatch is detected.
    *
    *@param msgs Message batch to send.
    *@param maxPacketSize The maximum number of bytes written to the socket's send buffer together.
    * This parameter could be used to reduce the probability that the operating system will fragment a FIX message across multiple TCP packets.
    *
    * @note The message batch should not be empty and maxPacketSize parameter should not be less than any message size in the batch.
    * Otherwise, the method call can produce an error and the session can close the connection.
    *
    * @note This call is asynchronous.
    *
    * @note This call is thread-safe.
    */
    Session & send(MessageBatch & msgs, size_t maxPacketSize = (std::numeric_limits<size_t>::max)());
    Session & send(FlatMessageBatch & msgs, size_t maxPacketSize = (std::numeric_limits<size_t>::max)());

    /**
    * Performs sending via a specific API (e.g. zero-copy send) of messages to the counterparty.
    *
    * As soon as a session is created, it is possible to start sending messages via the session.
    * If the session is not established, the messages are stored in the session storage and will be sent in replay to the resend request
    * when the connection is established with the counterparty and the sequence numbers mismatch is detected.
    *
    * @note This call is asynchronous.
    *
    * @note This call is thread-safe.
    */
    Session & send(FlatMessageBatch & msgs, SessionSendMode::Enum mode, size_t maxPacketSize = (std::numeric_limits<size_t>::max)());

    /**
    * Sends serialized message(s) to the counterparty without any fields updating.
    * One can use the preFill method to prepare message(s) for sending.
    *
    * As soon as a session is created, it is possible to start sending messages via the session.
    * If the session is not established, the messages are stored in the session storage and will be sent in replay to the resend request
    * when the connection is established with the counterparty and the sequence numbers mismatch is detected.
    *
    * @note This call is asynchronous.
    *
    * @note This call is thread-safe.
    */
    Session & sendAsIs(FlatMessage * msg);

    /**
    * Sends serialized message(s) to the counterparty without any fields updating.
    * One can use the preFill method to prepare message(s) for sending.
    *
    * As soon as a session is created, it is possible to start sending messages via the session.
    * If the session is not established, the messages are stored in the session storage and will be sent in replay to the resend request
    * when the connection is established with the counterparty and the sequence numbers mismatch is detected.
    *
    *@param msgs Message batch to send.
    *@param maxPacketSize The maximum number of bytes written to the socket's send buffer together.
    * This parameter could be used to reduce the probability that the operating system will fragment a FIX message across multiple TCP packets.
    *
    * @note The message batch should not be empty and maxPacketSize parameter should not be less than any message size in the batch.
    * Otherwise, the method call can produce an error and the session can close the connection.
    *
    * @note This call is asynchronous.
    *
    * @note This call is thread-safe.
    */
    Session & sendAsIs(FlatMessageBatch & msgs, size_t maxPacketSize = (std::numeric_limits<size_t>::max)());

    /**
    * Performs throttling of a session that must be called before each of a send function call.
    * If the count of messages per a time unit exceeds a throttling limit, the function will be blocked until the given time interval is passed.
    *
    * @note This call is thread-safe.
    */
    Session & throttle();

    /**
    * Sets throttling limit parameters.
    *
    *@param messagesCount Message limit per a time unit.
    *@param intervalInMs Time interval to limit messages.
    *
    * @note This call is thread-safe.
    */
    Session & throttlingLimit(size_t messagesCount, size_t intervalInMs = 1000);

    /**
    * This method warms up the sending path.
    *
    *@param msg Message to warm up the assembly part of the sending path.
    *@param warmupFlags Specific flags which can be used to turn on the warmup feature for a specific NIC.

    * @note This call is thread-safe.
    */
    Session & warmUp(FlatMessage* msg, int warmupFlags = 0);

    /**
    * Returns 'true' if given flags work as expected and a real data is not sent to the wire, otherwise - 'false'.
    *
    *@param warmupFlags Warmup flags for checking.
    *@param baseListenPort Base listen port to use during the checking.
    *@param localNetworkInterface IP address to bind for listen and outgoing test sockets.
    *
    * @note This call is thread-safe.
    */
    static bool checkWarmupFlags(int warmupFlags, unsigned short baseListenPort = 5000, const std::string & localNetworkInterface = "127.0.0.1");

    /**
    * Pre-fills session-level fields that are constant during the session's lifetime - SenderCompId, TargetCompId, SenderLocationId, TargetLocationID, SenderSubID, TargetSubID.
    *
    * @note This call is thread-safe.
    */
    void preFill(Message & msg) const;

    /**
    * Pre-fills the following fields in the message or messages batch for sending as is:
    * - Session-level fields that are constant during the session's lifetime - SenderCompId, TargetCompId, SenderLocationId, TargetLocationI, SenderSubID, TargetSubID.
    * - MsgSeqNum field in accordance with the session outgoing sequence number.
    * - SendingTime field.
    * - BodyLength and CheckSum fields.
    *
    * @note This call is thread-safe.
    */
    void preFill(FlatMessage & msg) const;
    void preFill(FlatMessageBatch & msgs) const;

    /**
    * Shutdowns the session.
    *
    * @note This call is thread-safe.
    */
    Session & shutdown();

    /**
    * Returns the text description of this session.
    *
    * @note This call is thread-safe.
    */
    operator const std::string & () const;

    /**
    * Returns the underlying storage Id.
    *
    * @note This call is thread-safe.
    */
    const std::string & storageId() const;

    /**
    * Flushes all internal buffers of the underlying storage.
    *
    * @note This call is thread-safe.
    */
    Session & flushSessionStorage();

    /**
    * Returns the counterparty host name.
    *
    * @note The method performs a DNS request for the first time.
    * Therefore, it can block the thread execution for a long time until the DNS request is completed.
    *
    * @note This call is thread-safe.
    */
    std::string counterpartyHost() const;

    /**
    * Returns the counterparty address.
    *
    * @note This call is thread-safe.
    */
    std::string counterpartyIpAddress() const;

    /**
    * Returns the counterparty port number.
    *
    * @note This call is thread-safe.
    */
    size_t counterpartyPort() const;

    /**
    * Returns Session's Custom Key.
    *
    * @note This call is thread-safe.
    */
    const std::string & customKey() const;

    /**
    * Returns the total number of bytes in the outbound queue.
    *
    * @note This call is thread-safe.
    */
    size_t outboundQueueBytes() const;

    /**
    * Returns the Heartbeat interval (in seconds).
    */
    int heartbeatIntervalSec() const;

    /**
    * Returns 'true' if inbound messages are logged, otherwise - 'false'.
    * By default, the value is 'true'.
    */
    bool logInboundMessages() const;

    /**
    * Option to log inbound messages.
    */
    Session & logInboundMessages(bool value);

    /**
    * Returns 'true' if outbound messages are logged, otherwise - 'false'.
    * By default, the value is 'true'.
    */
    bool logOutboundMessages() const;

    /**
    * Option to log outbound messages.
    */
    Session & logOutboundMessages(bool value);

    /**
    * Incoming message types to be filtered out from the logs.
    */
    typedef std::set<std::string> InboundMessageLogFilter;

    /**
    * Returns incoming message types to be filtered out from the logs.
    *
    * @note This call is thread-safe.
    */
    InboundMessageLogFilter inboundMessageLogFilter() const;

    /**
    * Sets incoming message types to be filtered out from the logs.
    *
    * @note This call is thread-safe.
    */
    Session & inboundMessageLogFilter(const InboundMessageLogFilter & filter);

    /**
    * Outgoing message types to be filtered out from the logs.
    */
    typedef std::set<std::string> OutboundMessageLogFilter;

    /**
    * Returns outgoing message types to be filtered out from the logs.
    *
    * @note This call is thread-safe.
    */
    OutboundMessageLogFilter outboundMessageLogFilter() const;

    /**
    * Sets outgoing message types to be filtered out from the logs.
    *
    * @note This call is thread-safe.
    */
    Session & outboundMessageLogFilter(const OutboundMessageLogFilter & filter);

    /**
    * Returns 'true' if outbound messages are logged before sending, otherwise - 'false'.
    * By default, the value is 'true'.
    *
    * @note This call is thread-safe.
    */
    bool logBeforeSending() const;

    /**
    * Option to switch on/off logging of outbound messages before/after sending.
    *
    * @note This call is thread-safe.
    */
    Session & logBeforeSending(bool value);

    /**
    * Returns the expected sequence number of the next incoming message.
    *
    * @note This call is thread-safe.
    */
    SequenceNumber inSeqNum() const;

    /**
    * Sets the expected sequence number of the next incoming message.
    *
    * @note This call is thread-safe.
    */
    Session & inSeqNum(SequenceNumber seqNum);

    /**
    * Returns the sequence number of the next outgoing message.
    *
    * @note This call is thread-safe.
    */
    SequenceNumber outSeqNum() const;

    /**
    * Sets the sequence number of the next outgoing message.
    *
    * @note This call is thread-safe.
    */
    Session & outSeqNum(SequenceNumber seqNum);

    /**
    * Represents unlimited number of messages to be requested in one Resend Request (MsgType=2) message.
    * Default value is 0.
    */
    static const unsigned int ResendRequestMaximumRangeNoLimit;

    /**
    * Sets the maximum number of messages to be requested in one Resend Request (MsgType=2) message.
    *
    * @see Session::ResendRequestMaximumRangeNoLimit.
    *
    * @param range Maximum number of messages to be requested in one Resend Request (MsgType=2) message. Cannot be negative.
    *
    * @note This call is thread-safe.
    */
    Session & resendRequestMaximumRange(int range);

    /**
    * Returns the maximum number of messages to be requested in one Resend Request (MsgType=2) message.
    * By default, the value is zero (no limit).
    *
    * @see Session::ResendRequestMaximumRangeNoLimit.
    *
    * @note This call is thread-safe.
    */
    int resendRequestMaximumRange() const;

    /**
    * Sets the number of sent messages that are available for resending on counterparty's Resend Request <2> message.
    *
    * @note This call is thread-safe.
    */
    Session & resendingQueueSize(size_t value);

    /**
    * Returns the number of sent messages that are available for resending on counterparty's Resend Request <2> message.
    * By default value is -1 that means that the corresponding Engine setting's value is used ('1000' by default).
    *
    * @note This call is thread-safe.
    */
    size_t resendingQueueSize() const;

    /**
    * Returns the session role.
    *
    * @note This call is thread-safe.
    */
    SessionRole::Enum role() const;

    /**
    * Returns the assigned value used to identify firm sending message (the SenderCompID (tag 49) field value in outgoing messages).
    *
    * @note This call is thread-safe.
    */
    const std::string & senderCompId() const;

    /**
    * Returns 'true' if the LastMsgSeqNumProcessed (tag 369) field is specified on every message sent, otherwise - 'false'.
    * By default, the option value is false.
    */
    bool specifyLastMsgSeqNumProcessed() const;

    /**
    * Option to specify the LastMsgSeqNumProcessed (tag 369) field on every message sent.
    * Useful for detecting a backlog with a counterparty.
    *
    * @note Option does not affect the FlatMessage send.
    */
    Session & specifyLastMsgSeqNumProcessed(bool specify);

    /**
    * Returns 'true' if updating of SendingTime is turn on for every message, otherwise - 'false'.
    * By default, the option value is true.
    */
    bool updateSendingTimeField() const;

    /**
    * Option to specify updating of SendingTime of every sent message.
    */
    Session & updateSendingTimeField(bool specify);

    /**
    * Sets the time format of SendingTime of every sent message.
    * By default, the YYYYMMDDHHMMSSMsec format is used.
    */
    Session & sendingTimeFormat(TimestampFormat::Enum format);

    /**
    * Returns the Assigned value used to identify receiving firm (the TargetCompID (tag 56) field value in outgoing messages).
    *
    * @note This call is thread-safe.
    */
    const std::string & targetCompId() const;

    /**
    * Instance of the FIX dictionary or standard FIX messages dictionary which is used by the session.
    */
    Dictionary dictionary() const;

    /**
    * Returns the CPU affinity of the receiving thread.
    */
    const OnixS::Threading::CpuIndexes & receivingThreadAffinity() const;

    /**
    * Sets the CPU affinity of the receiving thread.
    */
    Session & receivingThreadAffinity(const OnixS::Threading::CpuIndexes & cpuIndexes);

    /**
    * Sets the CPU affinity of the receiving thread to a CPU.
    */
    Session & receivingThreadAffinity(const OnixS::Threading::CpuIndex cpuIndex);

    /**
    * Returns the CPU affinity of the sending thread.
    */
    const OnixS::Threading::CpuIndexes & sendingThreadAffinity() const;

    /**
    * Sets the CPU affinity index of the sending thread.
    */
    Session & sendingThreadAffinity(const OnixS::Threading::CpuIndexes & cpuIndexes);

    /**
    * Sets the CPU affinity index of the sending thread a CPU.
    */
    Session & sendingThreadAffinity(const OnixS::Threading::CpuIndex cpuIndex);

    /**
    * Represents undefined value of priority and policy.
    */
    static const int UndefinedPriorityAndPolicy;

    /**
    * Returns the priority of the receiving thread.
    */
    int receivingThreadPriority() const;

    /**
    * Sets the priority of the receiving thread.
    */
    Session & receivingThreadPriority(int priority);

    /**
    * Returns the priority of the sending thread.
    */
    int sendingThreadPriority() const;

    /**
    * Sets the priority of the sending thread.
    */
    Session & sendingThreadPriority(int priority);

    /**
    * Returns the scheduling policy of the receiving thread.
    */
    int receivingThreadPolicy() const;

    /**
    * Sets the scheduling policy of the receiving thread.
    */
    Session & receivingThreadPolicy(int policy);

    /**
    * Returns the scheduling policy of the sending thread.
    */
    int sendingThreadPolicy() const;

    /**
    * Sets the scheduling policy of the sending thread.
    */
    Session & sendingThreadPolicy(int policy);

    /**
    * Returns the sent message if it can be found by the given message sequence number, otherwise - NULL.
    * 
    * @note The returned message is owned by the application and should be released after usage.
    *
    * @note This call is thread-safe.
    */
    Message * findSentMessage(SequenceNumber messageSequenceNumber);
    FlatMessage * findSentFlatMessage(SequenceNumber messageSequenceNumber);

    /**
    * Returns an array of sent messages if it can be found by the given message sequence number range, otherwise - empty array.
    * 
    * @note The returned messages are owned by the application and should be released after usage.
    *
    * @note This call is thread-safe.
    */
    MsgBatchTraits<Message>::MsgBatchType findSentMessages(SequenceNumber beginSequenceNumber, SequenceNumber endSequenceNumber);
    MsgBatchTraits<FlatMessage>::MsgBatchType findSentFlatMessages(SequenceNumber beginSequenceNumber, SequenceNumber endSequenceNumber);

    /**
    * When the message gap is detected the "Resend Request" FIX Message is sent and Session state is changed to "AwaitReplyOnResendRequest".
    * By default in this state the incoming new messages (without the PossDupFlag (tag #43) flag) are ignored because we expect them to be re-sent later again with the PossDupFlag flag.
    *
    * This property allows to change this behavior and report the new messages anyway.
    *
    * @note In this mode messages could be reported out of the original order: e.g. MsgSeqNum could be: 3 (original), 4 (original), 2 (PossDupFlag='Y'), 3 (PossDupFlag='Y'), 4 (PossDupFlag='Y')
    * and some messages could be received two times: first time without PossDupFlag='Y' and second time - with this flag.
    */
    Session & reportNewMessagesWhileWaitingForMissedMessages(bool report);

    /**
     * Returns 'true' if the new messages are reported even when the message gap is detected and the reply on the "Resend Request" message is expected, otherwise - 'false'.
     */
    bool reportNewMessagesWhileWaitingForMissedMessages() const;

    /**
    * By default the "Resend Request" message is sent only once - when the first gap is detected.
    * This property allows to change this behavior and send the "Resend Request" message on each detected message sequence number gap.
    */
    Session & sendResendRequestOnEachMessageGap(bool send);

    /**
     * Returns 'true' if the "Resend Request" message is sent on each detected message sequence number gap, otherwise - 'false'.
     */
    bool sendResendRequestOnEachMessageGap() const;

    /**
     * By default the "Resend Request" message requests all messages begin from the first missed one.
     * This property allows to change this behavior and request only missed messages.
     *
     * @note This method can be called only when the session is disconnected.
     */
    Session & requestOnlyMissedMessages(bool request);

    /**
     * Returns 'true' if the "Resend Request" message requests only missed messages, otherwise - 'false'.
     */
    bool requestOnlyMissedMessages() const;

    /**
    * By default if the "Session Level Reject" message is received in replay to the "Resend Request" then this is considered as a serious problem and the FIX connection will be closed.
    * This property allows to change this behavior and consider the "Session Level Reject" on the "Resend Request" as the "Sequence Reset Gap Fill" message.
    */
    Session & considerRejectOnResendRequestAsGapFill(bool consider);

    /**
     * Returns 'true' if the "Reject" on the "Resend Request" is considered as the "Sequence Reset Gap Fill" message, otherwise - 'false'.
     */
    bool considerRejectOnResendRequestAsGapFill() const;

    /**
    * By default if the incoming message has a sequence number less than expected and the PossDupFlag is not set, it indicates
    * a serious error and leads to FIX connection closing.
    * This property allows to change this behavior and consider the sequence number of the incoming message, which less than expected, as an expected one.
    */
    Session & ignoreLessThanExpectedSequenceNumber(bool ignore);

    /**
     * Returns 'true' if the sequence number of the incoming message, which less than expected, is considered as an expected one, otherwise - 'false'.
     */
    bool ignoreLessThanExpectedSequenceNumber() const;

    /**
    * Option to automatically reset the local sequence numbers to 1 during every logon.
    */
    Session & resetLocalSequenceNumbersOnLogon(bool reset);

    /**
     * Returns 'true' if local sequence numbers are reset automatically to 1 during every logon, otherwise - 'false'.
     */
    bool resetLocalSequenceNumbersOnLogon() const;

    /**
     * If requestOnlyMissedMessages option is true and the sequence number of an incoming FIX message
     * greater that expected then the resend functionality is run and this incoming message is stored
     * in the incoming message gap queue for further processing.
     * This property allows to set maximum size of that queue.
     */
    Session & incomingMessageGapQueueMaximumSize(size_t maxSize);

    /**
     * Returns maximum size of the incoming message gap queue.
     * By default, the value equal to 1000.
     */
    size_t incomingMessageGapQueueMaximumSize() const;

    /**
    * Registers the Session listener.
    *
    * @throw Exception if the listener is already registered.
    */
    Session & registerListener(ISessionListener * listener);

    /**
    * Un-registers the Session listener.
    */
    Session & unregisterListener(ISessionListener * listener);

    /**
    * Un-registers all Session listener.
    */
    Session & unregisterAllListeners();

    /**
    * Backups the current log files and resets the local sequence numbers to 1.
    *
    * @note This method can be called only when the session is disconnected.
    *
    * @note This call is thread-safe.
    */
    Session & resetLocalSequenceNumbers();

    /**
    * Sends a Logon message with the ResetSeqNumFlag set.
    *
    * @note This call is thread-safe.
    */
    Session & resetSeqNumViaLogonExchange();

    /**
     * Returns the SenderSubID (tag 50) field values for all outgoing messages.
     *
     * @note This call is thread-safe.
     */
    std::string senderSubId() const;

    /**
    * Sets the SenderSubID (tag 50) field values for all outgoing messages.
    *
    * @note This call is thread-safe.
    */
    Session & senderSubId(const std::string & value);

    /**
    * Returns the TargetSubID (tag 57) field values for all outgoing messages.
    *
    * @note This call is thread-safe.
    */
    std::string targetSubId() const;

    /**
    * Sets the TargetSubID (tag 57) field values for all outgoing messages.
    *
    * @note This call is thread-safe.
    */
    Session & targetSubId(const std::string & value);

    /**
    * Returns the SenderLocationID (tag 142) field values for all outgoing messages.
    *
    * @note This call is thread-safe.
    */
    std::string senderLocationId() const;

    /**
    * Sets the SenderLocationID (tag 142) field values for all outgoing messages.
    *
    * @note This call is thread-safe.
    */
    Session & senderLocationId(const std::string & value);

    /**
    * Returns the TargetLocationID (tag 143) field values for all outgoing messages.
    *
    * @note This call is thread-safe.
    */
    std::string targetLocationId() const;

    /**
    * Sets the TargetLocationID (tag 143) field values for all outgoing messages.
    *
    * @note This call is thread-safe.
    */
    Session & targetLocationId(const std::string & value);

    /**
    * Options to turn on/off incoming message sequence numbers validation.
    */
    Session & validateSequenceNumbers(bool value);

    /**
    * Returns the current status of incoming message sequence numbers validation.
    * By default the option value is true.
    */
    bool validateSequenceNumbers() const;

    /**
    * Returns the thread name suffix for receiving (R:threadNameSuffix) and sending (S:threadNameSuffix) threads.
    *
    * @note This call is thread-safe.
    */
    std::string threadNameSuffix() const;

    /**
    * Sets the thread name suffix for receiving ("R:threadNameSuffix") and sending ("S:threadNameSuffix") threads.
    **
    * If threadNameSuffix is not specified, it is set by default to ("R:senderCompId-targetCompId")("S:senderCompId-targetCompId").
    **
    * @note This method can be called only when the session is disconnected.
    * @throw Exception if the session state is not Disconnected.
    *
    * @note This call is thread-safe.
    */
    Session & threadNameSuffix(const std::string & value);

    /**
    * Sends the Test Request (MsgType 1) message.
    * If the timeout is specified, the method blocks until the heartbeat message is received from the counterparty or timeout ended.
    * 
    * @param testReqId The identifier included in Test Request (MsgType 1) message to be returned in resulting Heartbeat (MsgType 0) message from the counterparty.
    * @param timeout The maximum interval to wait until the reply is received from the counterparty.
    *
    * @note This call is thread-safe.
    */
    Session & sendTestRequest(const std::string & testReqId = "", const TimeSpan & timeout = TimeSpan::zero());

    /**
    * Sends the Resend Request (MsgType 2) message.
    *
    * @note Normally, "Resend Request" message is sent automatically. This method allows to simulate a sequence gap by sending this message manually.
    * This can be needed in some venue specific cases. This method should not be used in the normal work.
    *
    * @param beginSeqNumber Begin sequence number of the first requested message in the range.
    *
    * @note This call is thread-safe.
    */
    Session & sendResendRequest(SequenceNumber beginSeqNumber);

    /**
    * Sends the Reject (MsgType 3) message.
    *
    * @param refSeqNumber MsgSeqNum of rejected message.
    * @param text Message to explain the reason for rejection.
    *
    * @note This call is thread-safe.
    */
    Session & sendReject(SequenceNumber refSeqNumber, const std::string & text);

    /**
    * Returns the time when logical session was created or last sequence number reset operation was performed.
    * Originating value is extracted from attached storage using ISessionStorage::sessionCreationTime() method.
    *
    * @note This call is thread-safe.
    */
    Timestamp creationTime() const;

    /**
    * Returns the session string presentation.
    *
    * @note This call is thread-safe.
    */
    std::string toString() const;

    /**
    * Represents invalid value of socket handle.
    */
    static const OnixS::Sockets::Handle InvalidSocketHandle;

    /**
    * Returns the socket handle which the session uses to transmit FIX data.
    *
    * @note This call is thread-safe.
    */
    OnixS::Sockets::Handle socketHandle();

    /**
    * Additional options, which should be set to the session socket when it is created.
    * For initiator sessions, options are set before socket connect(..) call.
    * For acceptor sessions, options are set after socket accept(..) call.
    */
    Session & socketOptions(const OnixS::Sockets::SocketOptions & options);

    /**
    * Inbound and outbound messages, session's state data are stored in this directory.
    *
    * @note This method can be called only when the session is disconnected.
    * @throw Exception if the session state is not Disconnected.
    *
    * @note This call is thread-safe.
    */
    Session & logDirectory(const std::string & value);

    /**
    * Inbound and outbound messages, session's state data are stored in this directory.
    *
    * @note This call is thread-safe.
    */
    const std::string & logDirectory() const;

    /**
    * Sets the timeout during which counterparty should send a reply to the "Resend Request" message.
    * If a counterparty does not reply during this timeout, then the ISessionListener::onWarning is called.
    * By default, the resend request timeout equal to zero, which means an infinite timeout.
    *
    * @note The resend timeout is checked when an incoming message is received or when the receive timeout is elapsed.
    * Therefore, the actual timeout can be greater than the specified one or can be rounded to the value equal to the heartbeat interval + reasonable transmission time.
    *
    * @note This call is thread-safe.
    */
    Session & resendTimeout(const TimeSpan & timeout);

    /**
    * Returns the timeout during which counterparty should send a reply to the "Resend Request" message.
    *
    * @note This call is thread-safe.
    */
    TimeSpan resendTimeout() const;

    /**
    * Collection of scrambled tags.
    */
    typedef std::vector<Tag> ScrambledFields;

    /**
    * Sets scrambled fields in the Logon(A) message, in the session storage, for security reasons.
    * 
    * @note This call is thread-safe.
    */
    Session & scrambleLogonFields(const ScrambledFields & fields);

    /**
     * Returns scrambled fields in the Logon(A) message.
     */
    ScrambledFields scrambleLogonFields() const;

    /**
    * Schedule the memory usage optimization.
    * The session will perform the actual memory usage optimization after receiving and processing the next incoming message.
    */
    void scheduleShrinkToFit();

    /**
    * HTTP proxy settings.
    */
    struct ProxySettings
    {
        ProxySettings()
            :host(), port(), username(), password()
        {}

        ProxySettings(const std::string & proxyHost, int proxyPort, const std::string & proxyUsername = std::string(), const std::string & proxyPassword = std::string())
            :host(proxyHost), port(proxyPort), username(proxyUsername), password(proxyPassword)
        {}

        std::string host;
        int port;
        std::string username;
        std::string password;
    };

    /**
    * Sets HTTP proxy settings.
    */
    Session & proxySettings(const ProxySettings & settings);

    /**
    * Returns HTTP proxy settings.
    */
    ProxySettings proxySettings() const;

    /**
    * Returns the session message mode.
    */
    MessageMode::Enum messageMode() const;

    /**
    * Sets the session message mode.
    */
    void messageMode(MessageMode::Enum mode);

    struct Impl; ///< Implementation details.

private:
    void init(
        const std::string & senderCompId,
        const std::string & targetCompId,
        const Dictionary & dictionary,
        ISessionListener * listener,
        bool keepSequenceNumbersAfterLogout,
        SessionStorageType::Enum storageType,
        ISessionStorage * storage,
        const std::string & customSessionKey,
        ISessionReactor * reactor);

    Impl * impl_;

    friend class Engine::Impl;
};

/// Stream output.
ONIXS_FIXENGINE_API
std::ostream & operator << (std::ostream & os, const Session & session);
}
}