- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends

# Handle Class Reference

This reference page is linked to from the following overview topics: Autodesk Maya 2014, Meta Data.

Search for all occurrences

## Detailed 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.

`#include <adskDataHandle.h>`

List of all members.

## 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.
| Handle (const Structure &dataStructure)
| Standalone constructor, creates a chunk of memory with default structure data, owned by the Handle.
| Handle (const Structure &dataStructure, void *dataPointer)
| Usual constructor, initializes the owner of the data pointed to by this Handle.
Handle & | operator= (const Handle &rhs)
| Assignment operator.
bool | setPositionByMemberIndex (unsigned int memberIndex)
| Reposition the Handle to a specific member of the structure by index.
bool | setPositionByMemberName (const char *memberName)
| Reposition the Handle to a specific member of the structure by name.
void | pointToData (char *newData, bool ownsNewData)
| Redefine from where the Handle gets its data.
void | swap (Handle &rhs)
| Swap the contents of two Handles.
bool | makeUnique ()
| Make sure the data referenced by the Handle is its own copy.
bool | hasData () const
| Check to see if the Handle has valid data.
bool | isDefault () const
| Find out if the data pointed at by the Handle has all default values.
bool | isDefaultMember (const char *memberName) const
| Find out if the data pointed at by the Handle has default value at the named member.
Member::eDataType | dataType () const
| Find out what kind of data the Handle is currently pointing at.
unsigned int | dataLength () const
| Find out how many elements are in the data the Handle is currently pointing at.
bool | usesStructure (const Structure &comparedStructure) const
| Check to see if the Handle uses the given structure.
std::string | str (unsigned int dim) const
| Get the data currently pointed at by the Handle converted to a string.
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.
bool * | asBoolean ()
| Get the data currently pointed at by the Handle as a bool value.
double * | asDouble ()
| Get the data currently pointed at by the Handle as a double value.
double * | asDoubleMatrix4x4 ()
| Get the data currently pointed at by the Handle as a double value.
float * | asFloat ()
| Get the data currently pointed at by the Handle as a float value.
float * | asFloatMatrix4x4 ()
| Get the data currently pointed at by the Handle as a float value.
signed char * | asInt8 ()
| Get the data currently pointed at by the Handle as a char value.
short * | asInt16 ()
| Get the data currently pointed at by the Handle as a short value.
int * | asInt32 ()
| Get the data currently pointed at by the Handle as a int value.
int64_t * | asInt64 ()
| Get the data currently pointed at by the Handle as a int64_t value.
char ** | asString ()
| Get the data currently pointed at by the Handle as a char* value.
unsigned char * | asUInt8 ()
| Get the data currently pointed at by the Handle as a unsigned char value.
unsigned short * | asUInt16 ()
| Get the data currently pointed at by the Handle as a unsigned short value.
unsigned int * | asUInt32 ()
| Get the data currently pointed at by the Handle as a unsigned int value.
uint64_t * | asUInt64 ()
| Get the data currently pointed at by the Handle as a uint64_t value.
void * | asType (Member::eDataType type)
| Get the data currently pointed at by the Handle as a specific type.
## Static Public Member Functions
static bool | Debug (const Handle *me, Debug::Print &request)
| Answer a Print request for a Handle object.
static bool | Debug (const Handle *me, Debug::Footprint &request)
| Answer a footprint request for a Handle object.
## 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. Search for all occurrences

## 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 | ) |

Search for all occurrences

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.

bool setPositionByMemberName | ( | const char * | name | ) |

Search for all occurrences

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.

void pointToData | ( | char * | newData,
|  | bool | ownsNewData
| ) |  |

Search for all occurrences

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 | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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

Search for all occurrences

Check to see if the Handle has valid data.

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

bool isDefault | ( |  | ) | const

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

unsigned int dataLength | ( |  | ) | const

Search for all occurrences

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

bool usesStructure | ( | const Structure & | comparedStructure | ) | const

Search for all occurrences

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

Search for all occurrences

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.

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

Search for all occurrences

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

bool * asBoolean | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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

int64_t * asInt64 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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

unsigned char * asUInt8 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ) |

Search for all occurrences

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]`

Search for all occurrences

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]`

Search for all occurrences

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]`

Search for all occurrences

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

Handle Handle Handle Handle Handle Handle Handle Handle Handle Handle
Handle Handle Handle Handle Handle Handle Handle Handle Handle Handle