#include <adskDataHandle.h>

Class Description

Class handling access to specific data members of a structured type.

This class provides an interface to the structured data through which any individual member can be accessed. It works in the class hierarchy controlled by adsk::Data::Associations; see the documentation for that class for the bigger picture of how the classes interrelate.

The adsk::Data::Structure class contains the description of the data type being referenced, including a description of how the data is stored so that the Handle knows how to access any particular member directly.

Examples:: MetadataSample/createMetadataCmd.cpp, MetadataSample/tweakMetadataNode.cpp, MetadataXML/streamSerializerXML.cpp, and sceneAssembly/adskSceneMetadataCmd.cpp.

Public Member Functions
	~Handle ()
	Destructor, gets rid of allocated memory if it is owned.

	Handle ()
	Default constructor, only present so that map can populate.

	Handle (const Handle &rhs)
	Copy constructor. More...

	Handle (const Structure &dataStructure)
	Standalone constructor, creates a chunk of memory with default structure data, owned by the Handle. More...

	Handle (const Structure &dataStructure, void *dataPointer)
	Usual constructor, initializes the owner of the data pointed to by this Handle. More...

Handle &	operator= (const Handle &rhs)
	Assignment operator. More...

bool	setPositionByMemberIndex (unsigned int memberIndex)
	Reposition the Handle to a specific member of the structure by index. More...

bool	setPositionByMemberName (const char *memberName)
	Reposition the Handle to a specific member of the structure by name. More...

void	pointToData (char *newData, bool ownsNewData)
	Redefine from where the Handle gets its data. More...

void	swap (Handle &rhs)
	Swap the contents of two Handles. More...

bool	makeUnique ()
	Make sure the data referenced by the Handle is its own copy. More...

bool	hasData () const
	Check to see if the Handle has valid data. More...

bool	isDefault () const
	Find out if the data pointed at by the Handle has all default values. More...

bool	isDefaultMember (const char *memberName) const
	Find out if the data pointed at by the Handle has default value at the named member. More...

Member::eDataType	dataType () const
	Find out what kind of data the Handle is currently pointing at. More...

unsigned int	dataLength () const
	Find out how many elements are in the data the Handle is currently pointing at. More...

bool	usesStructure (const Structure &comparedStructure) const
	Check to see if the Handle uses the given structure. More...

std::string	str (unsigned int dim) const
	Get the data currently pointed at by the Handle converted to a string. More...

unsigned int	fromStr (const std::string &value, unsigned int dim, std::string &errors)
	Set the data currently pointed at by the Handle from a string. More...

bool *	asBoolean ()
	Get the data currently pointed at by the Handle as a bool value. More...

double *	asDouble ()
	Get the data currently pointed at by the Handle as a double value. More...

double *	asDoubleMatrix4x4 ()
	Get the data currently pointed at by the Handle as a double value. More...

float *	asFloat ()
	Get the data currently pointed at by the Handle as a float value. More...

float *	asFloatMatrix4x4 ()
	Get the data currently pointed at by the Handle as a float value. More...

signed char *	asInt8 ()
	Get the data currently pointed at by the Handle as a char value. More...

short *	asInt16 ()
	Get the data currently pointed at by the Handle as a short value. More...

int *	asInt32 ()
	Get the data currently pointed at by the Handle as a int value. More...

int64_t *	asInt64 ()
	Get the data currently pointed at by the Handle as a int64_t value. More...

char **	asString ()
	Get the data currently pointed at by the Handle as a char* value. More...

unsigned char *	asUInt8 ()
	Get the data currently pointed at by the Handle as a unsigned char value. More...

unsigned short *	asUInt16 ()
	Get the data currently pointed at by the Handle as a unsigned short value. More...

unsigned int *	asUInt32 ()
	Get the data currently pointed at by the Handle as a unsigned int value. More...

uint64_t *	asUInt64 ()
	Get the data currently pointed at by the Handle as a uint64_t value. More...

void *	asType (Member::eDataType type)
	Get the data currently pointed at by the Handle as a specific type. More...

Static Public Member Functions
static bool	Debug (const Handle *me, Debug::Print &request)
	Answer a Print request for a Handle object. More...

static bool	Debug (const Handle *me, Debug::Footprint &request)
	Answer a footprint request for a Handle object. More...

Static Public Attributes
static const char *	kDebugType = "type"
	Flag indicating to print as hex.

Friends
class	StreamImpl
	Flag indicating to include type info in non-hex debug output. More...

Constructor & Destructor Documentation

Handle ( const Handle & rhs )

Copy constructor.

The normal usage of this constructor is to initialize a new Handle from one returned from a method : Handle h( stream.element( someElement ) )

Parameters

[in] rhs Handle to be copied

Handle ( const Structure & dataStructure )

Standalone constructor, creates a chunk of memory with default structure data, owned by the Handle.

Parameters

[in] dataStructure Structure which this Handle references

Handle	(	const Structure &	dataStructure,
		void *	dataPointer
	)

Usual constructor, initializes the owner of the data pointed to by this Handle.

Parameters

[in]	dataStructure	Structure which this Handle references
[in]	dataPointer	Direct pointer to data of the structure's type

Member Function Documentation

Handle & operator= ( const Handle & rhs )

Assignment operator.

The normal usage of this operator is to create a temporary state for assignment of Handles : Handle h = stream.element( someElement )

Parameters

[in] rhs Handle to be copied

Returns: Reference to the assigned Handle

bool setPositionByMemberIndex ( unsigned int index )

Reposition the Handle to a specific member of the structure by index.

This uses a brute force method to find the member; if this turns out to be a performance problem a different approach may be needed.

Parameters

[in] index Subindex of the structure member to point at

Returns: true if the Handle was successfully repositioned. Could fail if the index is invalid.

Examples:: MetadataXML/streamSerializerXML.cpp.

bool setPositionByMemberName ( const char * name )

Reposition the Handle to a specific member of the structure by name.

This uses a brute force method to find the member; if this turns out to be a performance problem a different approach may be needed.

Parameters

[in] name Name of the structure member to point at

Returns: true if the Handle was successfully repositioned. Could fail if the name was not found.

Examples:: sceneAssembly/adskSceneMetadataCmd.cpp.

void pointToData	(	char *	newData,
		bool	ownsNewData
	)

Redefine from where the Handle gets its data.

Parameters

[in]	newData	Pointer to new Handle data
[in]	ownsNewData	Is the Handle assming ownership of the new data?

void swap ( Handle & rhs )

Swap the contents of two Handles.

Used for in-place switching of two Handles, especially within a map. This method is helpful since it avoids the confusion of ownership that could result and the extra steps necessary to resolve it. (Copy- constructed Handles cannot steal ownership so if the standard trick of using a temp variable to swap 2 Handles is used all ownership will be lost, resulting in a leak.)

Parameters

[in] rhs Handle to be swapped

bool makeUnique ( )

Make sure the data referenced by the Handle is its own copy.

Normally in order to keep things lightweight Handle assignment only transfers a pointer to the original data. When a Handle is to be permanent or requires independent data modification it should call this method to ensure that it has its own unique copy of the data.

Returns: True if a new copy was made, false if it was already unique

bool hasData ( ) const

Check to see if the Handle has valid data.

Returns: true if the Handle points to valid data of any type

Examples:: MetadataSample/tweakMetadataNode.cpp.

bool isDefault ( ) const

Find out if the data pointed at by the Handle has all default values.

Returns: true if the Handle contains default values for all Structure members

bool isDefaultMember ( const char * memberName ) const

Find out if the data pointed at by the Handle has default value at the named member.

Parameters

[in] memberName The name of the member to check

Returns: true if the Handle contains default values for the named member

Member::eDataType dataType ( ) const

Find out what kind of data the Handle is currently pointing at.

Returns: data type currently pointed at by the Handle, Member::kInvalidType if not valid

Examples:: MetadataSample/tweakMetadataNode.cpp, and sceneAssembly/adskSceneMetadataCmd.cpp.

unsigned int dataLength ( ) const

Find out how many elements are in the data the Handle is currently pointing at.

Returns: number of elements in the Handle's data, 0 if not valid

Examples:: MetadataSample/tweakMetadataNode.cpp.

bool usesStructure ( const Structure & comparedStructure ) const

Check to see if the Handle uses the given structure.

The comparison verifies that the referenced structures are the same object. No effort is made to match structure layout for different objects. (So a clone of a Handle's structure will return false.)

Parameters

[in] comparedStructure Structure to compare against the one used by this handle

Returns: true if the Handle uses the given structure to describe its data

std::string str ( unsigned int dim ) const

Get the data currently pointed at by the Handle converted to a string.

Unlike the asXXX() methods, which return direct references to the data, this method returns a string representation of the current elements. In the case where the dimension of the data type is greater than 1 the "dim" parameter chooses between the available elements. e.g. a float[1] can be returned in a single call as "1.0" but a float[3] requires three calls: Handle::str(0) -> "1.0" Handle::str(1) -> "2.0" Handle::str(2) -> "3.0"

Parameters

[in] dim Dimension to be extracted

Returns: The current array of data as a space-separated string.

Examples:: MetadataXML/streamSerializerXML.cpp.

unsigned int fromStr	(	const std::string &	dataStr,
		unsigned int	dim,
		std::string &	errors
	)

Set the data currently pointed at by the Handle from a string.

The string passed in contains the same representation that would be generated by the str() method for this Handle. If the data wasn't recognized or there is no location for the parsed data then the method fails and the reason for the failure appears in the errors parameter.

All data formats are the obvious. The matrix elements appear in row major order: r1c1 r1c2 r1c3 r1c4 r2c1 r2c2 ... etc.

Parameters

[in]	dataStr	String containing the Handle values
[in]	dim	Dimension currently being read.
[out]	errors	Description of the parsing errors found

Returns: Number of errors found while parsing the Handle string

Examples:: sceneAssembly/adskSceneMetadataCmd.cpp.

bool * asBoolean ( )

Get the data currently pointed at by the Handle as a bool value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first bool data element, or NULL if the data isn't a bool or the Handle doesn't reference valid data

double * asDouble ( )

Get the data currently pointed at by the Handle as a double value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first double data element, or NULL if the data isn't a double or the Handle doesn't reference valid data

double * asDoubleMatrix4x4 ( )

Get the data currently pointed at by the Handle as a double value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first double data element, or NULL if the data isn't a double or the Handle doesn't reference valid data

float * asFloat ( )

Get the data currently pointed at by the Handle as a float value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first float data element, or NULL if the data isn't a float or the Handle doesn't reference valid data

float * asFloatMatrix4x4 ( )

Get the data currently pointed at by the Handle as a float value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first float data element, or NULL if the data isn't a float or the Handle doesn't reference valid data

signed char * asInt8 ( )

Get the data currently pointed at by the Handle as a char value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first char data element, or NULL if the data isn't a char or the Handle doesn't reference valid data

short * asInt16 ( )

Get the data currently pointed at by the Handle as a short value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first short data element, or NULL if the data isn't a short or the Handle doesn't reference valid data

int * asInt32 ( )

Get the data currently pointed at by the Handle as a int value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first int data element, or NULL if the data isn't a int or the Handle doesn't reference valid data

Examples:: MetadataSample/tweakMetadataNode.cpp.

int64_t * asInt64 ( )

Get the data currently pointed at by the Handle as a int64_t value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first int64_t data element, or NULL if the data isn't a int64_t or the Handle doesn't reference valid data

char ** asString ( )

Get the data currently pointed at by the Handle as a char* value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first char* data element, or NULL if the data isn't a char* or the Handle doesn't reference valid data

Examples:: sceneAssembly/adskSceneMetadataCmd.cpp.

unsigned char * asUInt8 ( )

Get the data currently pointed at by the Handle as a unsigned char value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first unsigned char data element, or NULL if the data isn't a unsigned char or the Handle doesn't reference valid data

unsigned short * asUInt16 ( )

Get the data currently pointed at by the Handle as a unsigned short value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first unsigned short data element, or NULL if the data isn't a unsigned short or the Handle doesn't reference valid data

unsigned int * asUInt32 ( )

Get the data currently pointed at by the Handle as a unsigned int value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first unsigned int data element, or NULL if the data isn't a unsigned int or the Handle doesn't reference valid data

uint64_t * asUInt64 ( )

Get the data currently pointed at by the Handle as a uint64_t value.

See adsk::Data::Handle::asType() for details on how to use this.

Returns: Pointer to the first uint64_t data element, or NULL if the data isn't a uint64_t or the Handle doesn't reference valid data

void * asType ( Member::eDataType type )

Get the data currently pointed at by the Handle as a specific type.

If the element has length greater than one then the subsequent members can be accessed by using the return pointer as an array pointer. e.g. for a float of length 3: float* fArray = reinterpret_cast<float*>( Handle.asType(Member::kFloat) ); float x = fArray[0]; float y = fArray[1]; float z = fArray[2];

Parameters

[in] type Type of member expected

Returns: Pointer to the native data type, or NULL if the data type doesn't match the element type or the Handle doesn't reference valid data

bool Debug	(	const Handle *	me,
		Debug::Print &	request
	)

static

Answer a Print request for a Handle object.

Use the request object to dump all information on the "me" Handle, or all static Handle information if "me" is NULL.

Parameters

[in]	me	Pointer to object to debug, NULL means class static
[out]	request	Print request object

Returns: True if the request was successfully processed.

bool Debug	(	const Handle *	me,
		Debug::Footprint &	request
	)

static

Answer a footprint request for a Handle object.

Populate the Footprint request with the information on all data stored within this class if "me" is NULL, otherwise the information stored in the Handle object pointed at by "me".

Parameters

[in]	me	Pointer to object to footprint, NULL means class static
[out]	request	Footprint object to populate

Returns: True if the request was successfully processed. The Footprint object will have all information added to it.

Friends And Related Function Documentation

friend class StreamImpl

friend

Flag indicating to include type info in non-hex debug output.

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

adskDataHandle.h
adskDataHandle.cpp

Handle Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation