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 the FAST representation.
class ONIXS_FIXENGINE_API Encoder
{
public:
    /// Creates a FIX to FAST Encoder.
    ///
    /// @param xmlTemplates XML-based FAST templates.
    /// @param fixVersion The FIX Protocol version.
    /// @param encodeEachMessageIndependently The 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 The FIX dictionary ID.
    /// @param encodeEachMessageIndependently The 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 the FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, it uses the FIX 4.0 as a base and has a generic name.
    ///
    /// @param xmlTemplates XML-based FAST templates.
    /// @param encodeEachMessageIndependently The option to reset the previous
    /// values dictionaries before encoding the next FIX message.
    Encoder(const std::string & xmlTemplates, bool encodeEachMessageIndependently);

    /// Creates a FIX to FAST Encoder for the FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, it uses the specified FIX dictionary as a base and has a generic name.
    ///
    /// @param baseVersion This version of the FIX protocol becomes the base for the newly generated FIX dictionary.
    /// @param xmlTemplates XML-based FAST templates used to generate FIX dictionary. This FIX dictionary takes the generic identifier generated on a base of the XML content and @c baseVersion
    /// @param encodeEachMessageIndependently The 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 the FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, it uses the specified FIX dictionary as a base and has the specified name.
    /// @note The new FIX dictionary instance will be generated if and only if there is no a FIX dictionary with the same name.
    ///
    /// @param baseVersion This version of the FIX protocol becomes the base for the newly generated FIX dictionary.
    /// @param xmlTemplates XML-based FAST templates.
    /// @param genericFixDictionaryId The identifier which is applied to the generic FIX dictionary. This FIX dictionary is generated using @c xmlTemplates and @c baseVersion.
    /// @param encodeEachMessageIndependently The option to reset the previous
    /// values dictionaries before encoding the next FIX message.
    Encoder(ProtocolVersion::Enum baseVersion, const std::string & xmlTemplates, const std::string & genericFixDictionaryId, bool encodeEachMessageIndependently);

    /// The destructor.
    ~Encoder(void);

    /// Encodes the given FIX message into a FAST stream.
    ///
    /// @param fixMessage The source FIX message to be encoded.
    /// @param templateID The FAST Template Identifier which uniquely describes the encoding/decoding rules.
    /// @param buffer The supplied buffer that will contain the FAST stream chunk.
    /// @param bufferSize The 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 The source FIX message to be encoded.
    /// @param buffer The supplied buffer that will contain the FAST stream chunk.
    /// @param bufferSize The 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();

    /// The FIX dictionary used by the encoder instance.
    ///
    /// @return The FIX dictionary currently used by the encoder instance. If the encoder was initialized for the FIX dictionary-independent mode, the method returns
    /// a reference to the 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 &);

    class Impl;
    Impl * impl_;
};

/// Performs the FAST to FIX decoding.
class ONIXS_FIXENGINE_API Decoder
{
public:
    /// Creates a FAST to FIX Decoder.
    ///
    /// @param xmlTemplates XML-based FAST templates.
    /// @param fixDictionary The customized FIX dictionary used for the decoded message.
    /// @param decodeEachMessageIndependently The 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 the FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, it uses the FIX 4.0 as a base FIX dictionary and has a generic name.
    ///
    /// @param xmlTemplates XML-based FAST templates.
    /// @param decodeEachMessageIndependently The 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 the FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, it uses the specified FIX dictionary as a base and has a generic name.
    ///
    /// @param baseVersionForGeneratedDictionary This version of the FIX protocol becomes the base for the newly generated FIX dictionary.
    /// @param xmlTemplates XML-based FAST templates used to generate the FIX dictionary. This FIX dictionary takes a generic identifier generated on a base of the XML content and @c baseVersion
    /// @param decodeEachMessageIndependently The 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 the FIX dictionary-independent mode.
    /// The generic FIX dictionary is created by the provided FAST-template content, it uses the specified FIX dictionary as a base and has the specified name.
    /// @note The new FIX dictionary instance will be generated if and only if there is no a FIX dictionary with the same name.
    ///
    /// @param baseVersionForGeneratedDictionary This version of the FIX protocol becomes the base for the newly generated FIX dictionary.
    /// @param xmlTemplates XML-based FAST templates.
    /// @param genericFixDictionaryId The identifier which is applied to the generic FIX dictionary. This FIX dictionary is generated using @c xmlTemplates and @c baseVersion.
    /// @param decodeEachMessageIndependently The 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);

    /// The destructor.
    ~Decoder();

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

    /// Decodes the given FAST stream chunk into the corresponding FIX Message.
    ///
    /// @param buffer The buffer that contains the FAST stream chunk to be decoded.
    /// @param bufferSize The size of the buffer.
    ///
    /// @warning The returned message is 'owned' by the Decoder.
    /// @warning The previously decoded message is freed by the Decoder when this method is called again.
    ///
    /// @throw An 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 the Decoder.
    /// @warning The previously decoded message is freed by the Decoder when this method is called again.
    ///
    /// @throw An 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 The number of bytes to analyze during the decoding.
    /// @param[out] message The pointer to the decoded FIX Message.
    /// @param[out] numberOfDecodedBytes The number of bytes that contained the encoded FIX Message.
    ///
    /// @warning The message should point to an existing object. This object is not owned by the Decoder and should be managed by a user.
    ///
    /// @throw An 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 The buffer that contains the FAST stream chunk to be decoded.
    /// @param bufferSize The size of the buffer.
    /// @param value The decoded value.
    /// @param fieldLength The 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();

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

    /// Manages the maximum number of repeating groups, allowed for decoded messages.
    ///
    /// This parameter is used during the decoding and is useful to detect a broken data, which, in particular cases,
    /// can 'need' to allocate an 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 decreases the overall system performance.
    ///
    /// To prevent the memory exhausting and negative consequences of that, this parameter should be configured with the value,
    /// which is greater then the maximum possible number of entries in valid input data, but less then the maximum integer value (default one).
    /// In a lot of real cases the value of 10000 is good enough to detect broken data without the memory overloading.
    ///
    /// Default is the maximum positive value for @c int type.
    ///
    /// @param value The number of repeating groups, allowed for decoded messages.
    void maximumNumberOfRepeatingGroupEntries(int value);

    /// The maximum number of repeating groups, allowed for decoded messages.
    ///
    /// @return The current number of repeating groups, allowed for decoded messages. The default value is the maximum positive value for @c int type.
    int maximumNumberOfRepeatingGroupEntries() const;

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

    /// Generates the FIX dictionary XML.
    ///
    /// @param[in] fastTemplateXml The XML content of the FAST template (the same as used to initialize the Decoder).
    /// @param[in] baseVersion This version of the FIX protocol becomes the base for the newly generated FIX dictionary.
    /// @param[in] fixDictionaryId The output FIX dictionary identifier (see "id" attribute of "FIX" node).
    /// @param[out] fixDictionaryXml The XML with the 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 &);

    class Impl;
    Impl * impl_;
};

}
}
}