EngineSettings.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 <vector>
#include <string>

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

namespace OnixS {
namespace System {
class ISettings;
}
}

namespace OnixS {
namespace FIX {
class Engine;

/// Listen ports.
typedef std::vector<int> ListenPorts;

/// Local interfaces
typedef std::string LocalNetworkInterface;
typedef std::vector<LocalNetworkInterface> LocalNetworkInterfaces;

/// FIX Engine settings.
class ONIXS_FIXENGINE_API EngineSettings
{
public:
    /// The constructor.
    EngineSettings();

    /// The constructor to create the EngineSettings from a Configuration string.
    explicit EngineSettings(const std::string & configuration);

    /// The copy constructor.
    EngineSettings(const EngineSettings &);

    /// Loads Engine settings from a Configuration file.
    void loadFromConfigFile(const std::string & configFile);

    /// The destructor.
    ~EngineSettings();

    /// The assignment.
    EngineSettings & operator = (const EngineSettings &);

    /// The option to create the FIX Engine log file.
    EngineSettings & createEngineLogFile(bool value);

    /// The option to create the FIX Engine log file.
    bool createEngineLogFile() const;

    /// Specifies the path(s) to the XML file(s) with the description of the FIX Dictionary(s).
    ///
    /// @note More than one file could be specified. The symbol '|' is used as the file name delimiter.
    EngineSettings & dictionaryFile(const std::string & value);

    /// Returns the path to the XML file with the description of the FIX Dictionary(s).
    const std::string & dictionaryFile() const;

    /// Specifies the plain text string with a description of the FIX dialect.
    EngineSettings & dialectString(const std::string & value);

    /// Returns the string that contains the plain text string with the description of the FIX dialect.
    const std::string & dialectString() const;

    /// The FIX Engine listens on this port for incoming "plain text" connections.
    ///
    /// @note If '0' then only session-initiators can be created.
    /// @note  If '-1' then the telecommunication level is disabled and only message parsing/assembling can be used.
    EngineSettings & listenPort(int value);

    /// The FIX Engine listens on this port for incoming "plain text" connections.
    ///
    /// @note If '0' then only session-initiators can be created.
    /// @note  If '-1' then the telecommunication level is disabled and only message parsing/assembling can be used.
    int listenPort() const;

    /// Set listen ports.
    EngineSettings & listenPorts(const ListenPorts & value);

    /// Returns listen ports.
    const ListenPorts & listenPorts() const;

    /// The FIX Engine listens on these local interfaces for incoming "plain text" connections.
    const LocalNetworkInterfaces & localNetworkInterface() const;

    /// Sets local interfaces where the engine listen for incoming connections.
    /// Each local interface specification could specify the local IP address and port. For instance, "localhost" and "192.168.0.1:4501" are valid values. When
    /// a local interface specification contains the same port as specified at listenPort settings the listening appears only on the interface and port specified
    /// at the localInterface setting.
    /// @note At least a single listen port have to be specified to make the engine able to use this setting.
    EngineSettings & localNetworkInterface(const LocalNetworkInterfaces &);

    /// Sets the local interface where the engine listen for incoming connections.
    /// Each local interface specification could specify the local IP address and port. For instance, "localhost" and "192.168.0.1:4501" are valid values. When
    /// a local interface specification contains the same port as specified at listenPort settings the listening appears only on the interface and port specified
    /// at the localInterface setting.
    /// @note At least a single listen port have to be specified to make the engine able to use this setting.
    EngineSettings & localNetworkInterface(const LocalNetworkInterface &);

    /// Returns the default mode for outbound and incoming connections.
    ThreadingModel::Enum threadingModel() const;

    /// Sets the default mode for outbound and incoming connections.
    EngineSettings & threadingModel(ThreadingModel::Enum value);

    /// Returns the default mode for using a spin lock.
    bool useSpinLock() const;

    /// Returns the default mode for using a spin lock.
    EngineSettings & useSpinLock(bool value);

    /// Sets the thread pool size.
    EngineSettings & threadPoolSize(int size);

    /// Returns the thread pool size.
    int threadPoolSize() const;

    /// Specifies the path to the license file.
    ///
    /// @deprecated This method is deprecated, the OnixS::FIX::EngineSettings::licenseStore(const std::string&) should be used instead.
    EngineSettings & licenseFile(const std::string & value);

    /// Returns the path to the license file.
    ///
    /// @deprecated This method is deprecated, the OnixS::FIX::EngineSettings::licenseStore() should be used instead.
    const std::string & licenseFile() const;

    /// Specifies the path to the license directory.
    ///
    /// @note More than one license store could be specified. The symbol '|' is used as the license store delimiter.
    EngineSettings & licenseStore(const std::string & value);

    /// Returns the path to the license directory.
    const std::string & licenseStore() const;

    /// Specifies the string of the license content.
    EngineSettings & licenseString(const std::string & value);

    /// Returns the string of the license content.
    const std::string & licenseString() const;

    /// Returns the number of days to alert before the license expiration.
    unsigned licenseAlertingDaysBeforeExpiration();

    /// Sets the number of days to alert before the license expiration.
    /// If the amount of remaining license days is less or equal to this number
    /// then the warning will be reported to the FIX Engine's log and IEngineListener::onWarning callback will be invoked.
    /// The verification is performed during the following events: the FIX Engine initialization, Session::logonAsAcceptor and Session::logonAsInitiator calls.
    EngineSettings & licenseAlertingDaysBeforeExpiration(unsigned value);

    /// Inbound and outbound messages, session's state data and the FIX Engine log file (FixEngineLog.txt) are stored in this directory.
    EngineSettings & logDirectory(const std::string & value);

    /// Inbound and outbound messages, session's state data and the FIX Engine log file (FixEngineLog.txt) are stored in this directory.
    const std::string & logDirectory() const;

    /// Returns the FIX Engine log file name
    const std::string & logFileName() const;

    /// Sets the FIX Engine log file name
    EngineSettings & logFileName(const std::string & value);

    /// Returns 'true' if inbound messages are logged, otherwise - 'false'.
    bool logInboundMessages() const;

    /// The option to log inbound messages.
    EngineSettings & logInboundMessages(bool value);

    /// Returns 'true' if outbound messages are logged, otherwise - 'false'.
    bool logOutboundMessages() const;

    /// The option to log outbound messages.
    EngineSettings & logOutboundMessages(bool value);

    /// Returns 'true' if outbound messages are logged before sending, otherwise - 'false'.
    bool logBeforeSending() const;

    /// The option to switch on/off logging of outbound messages before/after sending.
    EngineSettings & logBeforeSending(bool value);

    /// Gets the usage of the local time in FIX Engine events and log files.
    bool localTimeUsage() const;

    /// Specifies the usage of the local time in FIX Engine events and log files.
    /// @param value If it is true - the local time is used, if it is false - the UTC time is used.
    EngineSettings & localTimeUsage(bool value);

    /// The option to process the DeliverToCompID (tag 128) flag.
    EngineSettings & processDeliverToCompId(bool value);

    /// The option to process the DeliverToCompID  (tag 128) flag.
    bool processDeliverToCompId() const;

    /// The reasonable transmission time as % from the HeartBtInt value.
    ///
    /// When either end of the connection has not received any data for (HeartBtInt * (100 + ReasonableTransmissionTime)/100) seconds,
    /// it will transmit a Test Request message.
    ///
    /// If there is still no a Heartbeat message received after (HeartBtInt * (100 + ReasonableTransmissionTime)/100) seconds
    /// then the connection should be considered lost and a corrective action should be initiated.
    ///
    /// @see If you need to change this option for the separate session, please use
    /// the OnixS::FIX::Session::setReasonableTransmissionTime(int).
    EngineSettings & reasonableTransmissionTime(int value);

    /// The reasonable transmission time as % from HeartBtInt value.
    ///
    /// When either end of the connection has not received any data for (HeartBtInt * (100 + ReasonableTransmissionTime)/100) seconds,
    /// it will transmit a Test Request message.
    ///
    /// If there is still no a Heartbeat message received after (HeartBtInt * (100 + ReasonableTransmissionTime)/100) seconds
    /// then the connection should be considered lost and a corrective action should be initiated.
    ///
    /// @see You also can get a value of this option for separate session using
    /// the OnixS::FIX::Session::getReasonableTransmissionTime().
    int reasonableTransmissionTime() const;

    /// Sets the number of attempts to restore the FIX connection.
    EngineSettings & reconnectAttempts(int value);

    /// Returns the number of attempts to restore the FIX connection.
    int reconnectAttempts() const;

    /// Sets the time interval between the attempts to restore the FIX connection (in seconds).
    EngineSettings & reconnectInterval(int value);

    /// Returns the time interval between the attempts to restore the FIX connection (in seconds).
    int reconnectInterval() const;

    /// Sets the number of sent messages that are available for the resending on the counterparty's Resend Request <2> message.
    EngineSettings & resendingQueueSize(size_t value);

    /// Returns the number of sent messages that are available for the resending on the counterparty's Resend Request <2> message.
    /// The zero value means that sent messages are not available for the resending.
    /// The value cannot be negative.
    size_t resendingQueueSize() const;

    /// Sets the maximum number of messages to be requested in one Resend Request (MsgType=2) message.
    EngineSettings & resendRequestMaximumRange(int value);

    /// Returns the maximum number of messages to be requested in one Resend Request (MsgType=2) message.
    int resendRequestMaximumRange() const;

    /// Specifies the usage of the operating system default RecvBuffer size.
    static const int UseDefaultReceiveBufferSize;

    /// Returns the size of the TCP buffer allocated to the FIX connection for receiving data.
    /// If '-1' then the default operating system value is used.
    int receiveBufferSize() const;

    /// Sets the size of the TCP buffer allocated to the FIX connection for receiving data.
    /// If '-1' then the default operating system value is used.
    EngineSettings & receiveBufferSize(int value);

    /// Specifies the usage of the operating system default SendBuffer size.
    static const int UseDefaultSendBufferSize;

    /// Returns the size of the TCP buffer allocated to the FIX connection for sending data.
    /// If '-1' then the default operating system value is used.
    int sendBufferSize() const;

    /// Sets the size of the TCP buffer allocated to the FIX connection for sending data.
    /// If '-1' then the default operating system value is used.
    EngineSettings & sendBufferSize(int value);

    /// Returns the value of the option to send the Logout message before dropping the telecommunication link in case of Exception during the processing of incoming FIX message.
    EngineSettings & sendLogoutOnException(bool value);

    /// The option to send the Logout message before dropping the telecommunication link in case of an Exception during the processing of an incoming FIX message.
    bool sendLogoutOnException() const;

    /// Returns the value of the option to send the Logout message before dropping the telecommunication link in case of an invalid logon attempt.
    EngineSettings & sendLogoutOnInvalidLogon(bool value);

    /// The option to send the Logout message before dropping the telecommunication link in case of an invalid logon attempt.
    bool sendLogoutOnInvalidLogon() const;

    /// Sets the path to the SSL certificate file in the (Privacy Enhanced Mail) Base64 encoded (.pem) format.
    EngineSettings & sslCertificateFile(const std::string & value);

    /// Returns the path to the SSL certificate file in the (Privacy Enhanced Mail) Base64 encoded (.pem) format.
    const std::string & sslCertificateFile() const;

    /// Sets the path to the SSL private key file in the (Privacy Enhanced Mail) Base64 encoded (.pem) format.
    EngineSettings & sslPrivateKeyFile(const std::string & value);

    /// Returns the path to the SSL private key file in the (Privacy Enhanced Mail) Base64 encoded (.pem) format.
    const std::string & sslPrivateKeyFile() const;

    /// Set the password to load private keys that are protected by a password.
    EngineSettings & sslPrivateKeyPassword(const Cryptography::SecureString & value);

    /// Returns the password to load private keys that are protected by a password.
    Cryptography::SecureString sslPrivateKeyPassword() const;

    /// The FIX Engine listens on this port for incoming SSL connections.
    ///
    /// @note If '0' then only session-initiators can be created.
    /// @note  If '-1' then the telecommunication level is disabled and only message parsing/assembling can be used.
    EngineSettings & sslListenPort(int value);

    /// The FIX Engine listens on this port for incoming SSL connections.
    ///
    /// @note If '0' then only session-initiators can be created.
    /// @note  If '-1' then the telecommunication level is disabled and only message parsing/assembling can be used.
    int sslListenPort() const;

    /// Sets SSL listen ports.
    EngineSettings & sslListenPorts(const ListenPorts & value);

    /// Returns SSL listen ports.
    const ListenPorts & sslListenPorts() const;

    /// The FIX Engine listens on these local interfaces for incoming SSL connections.
    const LocalNetworkInterfaces & sslLocalInterface() const;

    /// Sets local interfaces where the engine listen for incoming SSL connections.
    /// @note At least a single SSL-listen port have to be specified to make the engine able to use this setting.
    EngineSettings & sslLocalInterface(const LocalNetworkInterfaces &);

    /// Set the option to request client certificates and perform the certificate verification.
    EngineSettings & sslVerifyPeer(bool verify);

    /// Returns the option to request client certificates and perform the certificate verification.
    bool sslVerifyPeer() const;

    /// Sets the path to the trusted certification authority certificate file in the (Privacy Enhanced Mail) Base64 encoded (.pem) format.
    EngineSettings & sslCaFile(const std::string & value);

    /// Returns the path to trusted certification authority certificate file in the (Privacy Enhanced Mail) Base64 encoded (.pem) format.
    const std::string & sslCaFile() const;

    /// Sets the CPU affinity of Engine service threads.
    EngineSettings & serviceThreadAffinity(const OnixS::Threading::CpuIndexes & cpuIndexes);

    /// Sets the CPU affinity of Engine service threads.
    EngineSettings & serviceThreadAffinity(const OnixS::Threading::CpuIndex cpuIndex);

    /// Returns the CPU affinity of Engine service threads.
    const OnixS::Threading::CpuIndexes & serviceThreadAffinity();

    /// Returns the priority of Engine service threads.
    int serviceThreadPriority() const;

    /// Sets the priority of Engine service threads.
    EngineSettings & serviceThreadPriority(int priority);

    /// Returns the policy of Engine service threads.
    int serviceThreadPolicy() const;

    /// Sets the policy of Engine service threads.
    EngineSettings & serviceThreadPolicy(int policy);

    /// Sets the option to improve the latency at the expense of the message throughput (TCP_NODELAY).
    EngineSettings & tcpNoDelayOption(bool value);

    /// Gets the option to improve the latency at the expense of the message throughput (TCP_NODELAY).
    bool tcpNoDelayOption() 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 Heartbeat interval).
    EngineSettings & receiveSpinningTimeout(int value);

    /// Gets the current receive spinning timeout value (in microseconds).
    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 Heartbeat interval).
    EngineSettings & sendSpinningTimeout(int value);

    /// Gets the current send spinning timeout value (in microseconds).
    int sendSpinningTimeout() const;

    /// Sets the message grouping option:
    /// Value 0 means the default grouping  - the messages will be tried to send ASAP and pending messages (if any) will be grouped till reaching of the TCP buffer size.
    /// Value 1 means the messages will be sent ASAP and never will be grouped.
    /// Value 2 (or greater) means the messages will be sent ASAP and pending messages will be grouped maximum by 2 (or greater).
    EngineSettings & messageGrouping(unsigned value);

    /// Gets the message grouping option.
    unsigned messageGrouping() const;

    /// Gets the segment size for the file based session storage.
    unsigned long long fileBasedStorageSegmentSize() const;

    /// Sets the segment size for the file based session storage.
    /// @param value The maximum size of the single segment (single file) of the storage, in bytes.
    EngineSettings & fileBasedStorageSegmentSize(unsigned long long value);

    /// Gets the log queue maximum size of the asynchronous session storage.
    unsigned asyncFileBasedStorageQueueMaxSize() const;

    /// Sets the log queue maximum size of the asynchronous session storage.
    EngineSettings & asyncFileBasedStorageQueueMaxSize(unsigned value);

    /// Sets the CPU affinity of asynchronous session storage threads.
    EngineSettings & asyncFileBasedStorageThreadAffinity(const OnixS::Threading::CpuIndexes & cpuIndexes);

    /// Sets the CPU affinity of asynchronous session storage threads.
    EngineSettings & asyncFileBasedStorageThreadAffinity(const OnixS::Threading::CpuIndex cpuIndex);

    /// Returns the CPU affinity of asynchronous session storage threads.
    const OnixS::Threading::CpuIndexes & asyncFileBasedStorageThreadAffinity();

    /// Gets mode of the file based storage integrity errors checking. Valuable only when the value of fileBasedStorageSegmentSize != 0.
    bool ignoreFileBasedStorageIntegrityErrors() const;

    /// Sets mode of the file based storage integrity errors checking. Valuable only when the value of fileBasedStorageSegmentSize != 0.
    /// @param value The mode of checking: true - ignore errors and create a new storage, false - throw an exception.
    EngineSettings & ignoreFileBasedStorageIntegrityErrors(bool value);

    /// Gets the option to specify the ApplVerID(1128) tag in all application FIX messages when a FIX protocol version FIX 5.0 and above is used.
    bool specifyApplVerIdField() const;

    /// Sets the option to specify the ApplVerID(1128) tag in all application FIX messages when a FIX protocol version FIX 5.0 and above is used.
    EngineSettings & specifyApplVerIdField(bool value);

    /// Gets the option to specify the LastMsgSeqNumProcessed (tag=369) field on every message sent. Useful for detecting a backlog with a counterparty.
    bool specifyLastMsgSeqNumProcessed() const;

    /// Sets the option to specify the LastMsgSeqNumProcessed (tag=369) field on every message sent. Useful for detecting a backlog with a counterparty.
    EngineSettings & specifyLastMsgSeqNumProcessed(bool value);

    /// When the message gap is detected the "Resend Request" FIX Message is sent and the 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.
    bool reportNewMessagesWhileWaitingForMissedMessages() const;

    /// Sets the option to report new messages while waiting for missed messages.
    EngineSettings & reportNewMessagesWhileWaitingForMissedMessages(bool value);

    /// Gets the expected incoming FIX message size. The value represents an average FIX message size that is expected to be received by the session during the lifetime.
    /// It is used as a hint for the optimization of the deserialization of large FIX messages with a lot of repeating groups.
    ///
    /// @note The large value of the setting can increase the memory consumption by the incoming `Message` object,
    /// so try to increase the value only in case of a latency degradation of the large incoming FIX messages deserialization.
    int expectedIncomingMessageSize() const;

    /// Sets the expected incoming FIX message size.
    EngineSettings & expectedIncomingMessageSize(int value);

    /// Sets the option to scramble fields in the Logon(A) message, in the session storage and the FIX Engine log, for security reasons.
    EngineSettings & scrambleLogonFields(const Session::ScrambledFields & fields);

    /// Gets scrambled fields in the Logon(A) message.
    Session::ScrambledFields scrambleLogonFields() const;

    /// Sets the send queue maximum size in bytes.
    EngineSettings & sendQueueMaxSize(size_t size);

    /// Gets the send queue maximum size in bytes.
    size_t sendQueueMaxSize() const;

    /// Sets the timeout (in seconds) between an incoming TCP connection is detected and the first Logon message is received.
    /// If the first Logon message is not received during this timeout + reasonable transmission time, the connection will be closed.
    EngineSettings & firstLogonTimeout(unsigned timeout);

    /// Gets the first Logon timeout.
    unsigned firstLogonTimeout() const;

    /// Gets the option to validate the presence of unknown FIX messages (messages that do not belong to the message in accordance with the FIX protocol or its FIX Dictionary).
    bool validateUnknownMessages() const;

    /// Sets the option to validate the presence of unknown FIX messages (messages that do not belong to the message in accordance with the FIX protocol or its FIX Dictionary).
    EngineSettings & validateUnknownMessages(bool);

    /// Gets the option to validate the presence of unknown fields (fields that do not belong to the message in accordance with the FIX protocol or its FIX Dictionary.
    bool validateUnknownFields() const;

    /// Sets the option to validate the presence of unknown fields (fields that do not belong to the message in accordance with the FIX protocol or its FIX Dictionary.
    EngineSettings & validateUnknownFields(bool);

    /// Gets the option to validate the presence of required fields in inbound and outbound messages.
    bool validateRequiredFields() const;

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

    /// Gets the option to validate the field values of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
    bool validateFieldValues() const;

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

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

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

    /// Gets the option to validate the repeating group size of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
    bool validateRepeatingGroupEntryCount() const;

    /// Sets the option to validate the repeating group size of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
    EngineSettings & validateRepeatingGroupEntryCount(bool);

    /// Gets the option to validate the repeating group leading tag of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
    bool validateRepeatingGroupLeadingTag() const;

    /// Sets the option to validate the repeating group leading tag of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
    EngineSettings & validateRepeatingGroupLeadingTag(bool);

    /// Gets the option to validate the duplicated field.
    bool validateDuplicatedField() const;

    /// Sets the option to validate the duplicated field.
    EngineSettings & validateDuplicatedField(bool);

    /// Gets the option to validate the checksum of incoming messages.
    bool validateChecksum() const;

    /// Sets the option to validate the checksum of incoming messages.
    EngineSettings & validateChecksum(bool);

    /// The heartbeat resolution enum.
    enum HeartbeatResolution
    {
        // The heartbeat is measured in deciseconds.
        DecisecondsHeartbeatResolution = 100,

        // The heartbeat is measured in seconds.
        SecondsHeartbeatResolution = 1000
    };

    /// Sets the heartbeat resolution.
    /// @note This setting should be used only to speed up heartbeat related Unit Tests.
    EngineSettings & heartbeatResolution(HeartbeatResolution resolution);

    /// Gets the heartbeat resolution.
    HeartbeatResolution heartbeatResolution() const;

private:
    friend class Engine;

    const OnixS::System::ISettings & settings() const;

    struct Implementation;
    Implementation * impl;
};
}
}