General

General functions such as creation and deletion.

Functions

char VRCheckMetaHandleValid(

metaNode

)

Checks if a metanode handle is valid (that is, pointing at a metanode and not closed)

Parameters

metaNode	handle to check

Returns: 0 if invalid, 1 if valid

void VRCloseMetaHandle(

HMeta

metaNode

)

Closes a handle to a metanode.

HMeta VRCopyMetaNode(	HMeta	other,
	int	versionIncrement
	)

Copies a metanode internally in the API (that is, makes a new one with the same properties but doesn't give it to vrtree) It does this so that a migration can then modify it before VRFinishMetaNode is called as usual to instantiate it properly.

Parameters

other	handle to the metanode to copy
versionIncrement	automatically increments the version number by this much (negative for decrement)

Returns: new metanode

int VRCreateIntermediateMetaNodes(	HMeta	start,
	HMeta	end
	)

Performs migrations of a metanode to create all known versions between start and end.

Parameters

start	handle to the metanode to use as the starting point for migrations
end	handle to the metanode to migrate to (versions are created until this version, but does not create this version)

Returns: int the number of intermediate metanodes that exist between the requested versions, or -1 on failure

Note

Uses the version of start to begin - if end is > start, up migrations are used, otherwise down migrations are used.

HMeta VRCreateMetaNode(

const char *

metaName

)

Creates a metanode (a description of a node structure).

Metanodes start at version 0, and their version is incremented by VRAddMigration.

Once a metanode has been instantiated (by creating a Node of this type), no further modifications are allowed to its structure.

Parameters

metaName	the name of the new metanode

Returns: a handle to the metanode, for use with other metanode functions

HMeta VRCreateMetaNodeEx(	const char *	metaName,
	uint32_t	flags
	)

Creates a metanode (a description of a node structure) with additional flags.

Parameters

metaName	the name of the new metanode
flags	the flags to apply

Returns: a handle to the metanode, for use with other metanode functions

size_t VRCurrentMetaNodeVersion(	const char *	metaName,
	char *	buffer,
	size_t	bufferSize
	)

Gets the name of the current version of the specified metanode.

Parameters

metaName	the name of the metanode (no version suffix)
buffer	the variable to recieve the name of the current version of this metanode
bufferSize	size of the output buffer

Returns: number of bytes written to outputBuffer

Note

if buffer is null, function returns the required size of the buffer

int VRDeleteMetaNode(

HMeta

metaNode

)

Deletes a metanode. Can only be done if there are no instances of the metanode and the metanode structure has not been passed to vrtree.

Parameters

metaNode	handle to the metanode to delete

Returns: 0 on success. If successful, the handle is closed automatically

int VRFinishMetaNode(

HMeta

metaNode

)

Finishes a metanode definition by passing it to VRTree.

At this point, modifications to the metanode can no longer be made because the total number of migrations is used to set the metanode version.

Parameters

metaNode	handle to the metanode to finish. this handle is closed by this function

Returns: 0 on success

HMeta VRFinishMetaNodeEx(

HMeta

metaNode

)

Finishes a metanode definition by passing it to VRTree.

At this point, modifications to the metanode can no longer be made because the total number of migrations is used to set the metanode version.

Parameters

metaNode	handle to the metanode to finish. this handle is closed by this function

Returns: a new handle to the real metanode

size_t VRGetMetaNodeName(	HMeta	metaNode,
	char *	buffer,
	size_t	bufferLength
	)

Gets the name of a metanode.

Parameters

metaNode	handle to the metanode
buffer	a buffer to receive the node name as a null terminated string
size	size of the buffer

Returns: the number of characters written to the buffer (including trailing null)

size_t VRGetMetaNodeNameLength(

HMeta

metaNode

)

Gets the length of a metanode's name, plus 1 for the trailing null terminator.

Parameters

metaNode	handle to the metanode