BxDataObject Class Reference

Superclass implementing all basic operations on Binx data types. More...

#include <BxDataObject.h>

Inheritance diagram for BxDataObject:

List of all members.

Public Member Functions
	BxDataObject ()
	BxDataObject (const BxDataObject &copy)
virtual BxDataObject *	clone () const
virtual char *	varName () const
virtual void	setBinaryFilePtr (BxBinaryFile *fp)
virtual long	locate () const
bx_byte8	getByte ()
bx_ubyte8	getUnsignedByte ()
bx_char8	getChar ()
bx_short16	getShort ()
bx_int32	getInt ()
bx_long64	getLong ()
bx_float32	getFloat ()
bx_double64	getDouble ()
bx_ushort16	getUnsignedShort ()
bx_uint32	getUnsignedInt ()
bx_ulong64	getUnsignedLong ()
void	setVarName (char *vname)
void	setByte (bx_byte8 b)
void	setChar (bx_char8 c)
void	setShort (bx_short16 s)
void	setInt32 (bx_int32 i)
void	setLong64 (bx_long64 l)
void	setFloat (bx_float32 f)
void	setDouble (bx_double64 d)
void	setUnsignedByte (bx_ubyte8 ub)
void	setUnsignedShort (bx_ushort16 us)
void	setUnsignedInt32 (bx_uint32 ui)
void	setUnsignedLong64 (bx_ulong64 ul)

---

Detailed Description

This class implements methods to:

• Get values for BinX primitive data types.
• Set values for BinX primitive data types.
• Get size information (in bits and bytes) for BinX primitive data types.
• Pad data values to align BinX primitive data types, when necessary.

A class corresponding to each BinX primitive data type and BinX abstract data type is directly or indirectly derived from the class BxDataObject. The class BxDataObject defines a set semantically-rich methods that are reimplemented by the derived classes. Semantically-rich operations include:

• Reading data values from a binary data file and converting byte order(if necessary) to match the host machine.
• Extracting a data value from a buffer and converting byte order (if necessary) to match the host machine.
• Writing a DataBinX representation of a binary data value to an ASCII file.

The class BxDataObject defines the general semantics of all methods defined in this class, even when the method is implemented by the derived class.
Each instance of the class BxDataObject is associated with a binary data file. The file name is specified in a BinX document and it is typically associated with the BxDataObject instance when it is created. The primary data value stored by the BxDataObject instance is either read from the associated binary data file, or created in host memory and written to the associated binary data file.
The class BxDataObject defines attributes to store metadata describing the primary data value. Significant metadata attributes include:

• BinX type - records the actual BinX primitive type contained in this object.
• Byte order - indicates whether the associated binary data file contains this value in little endian or big endian order.
• Load status - indicates whether a primary data value has been stored in this object either by direct construction, direct assignment, or by reading a value from a binary data file.
• Size information - records the size of the object in both bit and byte quantities.
• Variable name - records the optional variable name defined in a BinX document and associated with this primary data value.
• Binary file - records a pointer to the associated binary data file.
• File offset - records the relative offset of the primary data value in the associated binary data file.

The class BxDataObject defines the following semantics with respect to the size of a BinX primitive data type.

• BxDataObject::bytes() - returns the number of bytes used to store the primary data value.
• BxDataObject::size() - returns the number of bytes the primary data value occupies in the associated binary data file, including padding, if required for alignment.
• BxDataObject::blockSize() - returns the bit alignment required by the primary data value. A value of zero or one, means no alignment is required. A value of 32 means the primary data value must be aligned on a four byte boundary.

Since: BinX version 1.0.

---

Constructor & Destructor Documentation

BxDataObject::BxDataObject (   )

Default constructor. Constructs an instance of the class BxDataObject. The primary data value stored by this instance is not set by this constructor. The primary data value and the metadata describing properties of the data value, such as byte order and size, msut be set by the derived class, specific to the data type. Default attribute values are assigned by this constructor as follows: typeName_ = NULL; varName_ = NULL; testValue_ = NULL; sizeInBytes_ = 0; sizeInAll_ = 0; blockSize_ = 0; bfile_ = NULL; byteOrder_ = BX_UNSPECIFIED; offsetInFile_ = 0; loaded_ = false;

BxDataObject::BxDataObject (  const BxDataObject &  copy  )

Construct a BxDataObject instance by copying a specified BxDataObject instance. Constructs and initialises an instance of the class BxDataObject. This constructor should be overridden by each derived class. Parameters: copy  A reference to the BxDataObject instance to copy.

---

Member Function Documentation

BxBinaryFile* BxDataObject::binaryFile (   )  const [inline]

Get the file pointer for the associated binary data file. This value is NULL if no file is associated with the object, or the file is not open.

virtual int BxDataObject::blockSize (   )  const [inline, virtual]

Get the block alignment factor, specifying the required alignment for the primary data value in the binary data file.

BxByteOrder BxDataObject::byteOrder (   )  const [inline]

Get the byte order identifier, indicating little endian or big endian byte order for data values in the associated binary data file.

int BxDataObject::bytes (   )  const [inline]

Get the number of bytes used to store the primary data value of this object.

BxDataObject * BxDataObject::clone (   )  const [virtual]

Create a duplicate instance of this BxDataObject instance. Uses the constructor to create a instance having the same attribute values as the instance it was cloned from. Upon completion of the cloning operations, the two instances are independent. They must be individually destructed. Returns: The newly created copy of this object.

int BxDataObject::dataClass (   )  const [inline]

Get the class ID of the BinX primitive data type stored in this object.

bx_byte8 BxDataObject::getByte (   )

Get the primary data value for this BxByte8 object. If this object is a BxByte8 object and a primary data value has been assigned to this object, then return a single signed byte value of type bx_byte8. If no primary data value has been assigned to this object, then the derived class BxByte8 is invoked to read a data value from the associated binary data file. If a value is successfully read, then a single byte value is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The byte value stored by this BxByte8 object.

bx_char8 BxDataObject::getChar (   )

Get the primary data value for this BxCharacter8 object. If this object is a BxCharacter8 object and a primary data value has been assigned to this object, then return a character value of type bx_char8. If no primary data value has been assigned to this object, then the derived class BxCharacter8 is invoked to read a data value from the associated binary data file. If a value is successfully read, then a single character value is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The single character value stored by this BxCharacter8 object.

BxDataUnion BxDataObject::getDataValue (   )  const [inline]

Get the primary data value, which was read from a binary data file, or will be written to a binary data file.

bx_double64 BxDataObject::getDouble (   )

Get the primary data value for this BxDouble64 object. If this object is a BxDouble64 object and a primary data value has been assigned to this object, then return a double precision floating point number of type bx_double64. If no primary data value has been assigned to this object, then the derived class BxDouble64 is invoked to read a data value from the associated binary data file. If a value is successfully read, then a double precision floating point number is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The double precision floating point number stored by this BxDouble64 object.

bx_float32 BxDataObject::getFloat (   )

Get the primary data value for this BxFloat32 object. If this object is a BxFloat32 object and a primary data value has been assigned to this object, then return a single precision floating point number of type bx_float32. If no primary data value has been assigned to this object, then the derived class BxFloat32 is invoked to read a data value from the associated binary data file. If a value is successfully read, then a single precision floating point number is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The single precision floating point number stored by this BxFloat32 object.

bx_int32 BxDataObject::getInt (   )

Get the primary data value for this BxInteger32 object. If this object is a BxInteger32 object and a primary data value has been assigned to this object, then return an integer value of type bx_int32. If no primary data value has been assigned to this object, then the derived class BxInteger32 is invoked to read a data value from the associated binary data file. If a value is successfully read, then an integer value is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The integer value stored by this BxInteger32 object.

bx_long64 BxDataObject::getLong (   )

Get the primary data value for this BxLong64 object. If this object is a BxLong64 object and a primary data value has been assigned to this object, then return a long integer value of type bx_long64. If no primary data value has been assigned to this object, then the derived class BxLong64 is invoked to read a data value from the associated binary data file. If a value is successfully read, then a long integer value is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The long integer value stored by this BxLong64 object.

bx_short16 BxDataObject::getShort (   )

Get the primary data value for this BxShort16 object. If this object is a BxShort16 object and a primary data value has been assigned to this object, then return a short integer value of type bx_short16. If no primary data value has been assigned to this object, then the derived class BxShort16 is invoked to read a data value from the associated binary data file. If a value is successfully read, then a short integer value is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The short integer value stored by this BxShort16 object.

bx_ubyte8 BxDataObject::getUnsignedByte (   )

Get the primary data value for this BxUnsignedByte8 object. If this object is a BxUnsignedByte8 object and a primary data value has been assigned to this object, then return a single unsigned byte value of type bx_ubyte8. If no primary data value has been assigned to this object, then the derived class BxUnsignedByte8 is invoked to read a data value from the associated binary data file. If a value is successfully read, then a single byte value is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The byte value stored by this BxUnsignedByte8 object.

bx_uint32 BxDataObject::getUnsignedInt (   )

Get the primary data value for this BxUnsignedInteger32 object. If this object is a BxUnsignedInteger32 object and a primary data value has been assigned to this object, then return an unsigned integer value of type bx_uint32. If no primary data value has been assigned to this object, then the derived class BxUnsignedInteger32 is invoked to read a data value from the associated binary data file. If a value is successfully read, then an unsigned integer value is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The unsigned integer value stored by this BxUnsignedInteger32 object.

bx_ulong64 BxDataObject::getUnsignedLong (   )

Get the primary data value for this BxUnsignedLong64 object. If this object is a BxUnsignedLong64 object and a primary data value has been assigned to this object, then return an unsigned long integer value of type bx_ulong64. If no primary data value has been assigned to this object, then the derived class BxUnsignedLong64 is invoked to read a data value from the associated binary data file. If a value is successfully read, then an unsigned long integer value is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The unsigned long integer value stored by this BxUnsignedLong64 object.

bx_ushort16 BxDataObject::getUnsignedShort (   )

Get the primary data value for this BxUnsignedShort16 object. If this object is a BxUnsignedShort16 object and a primary data value has been assigned to this object, then return an unsigned short integer value of type bx_ushort16. If no primary data value has been assigned to this object, then the derived class BxUnsignedShort16 is invoked to read a data value from the associated binary data file. If a value is successfully read, then an unsigned short integer value is returned. If a value can not be read from the associated binary data file, then the value zero is returned. If the return value is zero, invoke the method getErrorMessage() to check for possible errors. Possible error codes include: BX_ERROR_BIN_NOTREAD and BX_ERROR_DATATYPE. Returns: The unsigned short integer value stored by this BxUnsignedShort16 object.

bool BxDataObject::loaded (   )  const [inline]

Get an indicator stating whether the primary data value for this object is currently set.

long BxDataObject::locate (   )  const [virtual]

Position a binary file pointer to the first byte of a value for this data object. Due to the use of padding and headers in binary data files, it may be necessary to position a binary file pointer before reading or writing the data value for an object. Based on the object type, this method positions the file pointer in the associated binary file in preparation for reading or writing a value. This method returns the resulting file offset, expressed as a byte count relative to the beginning of the file. Returns: Current file pointer byte offset in the associated binary file.

long BxDataObject::offset (   )  const [inline]

Get the relative byte offset of the primary data value in the associated binary data file.

void BxDataObject::setBinaryFilePtr (  BxBinaryFile *  fp  )  [virtual]

Associate a specified binary data file with this object. The binary data file must be represented by an instance of class BxBinaryFile or one of its derived classes, BxBinaryFileReader and BxBinaryFileWriter. This means that the binary data file must be open for reading or writing. Upon completion of this method, the BxBinaryFile object is referenced by this object. The caller must not release the BxBinaryFile object. This object will release the input object when this object is destructed. This is a virtual method. Derived class may override this method. For example, the class BxDataset overrides this method to selectively set the file pointer to one of several binary data files managed by the BxDataset. Parameters: fp  A pointer to the BxBinaryFile object. Reimplemented in BxArrayVariable.

virtual void BxDataObject::setBlockSize (  int  blocksize  )  [inline, virtual]

Set the block alignment factor for the primary data value in the binary data file. Valid range is [0, 128].

void BxDataObject::setByte (  bx_byte8  b  )

Set the primary data value for this object to a specified byte value. This method should be applied only to an object of type BxByte8. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input byte value. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: b  The byte value to set the primary data value of this object.

virtual void BxDataObject::setByteOrder (  BxByteOrder  bo  )  [inline, virtual]

Set the byte order identifier for the associated binary file. Valid values are: BX_BIG_ENDIAN, BX_LITTLE_ENDIAN, BX_UNSPECIFIED. Reimplemented in BxArray.

void BxDataObject::setChar (  bx_char8  c  )

Set the primary data value for this object to a specified character value. This method should be applied only to an object of type BxCharacter8. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input character value. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: c  The character value to set the primary data value of this object.

void BxDataObject::setDouble (  bx_double64  d  )

Set the primary data value for this object to a specified double precision floating point number. This method should be applied only to an object of type BxDouble64. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input double precision floating point number. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: d  The double precision floating point number to set the primary data value of this object.

void BxDataObject::setFloat (  bx_float32  f  )

Set the primary data value for this object to a specified single precision floating point number. This method should be applied only to an object of type BxFloat32. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input single precision floating point number. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: f  The single precision floating point number to set the primary data value of this object.

void BxDataObject::setInt32 (  bx_int32  i  )

Set the primary data value for this object to a specified integer value. This method should be applied only to an object of type BxInteger32. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input integer value. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: i  The integer value to set the primary data value of this object.

void BxDataObject::setLong64 (  bx_long64  l  )

Set the primary data value for this object to a specified long integer value. This method should be applied only to an object of type BxLong64. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input long integer value. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: l  The long integer value to set the primary data value of this object.

void BxDataObject::setShort (  bx_short16  s  )

Set the primary data value for this object to a specified short integer value. This method should be applied only to an object of type BxShort16. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input short integer value. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: s  The short integer value to set the primary data value of this object.

void BxDataObject::setUnsignedByte (  bx_ubyte8  ub  )

Set the primary data value for this object to a specified byte value. This method should be applied only to an object of type BxUnsignedByte8. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input byte value. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: ub  The byte value to set the primary data value of this object.

void BxDataObject::setUnsignedInt32 (  bx_uint32  ui  )

Set the primary data value for this object to a specified unsigned integer value. This method should be applied only to an object of type BxUnsignedInteger32. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input unsigned integer value. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: ui  The unsigned integer value to set the primary data value of this object.

void BxDataObject::setUnsignedLong64 (  bx_ulong64  ul  )

Set the primary data value for this object to a specified unsigned long integer value. This method should be applied only to an object of type BxUnsignedLong64. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input unsigned long integer value. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: ul  The unsigned long integer value to set the primary data value of this object.

void BxDataObject::setUnsignedShort (  bx_ushort16  us  )

Set the primary data value for this object to a specified unsigned short integer value. This method should be applied only to an object of type BxUnsignedShort16. The method does not check the BinX data type of this object. The primary data value of this object is assigned the input unsigned short integer value. The load status of this object is also updated to indicate that a primary data value has been assigned to this object. Parameters: us  The unsigned short integer value to set the primary data value of this object.

void BxDataObject::setVarName (  char *  vname  )

Set the BinX XML variable name value for this object to a specified string. If the variable name has been previously set for this object, then the specified input value replaces the previously stored variable name value. Memory allocated for the old variable name value is released. Upon completion of this method, the input variable name value is referenced by this object. The caller must not release the input string. This object will release the string when this object is destructed. See Also: BxDataObject::copyVarName(const char *). Parameters: vname  A pointer to a string containing the variable name value.

int BxDataObject::size (   )  const [inline]

Get the number of bytes used to store the primary data value in the associated binary data file.

virtual char* BxDataObject::typeName (   )  const [inline, virtual]

Get the user-defined type name for this object. Returns a value only for user-defined abstract types.

char * BxDataObject::varName (   )  const [virtual]

Get the value of the BinX XML variable name associated with this object. The BinX XML schema defines an optional XML attribute called "varname". This attribute can be associated with several types of primitive and abstract data types. The BinX document file describing the binary data file that provides the primary data value for this object, also defines the value of the associated variable name. This method returns a null-terminated string containing the value of the variable name for this object. If the XML attribute "varName" is not defined in the associated BinX document, then a NULL pointer is returned. The returned string is also referenced as an attribute value of this object. The caller must not release the string. This object will release the string when this object is destructed. Returns: A pointer to a null-terminated string containing the BinX XML variable name.

---

The documentation for this class was generated from the following files:

• BxDataObject.h
• BxDataObject.cpp

---