Skip to main content

Migrations

Module: Metanodes

Functions for defining metanode migrations.

Functions​

TypeName
intVRAddInstanceMigration(HNode node, MigrationFunc func, void * userData)
intVRAddMigration(HMeta metaNode, MigrationAddFunc func)
Adds a migration to the ordered list of migrations applied to the metanode.
intVRChangePropertyArrayBool(HMeta metaNode, const char * propName, int numElements)
Changes the specified property to a VR_BOOL array type.
intVRChangePropertyArrayChar(HMeta metaNode, const char * propName, int numElements)
Changes the specified property to a VR_CHAR array type.
intVRChangePropertyArrayDouble(HMeta metaNode, const char * propName, int numElements)
Changes the specified property to a VR_DOUBLE array type.
intVRChangePropertyArrayFloat(HMeta metaNode, const char * propName, int numElements)
Changes the specified property to a VR_FLOAT array type.
intVRChangePropertyArrayInt(HMeta metaNode, const char * propName, int numElements)
Changes the specified property to a VR_INT array type.
intVRChangePropertyArrayWorldFloat(HMeta metaNode, const char * propName, int numElements)
Changes the specified property to a VR_WORLD_FLOAT array type.
intVRChangePropertyBool(HMeta metaNode, const char * propName)
Changes the specified property to single element VR_BOOL type.
intVRChangePropertyChar(HMeta metaNode, const char * propName)
Changes the specified property to single element VR_CHAR type.
intVRChangePropertyDouble(HMeta metaNode, const char * propName)
Changes the specified property to single element VR_DOUBLE type.
intVRChangePropertyFloat(HMeta metaNode, const char * propName)
Changes the specified property to single element VR_FLOAT type.
intVRChangePropertyInt(HMeta metaNode, const char * propName)
Changes the specified property to single element VR_INT type.
intVRChangePropertyLink(HMeta metaNode, const char * propName)
Changes the specified property to single element VR_LINK type.
intVRChangePropertyName(HMeta metaNode, const char * propName, const char * newPropName)
Renames a property.
intVRChangePropertyString(HMeta metaNode, const char * propName)
Changes the specified property to single element VR_STRING type.
intVRChangePropertyVectorChar(HMeta metaNode, const char * propName)
Changes the specified property to a VR_VEC_CHAR type.
intVRChangePropertyVectorFloat(HMeta metaNode, const char * propName)
Changes the specified property to a VR_VEC_FLOAT type.
intVRChangePropertyVectorInt(HMeta metaNode, const char * propName)
Changes the specified property to a VR_VEC_INT type.
intVRChangePropertyVectorString(HMeta metaNode, const char * propName)
Changes the specified property to a VR_VEC_STRING type.
intVRChangePropertyVectorWorldFloat(HMeta metaNode, const char * propName)
Changes the specified property to a VR_VEC_WORLD_FLOAT type.
intVRChangePropertyWorldFloat(HMeta metaNode, const char * propName)
Changes the specified property to single element VR_WORLD_FLOAT type.
voidVRCloseMigrationHandle(HMigration migration)
Closes a migration handle.
intVRMigrationCopyKnownProperties(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.
HNodeVRMigrationCreateCurrentNode(HMigration migration, HNode node)
Creates an instance of a node using the metanode version defined by this migration.
intVRMigrationFinish(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.
HMigrationVRMigrationNext(HMigration migration)
Gets the next migration in the chain (the one for the version after this one)
HNodeVRMigrationPrepareNode(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.
HMigrationVRMigrationPrev(HMigration migration)
Gets the previous migration in the chain (the one for the version before this one)
intVRRemoveProperty(HMeta metaNode, const char * propertyName)
Removes a property from a metanode.
intVRSetMigrationDown(HMigration migration, MigrationDownFunc func)
Adds a downgrade function to a migration.
intVRSetMigrationDowngradeNode(HMigration migration, MigrationDowngradeFunc func)
Adds a node downgrade function to a migration.
intVRSetMigrationUp(HMigration migration, MigrationUpFunc func)
Adds an upgrade function to a migration.
intVRSetMigrationUpgradeNode(HMigration migration, MigrationUpgradeFunc func)
Adds a node upgrade function to a migration.

Functions Documentation​

VRAddInstanceMigration​

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

VRAddMigration​

int VRAddMigration(
    HMeta metaNode,
    MigrationAddFunc func
)

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

Parameters:

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

Return: 0 if the migration is added successfully.

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.

VRChangePropertyArrayBool​

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

Return: 0 on success

VRChangePropertyArrayChar​

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

Return: 0 on success

VRChangePropertyArrayDouble​

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

Return: 0 on success

VRChangePropertyArrayFloat​

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

Return: 0 on success

VRChangePropertyArrayInt​

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

Return: 0 on success

VRChangePropertyArrayWorldFloat​

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

Return: 0 on success

VRChangePropertyBool​

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

Return: 0 on success

VRChangePropertyChar​

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

Return: 0 on success

VRChangePropertyDouble​

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

Return: 0 on success

VRChangePropertyFloat​

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

Return: 0 on success

VRChangePropertyInt​

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

Return: 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

Return: 0 on success

VRChangePropertyName​

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

Return: 0 on success

VRChangePropertyString​

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

Return: 0 on success

VRChangePropertyVectorChar​

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

Return: 0 on success

VRChangePropertyVectorFloat​

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

Return: 0 on success

VRChangePropertyVectorInt​

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

Return: 0 on success

VRChangePropertyVectorString​

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

Return: 0 on success

VRChangePropertyVectorWorldFloat​

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

Return: 0 on success

VRChangePropertyWorldFloat​

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

Return: 0 on success

VRCloseMigrationHandle​

void VRCloseMigrationHandle(
    HMigration migration
)

Closes a migration handle.

Parameters:

  • migration the handle to close

VRMigrationCopyKnownProperties​

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)

Return: 0 on success

VRMigrationCreateCurrentNode​

HNode VRMigrationCreateCurrentNode(
    HMigration migration,
    HNode node
)

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

VRMigrationFinish​

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

Return: 0 on success

VRMigrationNext​

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

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

VRMigrationPrepareNode​

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

Return: handle to the node at the requested version.

VRMigrationPrev​

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

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

VRRemoveProperty​

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

Return: 0 if property is removed

VRSetMigrationDown​

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.

Return: 0 if the function is added successfully

VRSetMigrationDowngradeNode​

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.

Return: 0 if the function is added successfully

VRSetMigrationUp​

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.

Return: 0 if the function is added successfully

VRSetMigrationUpgradeNode​

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.

Return: 0 if the function is added successfully