FAST.h

Go to the documentation of this file.

#pragma once
/*
* 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.
*/

#include <string>
#include <vector>
#include <map>

#include <OnixS/FIXEngine/ABI.h>
#include <OnixS/FIXEngine/FIX/Tag.h>
#include <OnixS/FIXEngine/FIX/ProtocolVersion.h>
#include <OnixS/FIXEngine/FIX/InputDataTraits.h>
#include <OnixS/FIXEngine/Sockets/Definitions.h>

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

namespace FAST {
/// Encodes FIX messages into FAST representation.
class ONIXS_FIXENGINE_API Encoder
{
public:
    /// Creates a FIX to FAST Encoder.
    ///
    /// @param xmlTemplates XML-based FAST templates.
    /// @param fixVersion FIX Protocol version.
    /// @param encodeEachMessageIndependently Option to reset the previous values dictionaries before encoding a new FIX message.
    Encoder(const std::string & xmlTemplates, ProtocolVersion::Enum fixVersion,
            bool encodeEachMessageIndependently);

    /// Creates a FIX to FAST Encoder.
    ///
    /// @param xmlTemplates XML-based FAST templates.
    /// @param fixDictionaryId FIX dictionary ID.
    /// @param encodeEachMessageIndependently Option to reset the previous values dictionaries before encoding a new FIX message.
    Encoder(const std::string & xmlTemplates, const std::string & fixDictionaryId,
            bool encodeEachMessageIndependently);

    /// Creates a FIX to FAST Encoder for FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, uses FIX 4.0 as base and has generic name.
    ///
    /// @param xmlTemplates XML-based FAST templates.
    /// @param encodeEachMessageIndependently Option to reset the previous
    /// values dictionaries before encoding next FIX message.
    Encoder(const std::string & xmlTemplates, bool encodeEachMessageIndependently);

    /// Creates a FIX to FAST Encoder for FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, uses specified FIX dictionary as base and has generic name.
    ///
    /// @param baseVersion Version of FIX protocol which dictionary becomes base for the newly generated FIX dictionary.
    /// @param xmlTemplates XML-based FAST templates used to generate FIX dictionary. This FIX dictionary takes generic identifier generated on base of the XML contanet and @c baseVersion
    /// @param encodeEachMessageIndependently Option to reset the previous
    /// values dictionaries before encoding next FIX message.
    Encoder(ProtocolVersion::Enum baseVersion, const std::string & xmlTemplates,
            bool encodeEachMessageIndependently);

    /// Creates a FIX to FAST Encoder for FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, uses specified FIX dictionary as base and has the specified name.
    /// @note New FIX dictionary instance will be generated if and only if there is no FIX dictionary with the same name.
    ///
    /// @param baseVersion Version of FIX protocol which dictionary becomes base for the newly generated FIX dictionary.
    /// @param xmlTemplates XML-based FAST templates.
    /// @param genericFixDictionaryId Identifier which is applied to generic FIX dictionary. This FIX dictionary is generated using @c xmlTemplates and @c baseVersion.
    /// @param encodeEachMessageIndependently Option to reset the previous
    /// values dictionaries before encoding next FIX message.
    Encoder(ProtocolVersion::Enum baseVersion, const std::string & xmlTemplates,
            const std::string & genericFixDictionaryId, bool encodeEachMessageIndependently);

    /// Destructor.
    ~Encoder(void);

    /// Encodes the given FIX message into a FAST stream.
    ///
    /// @param fixMessage Source FIX message to be encoded.
    /// @param templateID FAST Template Identifier which uniquely describes the encoding/decoding rules.
    /// @param buffer Supplied buffer that will contain the FAST stream chunk.
    /// @param bufferSize Size of the supplied buffer.
    ///
    /// @return the size of the encoded FAST stream chunk.
    size_t encode(const OnixS::FIX::Message & fixMessage, int templateID, char * buffer,
                  size_t bufferSize); // Deprecated
    size_t encode(const OnixS::FIX::Message & fixMessage, int templateID, unsigned char * buffer,
                  size_t bufferSize);

    /// Encodes the given FIX message into a FAST stream using the default template ID.
    ///
    /// @param fixMessage Source FIX message to be encoded.
    /// @param buffer Supplied buffer that will contain the FAST stream chunk.
    /// @param bufferSize Size of the supplied buffer.
    ///
    /// @return the size of the encoded FAST stream chunk.
    size_t encode(const OnixS::FIX::Message & fixMessage, char * buffer,
                  size_t bufferSize); // Deprecated
    size_t encode(const OnixS::FIX::Message & fixMessage, unsigned char * buffer,
                  size_t bufferSize);

    /// Resets the state of the previous values dictionaries (sets the state of the previous values to undefined).
    ///
    /// @see encodeEachMessageIndependently.
    void reset();

    /// FIX dictionary used by the encoder instance.
    ///
    /// @return FIX dictionary currently used by the encoder instance. If the encoder was initialized for FIX dictionary-independent mode, the method returns
    /// reference to internally generated FIX dictionary.
    OnixS::FIX::Dictionary fixDictionary() const;

private:
    friend ONIXS_FIXENGINE_API_DECL(class, OnixS::FIX::Dictionary);

    Encoder(const Encoder &);
    Encoder & operator = (const Encoder &);

    struct Impl;
    Impl * impl_;
};

/// Performs FAST to FIX decoding.
class ONIXS_FIXENGINE_API Decoder
{
public:
    /// Creates a FAST to FIX Decoder.
    ///
    /// @param xmlTemplates XML-based FAST templates.
    /// @param fixDictionary Customized FIX dictionary used for decoded message.
    /// @param decodeEachMessageIndependently Option to reset the previous
    /// values dictionaries before decoding a new FAST stream chunk.
    /// @param inputDataTraits Traits of input data, has effect only when @c decodeEachMessageIndependently is @c false. See InputDataTraits::Enum for details.
    Decoder(const std::string & xmlTemplates, const OnixS::FIX::Dictionary & fixDictionary,
            bool decodeEachMessageIndependently, InputDataTraits::Enum inputDataTraits);

    /// Creates a FAST to FIX Decoder for FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, uses FIX 4.0 as base FIX dictionary and has generic name.
    ///
    /// @param xmlTemplates XML-based FAST templates.
    /// @param decodeEachMessageIndependently Option to reset the previous
    /// values dictionaries before decoding a new FAST stream chunk.
    /// @param inputDataTraits Traits of input data, has effect only when @c decodeEachMessageIndependently is @c false. See InputDataTraits::Enum for details.
    Decoder(const std::string & xmlTemplates, bool decodeEachMessageIndependently,
            InputDataTraits::Enum inputDataTraits);

    /// Creates a FAST to FIX Decoder for FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, uses specified FIX dictionary as base and has generic name.
    ///
    /// @param baseVersionForGeneratedDictionary Version of FIX protocol which dictionary becomes base for the newly generated FIX dictionary.
    /// @param xmlTemplates XML-based FAST templates used to generate FIX dictionary. This FIX dictionary takes generic identifier generated on base of the XML contanet and @c baseVersion
    /// @param decodeEachMessageIndependently Option to reset the previous
    /// values dictionaries before decoding a new FAST stream chunk.
    /// @param inputDataTraits Traits of input data, has effect only when @c decodeEachMessageIndependently is @c false. See InputDataTraits::Enum for details.
    Decoder(ProtocolVersion::Enum baseVersionForGeneratedDictionary,
            const std::string & xmlTemplates, bool decodeEachMessageIndependently,
            InputDataTraits::Enum inputDataTraits);

    /// Creates a FAST to FIX Decoder for FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, uses specified FIX dictionary as base and has the specified name.
    /// @note New FIX dictionary instance will be generated if and only if there is no FIX dictionary with the same name.
    ///
    /// @param baseVersionForGeneratedDictionary Version of FIX protocol which dictionary becomes base for the newly generated FIX dictionary.
    /// @param xmlTemplates XML-based FAST templates.
    /// @param genericFixDictionaryId Identifier which is applied to generic FIX dictionary. This FIX dictionary is generated using @c xmlTemplates and @c baseVersion.
    /// @param decodeEachMessageIndependently Option to reset the previous
    /// values dictionaries before decoding a new FAST stream chunk.
    /// @param inputDataTraits Traits of input data, has effect only when @c decodeEachMessageIndependently is @c false. See InputDataTraits::Enum for details.
    Decoder(ProtocolVersion::Enum baseVersionForGeneratedDictionary,
            const std::string & xmlTemplates, const std::string & genericFixDictionaryId,
            bool decodeEachMessageIndependently, InputDataTraits::Enum inputDataTraits);

    /// Destructor.
    ~Decoder();

    /// Input data traits of the decoder.
    /// @return Input data traits provided during construction of the decoder.
    InputDataTraits::Enum inputDataTraits() const;

    /// Decodes the given FAST stream chunk into the corresponding FIX Message.
    ///
    /// @param buffer Buffer that contains the FAST stream chunk to be decoded.
    /// @param bufferSize Size of the buffer.
    ///
    /// @warning The returned message is 'owned' by Decoder.
    /// @warning The previously decoded message is freed by Decoder when this method is called again.
    ///
    /// @throw Exception if the message cannot be decoded.
    ///
    /// @return the decoded FIX message.
    const OnixS::FIX::Message & decode(const char * buffer, size_t bufferSize); // Deprecated
    const OnixS::FIX::Message & decode(const unsigned char * buffer, size_t bufferSize);

    /// Decodes the given FAST stream chunk into the corresponding FIX Message.
    ///
    /// @param chunk The FAST stream chunk to be decoded.
    ///
    /// @warning The returned message is 'owned' by Decoder.
    /// @warning The previously decoded message is freed by Decoder when this method is called again.
    ///
    /// @throw Exception if the message cannot be decoded.
    ///
    /// @return the decoded FIX message.
    const OnixS::FIX::Message & decode(const std::vector<char> & chunk); // Deprecated
    const OnixS::FIX::Message & decode(const OnixS::Sockets::Bytes & chunk);

    /// Tries to decode the given FAST stream buffer into the corresponding FIX Message.
    ///
    /// @param[in] buffer The FAST stream chunk to be decoded.
    /// @param[in] offset The index in the buffer at which decoding begins.
    /// @param[in] count Number of bytes to analyze during the decoding.
    /// @param[out] message pointer to decoded FIX Message.
    /// @param[out] numberOfDecodedBytes Number of bytes that contained the encoded FIX Message.
    ///
    /// @warning message should point to an existing object. This object is not owned by Decoder and should be managed by user.
    ///
    /// @throw Exception if the decoding error is detected.
    ///
    /// @return 'true' if the given bytes could be decoded into a FIX message, otherwise - 'false'.
    bool tryDecode(const char * buffer, size_t offset, size_t count, OnixS::FIX::Message * message,
                   size_t * numberOfDecodedBytes); // Deprecated
    bool tryDecode(const unsigned char * buffer, size_t offset, size_t count,
                   OnixS::FIX::Message * message, size_t * numberOfDecodedBytes);

    /// Decodes the FAST-encoded unsigned integer.
    ///
    /// @param buffer Buffer that contains the FAST stream chunk to be decoded.
    /// @param bufferSize Size of the buffer.
    /// @param value Decoded value.
    /// @param fieldLength Number of bytes that contained the encoded value.
    ///
    /// @return 'true' if the stop bit was found and the value was decoded, otherwise - 'false'.
    static bool tryDecodeUnsignedInteger(const char * buffer, size_t bufferSize,
                                         unsigned int * value, size_t * fieldLength); // Deprecated
    static bool tryDecodeUnsignedInteger(const unsigned char * buffer, size_t bufferSize,
                                         unsigned int * value, size_t * fieldLength);

    /// Resets the state of the previous values dictionaries (sets the state of the previous values to undefined).
    ///
    /// @see decodeEachMessageIndependently.
    void reset();

    /// FIX dictionary used by the decoder instance.
    ///
    /// @return FIX dictionary currently used by the decoder instance. If the decoder was initialized with FIX dictionary-independent mode, the method returns
    /// reference to internally generated FIX dictionary.
    OnixS::FIX::Dictionary fixDictionary() const;

    /// Manage maximum number of repeating groups, allowed for decoded messages.
    ///
    /// This parameter is used during decoding and is useful to detect a broken data, which, in particular cases,
    /// can 'need' to allocate unexpectedly huge number of entries (for instance - billions of entries,
    /// while normally there are just a few ones). This situation results in memory exhausting and (often)
    /// significantly decrease overall system performance.
    ///
    /// To prevent memory exhausting and negative consequences of that, this parameter should be configured with the value,
    /// which is greater then maximum possible number of entries in valid input data, but less then maximum integer value (default one).
    /// In a lot of real cases value of 10000 is good enough to detect broken data without memory overloading.
    ///
    /// Default is maximum positive value for @c int type.
    ///
    /// @param value Number of repeating groups, allowed for decoded messages.
    void maximumNumberOfRepeatingGroupEntries(int value);

    /// Maximum number of repeating groups, allowed for decoded messages.
    ///
    /// @return Current number of repeating groups, allowed for decoded messages. Default value is maximum positive value for @c int type.
    int maximumNumberOfRepeatingGroupEntries() const;

    /// Generates FIX dictionary XML.
    ///
    /// @param[in] fastTemplateXml XML content of FAST template (the same as used to initialize Decoder).
    ///
    /// @param[in] fixDictionaryId Output FIX dictionary identifier (see "id" attribute of "FIX" node).
    /// @param[out] fixDictionaryXml XML with generated FIX dictionary.
    static void generateFixDictionary(const std::string & fastTemplateXml,
                                      const std::string & fixDictionaryId, std::string * fixDictionaryXml);

    /// Generates FIX dictionary XML.
    ///
    /// @param[in] fastTemplateXml XML content of FAST template (the same as used to initialize Decoder).
    /// @param[in] baseVersion Version of FIX protocol which dictionary becomes base for the newly generated FIX dictionary.
    /// @param[in] fixDictionaryId Output FIX dictionary identifier (see "id" attribute of "FIX" node).
    /// @param[out] fixDictionaryXml XML with generated FIX dictionary.
    static void generateFixDictionary(ProtocolVersion::Enum baseVersion,
                                      const std::string & fastTemplateXml, const std::string & fixDictionaryId,
                                      std::string * fixDictionaryXml);
private:
    friend ONIXS_FIXENGINE_API_DECL(class, OnixS::FIX::Dictionary);

    Decoder(const Decoder &);
    Decoder & operator = (const Decoder &);

    struct Impl;
    Impl * impl_;
};

}
}
}