Improved blind data support
class.
Synopsis
class AlBlindData
public:
AlBlindData(AlObject *obj, int userID,
size_t size);
AlBlindData(int userID, size_t size);
virtual
~AlBlindData();
virtual
statusCode create();
virtual
statusCode deleteData();
virtual
bool isValid() const;
protected:
void
convert(int&);
void
convert(float&);
void
convert(short&);
void
convert(double&);
void
setEndian();
void
*getData() const;
Description
This class provides an
improved blind data support. AlBlindData is a base class for OpenAlias
plug-ins and OpenModel applications which need to maintain blind
data (that is, data which Alias does not know about in a platform
independent form). This class supersedes the existing blind data
support (AlDagNode::blindData for example).
The previous implementation
for blind data did not provide any support for moving data between
platforms which have different endian representations (for example
Irix and NT). This class provides a nearly invisible solution to
this problem. As such the previous implementation is obsolete and
will be removed in a future release of the API.
AlBlindData::AlBlindData(int
userID, size_t userSize)
Description
Constructor for referencing
blind data on an AlUniverse. If data with the userID already exists
this wrapper will reference it, otherwise it will initialized for
a call to the create() method.
Arguments
<
userID - user ID of the data desired.
<
userSize - number of bytes in the block of data.
AlBlindData::AlBlindData(AlObject
*parent, int userID, size_t userSize)
Description
Constructor for referencing
blind data on an AlObject. Only those object types which support
blind data will successfully initialize this wrapper. If data with
the userID already exists this wrapper will reference it, otherwise
it will initialized for a call to the create() method.
Arguments
<
parent - AlObject to attach blind data to.
<
userID - user ID of the data desired.
<
userSize - number of bytes in the block of data.
AlBlindData::~AlBlindData()
Description
Delete the AlBlindData
object. This does not affect the blind data.
bool AlBlindData::isValid()
const
Description
This method returns true
if it is possible to read or write to the blind data. Accessing
the blind data when this method returns false can lead to unexpected
results including segmentation violations.
statusCode AlBlindData::deleteData()
Description
This method deletes the
blind data referenced by this wrapper.
Note Under
no circumstances should you delete the data yourself.
Return Codes
sSuccess - the data was
successfully deleted.
sInvalidObject - the
wrapper does not reference a valid object.
statusCode AlBlindData::create()
Description
Create an instance of
the blind data on the object and of the size set when the AlBlindData object
was instantiated. If this object already references blind data
this method fails.
Return Codes
sAlreadyCreated - this
object already references blind data.
sInvalidObject - the
parent object was invalidated or cannot accept blind data.
sObjectAlreadyPresent
- blind data of the same user ID but different size exists. This likely
happens when attempting to reference old style blind data.
sInsufficientMemory -
insufficient memory to creat the blind data.
sSuccess - the blind
data was successfully created.
void *AlBlindData::getData()
const
Description
This protected method
returns a pointer to the data referenced by this wrapper. The validity
of the data should be checked with isValid() before the data is
accessed. The AlBlindData object maintains ownership of the data
and you are provided a pointer to the data only for the purposes
of reading and writing to it. You may not free this pointer. The
only way to delete the data is with the deleteData() method above.
void AlBlindData::convert(int&
val)
Description
This method ensures that
the integer is properly converted from whatever endian representation
the integer was saved in to the representation appropriate for the
current platform. This method is called in the constructor of classes
derived from this one.
void AlBlindData::convert(int&
val)
Description
This method ensures that
the integer is properly converted from whatever endian representation
the integer was saved in to the representation appropriate for the
current platform. This method is called in the constructor of classes
derived from this one.
void AlBlindData::convert(float&
val)
Description
This method ensures that
the float is properly converted from whatever endian representation
the float was saved in to the representation appropriate for the
current platform. This method is called in the constructor of classes
derived from this one.
void AlBlindData::convert(double&
val)
Description
This method ensures that
the double is properly converted from whatever endian representation
the double was saved in to the representation appropriate for the
current platform. This method is called in the constructor of classes
derived from this one.
void AlBlindData::setEndian()
Description
This method sets the
endian flag of the wrapper appropriately for the current platform. This
method must be the last one called in constructors of classes derived
from this one.
