Migrations

Functions for defining metanode migrations.

Functions

int VRAddInstanceMigration(	HNode	node,
	MigrationFunc	func,
	void *	userData
	)

int VRAddMigration(	HMeta	metaNode,
	MigrationAddFunc	func
	)

Adds a migration to the ordered list of migrations applied to the metanode.

The function provided is expected to be implemented to call VRSetMigration functions. (VRSetMigrationUp, VRSetMigrationDown, VRSetMigrationUpgradeNode, VRSetMigrationDowngradeNode)

The number of calls to this function during metanode creation defines the version number of the metanode.

Migrations can only be added to uninstantiated metanodes.

Parameters

metaNode	handle to the metanode to modify
func	function to call to register the migration specifics. This function is called immediately.

Returns: 0 if the migration is added successfully.

int VRChangePropertyArrayBool(	HMeta	metaNode,
	const char *	propName,
	int	numElements
	)

Changes the specified property to a VR_BOOL array type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change
numElements	number of elements in the new array property

Returns: 0 on success

int VRChangePropertyArrayChar(	HMeta	metaNode,
	const char *	propName,
	int	numElements
	)

Changes the specified property to a VR_CHAR array type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change
numElements	number of elements in the new array property

Returns: 0 on success

int VRChangePropertyArrayDouble(	HMeta	metaNode,
	const char *	propName,
	int	numElements
	)

Changes the specified property to a VR_DOUBLE array type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change
numElements	number of elements in the new array property

Returns: 0 on success

int VRChangePropertyArrayFloat(	HMeta	metaNode,
	const char *	propName,
	int	numElements
	)

Changes the specified property to a VR_FLOAT array type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change
numElements	number of elements in the new array property

Returns: 0 on success

int VRChangePropertyArrayInt(	HMeta	metaNode,
	const char *	propName,
	int	numElements
	)

Changes the specified property to a VR_INT array type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change
numElements	number of elements in the new array property

Returns: 0 on success

int VRChangePropertyArrayWorldFloat(	HMeta	metaNode,
	const char *	propName,
	int	numElements
	)

Changes the specified property to a VR_WORLD_FLOAT array type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change
numElements	number of elements in the new array property

Returns: 0 on success

int VRChangePropertyBool(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to single element VR_BOOL type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyChar(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to single element VR_CHAR type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyDouble(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to single element VR_DOUBLE type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyFloat(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to single element VR_FLOAT type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyInt(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to single element VR_INT type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyLink(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to single element VR_LINK type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyName(	HMeta	metaNode,
	const char *	propName,
	const char *	newPropName
	)

Renames a property.

Parameters

metaNode	handle to the metanode to change
propName	the name of the property to rename
newPropName	the new name of the property

Returns: 0 on success

int VRChangePropertyString(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to single element VR_STRING type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyVectorChar(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to a VR_VEC_CHAR type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyVectorFloat(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to a VR_VEC_FLOAT type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyVectorInt(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to a VR_VEC_INT type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyVectorString(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to a VR_VEC_STRING type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyVectorWorldFloat(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to a VR_VEC_WORLD_FLOAT type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

int VRChangePropertyWorldFloat(	HMeta	metaNode,
	const char *	propName
	)

Changes the specified property to single element VR_WORLD_FLOAT type.

Parameters

metaNode	handle to the metanode to change
propName	name of the property to change

Returns: 0 on success

void VRCloseMigrationHandle(

HMigration

migration

)

Closes a migration handle.

Parameters

migration	the handle to close

int VRMigrationCopyKnownProperties(	HMigration	migration,
	HNode	old,
	HNode	newNode
	)

Copies values of all properties that exist on both new and old node versions of the nodes. The nodes must be the same basic type, but may be different versions of that type. Properties that do not match in name or type between the versions are left for the migration implementation to handle.

Parameters

migration	migration handle
old	the old version of the node (source)
newNode	the new node to copy into (dest)

Returns: 0 on success

HNode VRMigrationCreateCurrentNode(	HMigration	migration,
	HNode	node
	)

Creates an instance of a node using the metanode version defined by this migration.

int VRMigrationFinish(	HMigration	migration,
	HNode	old,
	HNode	newNode
	)

Helper function for completing a migration step. This function moves all children of old to newNode, deletes old, and closes its handle.

Parameters

migration	the migration being completed
old	the node to clear and delete
newNode	the new parent of the children being moved

Returns: 0 on success

HMigration VRMigrationNext(

HMigration

migration

)

Gets the next migration in the chain (the one for the version after this one)

Parameters

migration	handle to the migration

Returns: the next migration or NULL if this is the newest one

HNode VRMigrationPrepareNode(	HMigration	migration,
	HNode	node
	)

Calls the registered upgrade node function of the migration previous or next to this one (depending on whether node is older or newer than migration). This effectively brings node up to date, ready for this migration to perform its upgrade.

Parameters

migration	handle to the migration
node	the node to transform to the version of this migration

Returns: handle to the node at the requested version.

HMigration VRMigrationPrev(

HMigration

migration

)

Gets the previous migration in the chain (the one for the version before this one)

Parameters

migration	handle to the migration

Returns: the previous migration or NULL if this is the oldest one

int VRRemoveProperty(	HMeta	metaNode,
	const char *	propertyName
	)

Removes a property from a metanode.

Parameters

metaNode	handle to the metanode to modify
propertyName	name of the property to remove

Returns: 0 if property is removed

int VRSetMigrationDown(	HMigration	migration,
	MigrationDownFunc	func
	)

Adds a downgrade function to a migration.

Parameters

migration	handle to migration to modify
func	function implementing the downgrade. the implementation need not close the handle parameters.

Returns: 0 if the function is added successfully

int VRSetMigrationDowngradeNode(	HMigration	migration,
	MigrationDowngradeFunc	func
	)

Adds a node downgrade function to a migration.

Parameters

migration	handle to migration to modify
func	function implementing the downgrade. the implementation need not close the handle parameters.

Returns: 0 if the function is added successfully

int VRSetMigrationUp(	HMigration	migration,
	MigrationUpFunc	func
	)

Adds an upgrade function to a migration.

Parameters

migration	handle to migration to modify
func	function implementing the upgrade. the implementation need not close the handle parameters.

Returns: 0 if the function is added successfully

int VRSetMigrationUpgradeNode(	HMigration	migration,
	MigrationUpgradeFunc	func
	)

Adds a node upgrade function to a migration.

Parameters

migration	handle to migration to modify
func	function implementing the upgrade. the implementation need not close the handle parameters.

Returns: 0 if the function is added successfully