---

d_Binary.h

Go to the documentation of this file.

#ifndef d_Binary_h
#define d_Binary_h 1
//------------------------------------------------------------------------------

#include "cTypes.h"
#include "oMemoryManager.h"
//------------------------------------------------------------------------------

/**
 * Manages binary data.
 *
 * d_Binary is the type for managing binary data. It's like the BLOB (Binary
 * Large Object Block) type of Relational DBMS.
 *
 * It permits to save any information: texts, pictures, movies, sounds, etc.
 * The size limit of a d_Binary object is 2^32 for 32bit systems.
 *
 * USAGE:
 * d_Binary     <variable>;
 * 
 * Where:
 * <VARIABLE>:  NAME OF VARIABLE
 *
 * EXAMPLES:
 * class Employee : public d_Object
 * {
 *   d_Binary    photo;  * JPEG FORMAT
 * };
 * 
 *  * Use a d_Binary object in app
 * d_Binary       stream;
 *
 * ODMG:
 * Extension
 */
class _ODLL d_Binary 
{
  public:

    /**
     * Default constructor.
     *
     * <iSize> specifies the start size in bytes of d_Binary object. If not
     * specified will be taken the default value (256 bytes).
     *
     * <iStep> specifies the size in bytes of step of increment when the
     * d_Binary becames full. If not specified will be taken the default
     * value (64 bytes).
     *
     * SEE ALSO:  reserve(), getSize()
     */
    d_Binary (oUInt4 iSize = DEFAULT_SIZE, oUInt4 iStep = DEFAULT_STEP);

    /**
     * Create a d_Binary object by a raw buffer.
     *
     * <iData> is a char* that points to the begin of buffer. <iLength> is the
     * size in bytes of buffer.
     *
     * The buffer will be copied into the d_Binary object.
     *
     * SEE ALSO:  append(), set()
     */
    d_Binary (const char* iData, oUInt4 iLength);

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


    /**
     * Reset the internal buffer.
     */
    void reset ();

    /**
     * Append a raw buffer to the end of own data.
     */
    bool append (const char* iData, oUInt4 iLength);

    /**
     * Append another d_Binary object to the end of own data.
     */
    bool append (const d_Binary& iSource);

    /**
     * Copy d_Buffer data in to a raw buffer.
     *
     * <iData> is a char* that points to the begin of buffer. <iLength> is the
     * size in bytes of buffer to copy and <iStart> is the offset from the
     * begin of buffer.
     */
    bool get (const char* iData, oUInt4 iStart, oUInt4 iLength) const;

    /**
     * Copy d_Buffer data in to another d_Binary object.
     *
     * <iData> is the d_Binary object where the buffer is copied. <iLength> is
     * the size in bytes of buffer to copy. If is equals to 0, then copy all
     * buffer.
     *
     * <iStart> is the offset from the begin of buffer.
     */
    bool get (d_Binary& iData, oUInt4 iStart = 0, oUInt4 iLength = 0) const;

    /**
     * Copy a raw buffer in the d_Binary object.
     *
     * <iData> is a char* that points to the begin of buffer. <iLength> is the
     * size in bytes of buffer to copy and <iStart> is the offset from the
     * begin of d_Binary buffer.
     */
    bool set (const char* iData, oUInt4 iStart, oUInt4 iLength);

    /**
     * Copy data from a d_Binary object.
     *
     * All <iSource> object is copied.
     *
     * <iSource> is the d_Binary object to copy. <iStart> is the offset from
     * the begin of own d_Binary buffer.
     */
    bool set (d_Binary& iSource, oUInt4 iStart);

    /**
     * Insert a d_Binary object in the current object.
     *
     * The <iSource> object is inserted by <iStart> position moving the data
     * on the right.
     *
     * <iSource> is the d_Binary object to insert. <iStart> is the offset from
     * the begin of own d_Binary buffer.
     */
    bool insert( d_Binary& iSource, oUInt4 iStart );

    /**
     * Insert a buffer in the current object.
     *
     * The <iData> buffer of size <iLength> is inserted by <iStart> position
     * moving the data on the right.
     *
     * <iData> is the buffer to insert. <iStart> is the offset from the begin
     * of own d_Binary buffer. <iLength> is the size of buffer to insert.
     */
    bool insert( char* iData, oUInt4 iStart, oUInt4 iLength );

    /**
     * Erase a portion of buffer.
     *
     * Data at the right of the portion to erase will be moved on left.
     *
     * <iStart> is the offset from the begin of own d_Binary buffer. <iLength>
     * is the size in bytes of buffer.
     */
    void cut (oUInt4 iStart, oUInt4 iLength);

    /**
     * Returns the current length of buffer in bytes.
     *
     * SEE ALSO:  getSize()
     */
    oUInt4 getLength () const;

    /**
     * Returns the current size of buffer in bytes.
     *
     * The size is always grather or equals to the effective buffer length.
     *
     * SEE ALSO:  getLength()
     */
    oUInt4 getSize () const;

    /**
     * Returns the pointer to the internal buffer.
     *
     * This method permits to access to the d_Binary buffer without copy it.
     * Applications should use this method just to read the buffer data and
     * not for write.
     *
     * If <iStart> is specified, then returns the pointer of the internal
     * buffer plus <iStart> offset.
     */
    const char* raw (oUInt4 iStart = 0) const;

    /**
     * Reserve space for data.
     *
     * <iSize> is the size in bytes of space to reserve. If <iSize> is minor
     * than actual size, then the extra data will be lost.
     *
     * SEE ALSO:  d_Binary(), getSize()
     */
    bool reserve (oUInt4 iSize);

 private:
   // Internal.
    char* buffer;

   // Internal.
    oUInt4 _length;

   // Internal.
    oUInt4 size;

   // Internal.
    oUInt4 step;

   // Internal.
    static oUInt4 DEFAULT_SIZE;

   // Internal.
    static oUInt4 DEFAULT_STEP;


  friend class _ODLL d_String;
};

//------------------------------------------------------------------------------
inline void d_Binary::reset ()
{
  // JUST RESET LENGTH MEMBER AND LEAVE MEMORY ALLOCATED FOR FUTURE USE
  _length = 0;
}
//------------------------------------------------------------------------------
inline bool d_Binary::append (const char* iData, oUInt4 iLength)
{
  // MAP THIS CALL TO GET METHOD
  return set( iData, _length, iLength );
}
//------------------------------------------------------------------------------
inline bool d_Binary::append (const d_Binary& iSource)
{
  // MAP THIS CALL TO GET METHOD
  return set( iSource.buffer, _length, iSource._length );
}
//------------------------------------------------------------------------------
inline bool d_Binary::set (d_Binary& iSource, oUInt4 iStart)
{
  // MAP THIS CALL TO SET METHOD
  return set( iSource.buffer, iStart, iSource._length );
}
//------------------------------------------------------------------------------
inline oUInt4 d_Binary::getLength () const
{
  return _length;
}
//------------------------------------------------------------------------------
inline oUInt4 d_Binary::getSize () const
{
  return size;
}
//------------------------------------------------------------------------------
inline const char* d_Binary::raw (oUInt4 iStart) const
{
  // JUST RETURN POINTER OF INTERNAL BUFFER PLUS OFFSET
  return &buffer[iStart];
}
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

#endif

---