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.
