/////////////////////////////////////////////////////////////////////////////// 
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance"). 
// All rights reserved. 
// 
// This software and its documentation and related materials are owned by 
// the Alliance. The software may only be incorporated into application 
// programs owned by members of the Alliance, subject to a signed 
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable  
// trade secrets of the Alliance and its suppliers. The software is also 
// protected by copyright law and international treaty provisions. Application  
// programs incorporating this software must include the following statement 
// with their copyright notices:
//   
//   This application incorporates Open Design Alliance software pursuant to a license 
//   agreement with Open Design Alliance.
//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance. 
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you 
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////

#ifndef _DAI_BINARY_H_
#define _DAI_BINARY_H_

#include "OdAnsiString.h"
#include "OdArray.h"
#include "daiUtils/daiUnset.h"
#include "RxDictionary.h"

#include "TD_PackPush.h"

namespace OdDAI
{
  class BinaryType;

  /** \details
  A class that implements the EXPRESS BINARY data type within Standard Data Access Interface (SDAI).
  */
  class DAI_EXPORT Binary
  {
  public:
    /** \details
    Creates a new Binary instance with default parameters.
    */
    Binary();

    /** \details
    Creates a new Binary instance with specified parameters.
    \param maxSize [in] The long value for the max size for binary buffer.
    */
    Binary(unsigned long maxSize);

    /** \details
    Creates a new Binary instance with specified parameters.
    \param maxSize [in] The long value for the max size for binary buffer.
    \param newBuffer [in] initialize buffer for binary.
    */
    Binary(unsigned long maxSize, const OdArray<char>& newBuffer);

    /** \details
    Creates a new Binary instance with specified parameters.
    \param binaryType [in] binary type to initialize max size and buffer at binary.
    */
    Binary(const OdDAI::BinaryType* binaryType);

    /** \details
    Creates a new Binary instance as a copy of another Binary instance (copy constructor).
    \param other [in] An original Binary instance to be copied.
    */
    Binary(const Binary& other);

    /** \details
    Destroys binary instance.
    */
    ~Binary();

    /** \details
    Retrieves maximum binary data length.
    \returns Returns maximum binary data length.
    */
    unsigned long maximum() const;

    /** \details
    Sets current data length for binary data.
    \param newLength [in] new value of data length.
    */
    void length(unsigned long newLength);

    /** \details
    Retrieves current binary data length.
    \returns Returns a long value that represents a length of current binary data.
    */
    unsigned long length() const;

    /** \details
    Retrieves if Binary instance has a value.
    \returns Returns true if Binary instance has assigned value; otherwise returns false.
    */
    bool exists() const;

    /** \details
    Makes Binary instance unset.
    */
    void nullify();

    /** \details
    Provides a string which represents currently settled binary data.
    \returns Returns string that represents a current settled value. If Binary is unset the function returns empty string.
    */
    OdAnsiString getAnsiString() const;

    /** \details
    Assigns hexadecimal string value to Binary.
    \param buffer [in] string hexadecimal value.
    */
    void setAnsiString(const OdAnsiString& buffer);

    /** \details
    Provides a constant reference to internal Binary buffer.
    \returns Returns a constant reference to internal buffer.
    */
    const OdArray<char>& getBuffer() const;
    
    /** \details
    Sets new data buffer to Binary instance.
    \param newBuffer [in] new data buffer.
    */
    void setBuffer(const OdArray<char>& newBuffer);

    /** \details
    Retrieves a string to internal Binary data represented in binary view.
    \returns Returns a pointer to string which represents internal buffer in binary view.
    */
    const char* getBinaryString() const;

    /** \details
    Sets string to represented in binary view to Binary instance.
    \param newData [in] a binary string.
    */
    void setBinaryString(const char* newData);

    /** \details
    Retrieves the Binary object value represented as a byte array (memory buffer).
    \param memoryBuffer [out] A buffer to be filled with bytes of the Binary value.
    \returns true if the Binary object value was successfully written as a byte array in a specified buffer; otherwise, the method returns false.
    */
    bool getMemory(OdArray<OdUInt8>& memoryBuffer) const;
    
    /** \details
    Sets the Binary object value from a specified memory buffer.
    \param newBuffer [in] A memory buffer with new data to set.
    */
    void setMemory(const OdArray<OdUInt8>& newBuffer);

    /** \details 
    The equality operator for Binary objects. 
    \param other [in] Another Binary object to compare with (right-hand operand of the comparison operation).
    \returns true if this Binary object equals to another specified with the input parameter; otherwise, the operator returns false.
    */
    bool operator== (const Binary& other) const;
    
    /** \details 
    The &quot;less than&quot; operator for Binary objects. 
    \param other [in] Another Binary object to compare with (right-hand operand of the comparison operation).
    \returns true if this Binary object is less than another specified with the input parameter; otherwise, the operator returns false.
    */
    bool operator< (const Binary& other) const;
    
    /** \details 
    The inequality operator for Binary objects. 
    \param other [in] Another Binary object to compare with (right-hand operand of the comparison operation).
    \returns true if this Binary object is not equal to another specified with the input parameter; otherwise, the operator returns false.
    */
    bool operator!=(const Binary& other) const;
    
    /** \details 
    The assignment operator for Binary objects. 
    \param other [in] Another Binary object to assign (right-hand operand of the assignment operation).
    \returns The reference to the Binary object modified by the assignment operation.
    */
    Binary& operator=(const Binary& other);
    
    //DOM-IGNORE-BEGIN

  private:
    void clearCache();

  private:
    OdArray<char> m_buffer;
    mutable char* m_binaryDecodedCache = nullptr;

    unsigned long m_maxSize = 0;

  };

  /** \details 
  Contains declarations and definitions for different utils that implement useful helper functionality for Data Access Interface (DAI).
  */
  namespace Utils
  { 
    /** \details 
    Retrieves an unset value (value that is not set) for the <link OdDAI::Binary, Binary> data type.
    \returns A constant reference to a <link OdDAI::Binary, Binary object, which value represents the unset value (value that is not set).
    */
    template <> inline const OdDAI::Binary& getUnset<OdDAI::Binary>() { static OdDAI::Binary enumUnset; return enumUnset; }
    
    /** \details 
    A function that defines whether the value of a specified <link OdDAI::Binary, Binary> object is not set (unset).
    \param value [in] A <link OdDAI::Binary, Binary> object which value should be checked.
    \returns true if the specified <link OdDAI::Binary, Binary> object has an unset value (value that is not set).
    */
    inline bool isUnset(const  OdDAI::Binary& value) { return !value.exists(); }
    
    /** \details 
    A function that defines whether the value of a specified <link OdDAI::Binary, Binary> object is not set (unset).
    \param value [in] A raw pointer to the <link OdDAI::Binary, Binary> object which value should be checked.
    \returns true if the specified <link OdDAI::Binary, Binary> object has an unset value (value that is not set).
    */
    inline bool isUnset(const  OdDAI::Binary* value) { return (value == nullptr || !value->exists()); } 
  }
}

//DOM-IGNORE-END

#include "TD_PackPop.h"

#endif // _DAI_BINARY_H_