gxvariant.h File Reference

---

Detailed Description

Gx variant - a complex data structure

The gxVARIANT type was introduced to easily form dynamically expandable complex data structures which are usable in different programming languages under various operational environments. The gxVARIANT is the basic unit of these complex data structures, and it has the following important features:

• Stores basic data types as well as arrays or strings.
• Uses run-time type information for automatic data conversion on user request.
• Stores id or name which can be used to identify data in a complex structure.
• Stores children. The variants can be connected together in a way that they form a tree through parent-child relationships.
• Uses reference counting to save memory and to form a closed tree.
• It can be a list, in which the items are connected according to parent-children hierarchy. The list and list items can have children too.

Go to the source code of this file.

Functions
Create, modify, read variants
int	gx_createvariant (gxVARIANT *variant, int id, const wchar_t *name, GX_VARIANT_TYPES type, int size, const void *data, int nitems=1)
	Creates a new variant.
int	gx_updatevariant (gxVARIANT variant, int id, const wchar_t *name, GX_VARIANT_TYPES type, int size, const void *data, int nitems=1)
	Modifies a variant.
int	gx_updatevariantdata (gxVARIANT variant, GX_VARIANT_TYPES type, int size, const void *data, int nitems=1)
	Modifies the data of a variant.
int	gx_changevariantname (gxVARIANT variant, const wchar_t *name)
	Changes the name of a variant.
int	gx_getvariantinfo (gxVARIANT variant, int *id, wchar_t *namebuff, int namebuffsize, GX_VARIANT_TYPES *type, int *size, int *nitems, int *nchildren)
	Gives information about a variant.
int	gx_convertvariant (gxVARIANT variant, GX_VARIANT_TYPES type, void *target, int tgtlen, int *size=0, int *nitems=0)
	Returns a variant's data converted to a specified type.
Work with list type variants
int	gx_getvariantitem (gxVARIANT list, int flags, int id, const wchar_t *name, int *ix, gxVARIANT *target)
	Returns an item from a list type variant.
int	gx_getvariantitem (gxVARIANT list, int flags, int id, const wchar_t *name, int ix, gxVARIANT *target)
	Returns an item from a list type variant.
int	gx_cutvariantitem (gxVARIANT list, int flags, int id, const wchar_t *name, int ix, gxVARIANT *target=0)
	Cuts and returns an item from a list type variant.
int	gx_findvariantitem (gxVARIANT list, gxVARIANT item, int flags, int *ix)
	Returns the index of a variant element located in a list type variant.
int	gx_addvariantitem (gxVARIANT list, int flags, int id, const wchar_t *name, int ix, gxVARIANT item)
	Adds an item to a list type variant.
int	gx_createvariantitem (gxVARIANT list, int id, const wchar_t *name, GX_VARIANT_TYPES type, int size, const void *data, int nitems=1, gxVARIANT *item=0)
	Creates a new variant and appends to a list type variant.
int	gx_convertvariantitem (gxVARIANT list, int id, const wchar_t *name, int ix, GX_VARIANT_TYPES type, void *target, int tgtlen, int *size=0, int *nitems=0)
	Returns the data of an item in a list type variant converted to a specified type.
Work with children
int	gx_getvariantchild (gxVARIANT parent, int flags, int id, const wchar_t *name, int *ix, gxVARIANT *target)
	Returns a child of a variant.
int	gx_getvariantchild (gxVARIANT parent, int flags, int id, const wchar_t *name, int ix, gxVARIANT *target)
	Returns a child of a variant.
int	gx_cutvariantchild (gxVARIANT parent, int flags, int id, const wchar_t *name, int ix, gxVARIANT *target=0)
	Cuts and returns a child of a variant.
int	gx_findvariantchild (gxVARIANT parent, gxVARIANT child, int flags, int *ix)
	Returns the index of a child element located in a variant's children list.
int	gx_addvariantchild (gxVARIANT parent, int flags, int id, const wchar_t *name, int ix, gxVARIANT child)
	Adds a child element to a variant.
int	gx_createvariantchild (gxVARIANT parent, int id, const wchar_t *name, GX_VARIANT_TYPES type, int size, const void *data, int nitems=1, gxVARIANT *child=0)
	Creates a new variant and appends it to a variant as a child.
int	gx_convertvariantchild (gxVARIANT parent, int id, const wchar_t *name, int ix, GX_VARIANT_TYPES type, void *target, int tgtlen, int *size=0, int *nitems=0)
	Returns the data of a variant's child converted to a specified type.
Work with descendant variants
int	gx_convertvariantbypath (gxVARIANT root, const wchar_t *path, GX_VARIANT_TYPES type, void *target, int tgtlen, int *size=0, int *nitems=0)
	Returns the data of a variant located in a variant tree converted to a specified type.

---

Function Documentation

int gx_createvariant	(	gxVARIANT *	variant,
		int	id,
		const wchar_t *	name,
		GX_VARIANT_TYPES	type,
		int	size,
		const void *	data,
		int	nitems = 1
	)			[inline]

Creates a new variant.

Note:

For creating a list type variant the size, the data and the nitems parameters have to be 0.

Parameters:

	variant	Buffer for the result. To free up the used memory call the gx_unrefvariant() or the gx_leavevariant() function.
	id	The id of the new variant.
	name	The name of the new variant.
	type	The type of the new variant.
	size	The size of the new variant.
	data	The data of the new variant.
	nitems	The number of items of the new variant. This value is usually 1, except for list and array types.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

Referenced by gxVariant::Create(), gxVariant::CreateArray(), gxVariant::CreateEmpty(), gxVariant::CreateEmptyList(), gxVariant::CreateList(), gx_createvariantchild(), and gx_createvariantitem().

int gx_updatevariant	(	gxVARIANT	variant,
		int	id,
		const wchar_t *	name,
		GX_VARIANT_TYPES	type,
		int	size,
		const void *	data,
		int	nitems = 1
	)			[inline]

Modifies a variant.

Modifying the data structure of a variant affects all the variables that references the same memory area. Therefore all the modifications are automatically reflected in the data structure of those variants.

Note:

Updating the data structure does not affect the children of the variant.

For generating a list type variant the size, the data and the nitems parameters have to be 0.

Parameters:

	variant	Variant to modify.
	id	The new id of the variant.
	name	The new name of the variant.
	type	The new type of the variant.
	size	The new size of the variant.
	data	The new data of the variant.
	nitems	The new number of items of the variant. This value is usually 1, except for list and array types.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

int gx_updatevariantdata	(	gxVARIANT	variant,
		GX_VARIANT_TYPES	type,
		int	size,
		const void *	data,
		int	nitems = 1
	)			[inline]

Modifies the data of a variant.

Modifying the data structure of a variant affects all the variables that references the same memory area. Therefore all the modifications are automatically reflected in the data structure of those variants.

Note:

Updating the data structure does not affect the children of the variant.

For generating a list type variant the size, the data and the nitems parameters have to be 0.

Parameters:

	variant	Variant to modify.
	type	The new type of the variant.
	size	The new size of the variant.
	data	The new data of the variant.
	nitems	The new number of items of the variant. This value is usually 1, except for list and array types.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

int gx_changevariantname	(	gxVARIANT	variant,
		const wchar_t *	name
	)			[inline]

Changes the name of a variant.

Changing the name of a variant affects all the variables that references the same memory area. Therefore all the modifications are automatically reflected in the data structure of those variants.

Parameters:

	variant	Variant to modify.
	name	The new name of the variant.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

int gx_getvariantinfo	(	gxVARIANT	variant,
		int *	id,
		wchar_t *	namebuff,
		int	namebuffsize,
		GX_VARIANT_TYPES *	type,
		int *	size,
		int *	nitems,
		int *	nchildren
	)			[inline]

Gives information about a variant.

Note:

Uninterested buffers can be NULL.

Parameters:

	variant	Variant to process.
	id	Buffer for the id.
	namebuff	Buffer for the name.
	namebuffsize	The size of the name buffer.
	type	Buffer for the type.
	size	Buffer for the size.
	nitems	Buffer for the number of items.
	nchildren	Buffer for the number of children.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

int gx_convertvariant	(	gxVARIANT	variant,
		GX_VARIANT_TYPES	type,
		void *	target,
		int	tgtlen,
		int *	size = 0,
		int *	nitems = 0
	)			[inline]

Returns a variant's data converted to a specified type.

Parameters:

	variant	Variant to process.
	type	Type to convert to.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.
	size	Pointer to the item size. The function can modify this value. This value is useful in case of array handling or when the modified value is needed. Otherwise it can be NULL.
	nitems	Pointer to the number of items. The function can modify this value. This value is useful in case of array handling. Otherwise it can be NULL.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

Referenced by gxVariant::Convert(), gxVariant::GetASCII(), gxVariant::GetFloat(), gxVariant::GetGxPG4(), gxVariant::GetInt(), gxVariant::GetUInt(), gxVariant::GetULInt(), gxVariant::GetUnicode(), gx_convertvariantbypath(), gx_convertvariantchild(), and gx_convertvariantitem().

int gx_getvariantitem	(	gxVARIANT	list,
		int	flags,
		int	id,
		const wchar_t *	name,
		int *	ix,
		gxVARIANT *	target
	)			[inline]

Returns an item from a list type variant.

Note:

The actual role of the id, name and ix parameters depends on the flags parameter.

Parameters:

	list	List type variant.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	id	Id of the requested item.
	name	Name of the requested item.
	ix	Pointer to the index of the requested item. On success the item index is returned.
	target	Buffer for the result. The reference counter of this variant is increased internally. To sign the end of usage call the gx_unrefvariant() or the gx_leavevariant() function.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

Referenced by gxVariant::GetItem(), gx_convertvariantitem(), and gx_getvariantitem().

int gx_getvariantitem	(	gxVARIANT	list,
		int	flags,
		int	id,
		const wchar_t *	name,
		int	ix,
		gxVARIANT *	target
	)			[inline]

Returns an item from a list type variant.

Note:

The actual role of the id, name and ix parameters depends on the flags parameter.

Parameters:

	list	List type variant.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	id	Id of the requested item.
	name	Name of the requested item.
	ix	Index of the requested item.
	target	Buffer for the result. The reference counter of this variant is increased internally. To sign the end of usage call the gx_unrefvariant() or the gx_leavevariant() function.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_getvariantitem().

int gx_cutvariantitem	(	gxVARIANT	list,
		int	flags,
		int	id,
		const wchar_t *	name,
		int	ix,
		gxVARIANT *	target = 0
	)			[inline]

Cuts and returns an item from a list type variant.

Note:

The actual role of the id, name and ix parameters depends on the flags parameter.

Parameters:

	list	List type variant.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	id	The id of the requested item to cut.
	name	The name of the requested item to cut.
	ix	The index of the requested item to cut.
	target	Buffer for the result. To sign the end of usage call the gx_unrefvariant() or the gx_leavevariant() function. This parameter can be NULL to simply remove the variant item. In this case the function calls the gx_leavevariant function automatically.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call(), and gx_leavevariant().

Referenced by gxVariant::CutItem().

int gx_findvariantitem	(	gxVARIANT	list,
		gxVARIANT	item,
		int	flags,
		int *	ix
	)			[inline]

Returns the index of a variant element located in a list type variant.

Parameters:

	list	List type variant.
	item	Item of the list to search for.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	ix	Buffer for the list index according to the flags parameter.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

Referenced by gxVariant::FindItem().

int gx_addvariantitem	(	gxVARIANT	list,
		int	flags,
		int	id,
		const wchar_t *	name,
		int	ix,
		gxVARIANT	item
	)			[inline]

Adds an item to a list type variant.

Note:

The actual role of the id, name and ix parameters depends on the flags parameter.

Parameters:

	list	List type variant.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	id	The id of the item located on the position where to insert or append the new item.
	name	The name of the item located on the position where to insert or append the new item.
	ix	The index of the position where to insert or append the new item.
	item	The new item to add to the list. The reference counter of this variant is increased internally.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

Referenced by gxVariant::AddItem(), gxVariant::CreateList(), and gx_createvariantitem().

int gx_createvariantitem	(	gxVARIANT	list,
		int	id,
		const wchar_t *	name,
		GX_VARIANT_TYPES	type,
		int	size,
		const void *	data,
		int	nitems = 1,
		gxVARIANT *	item = 0
	)			[inline]

Creates a new variant and appends to a list type variant.

Note:

For creating a list type variant the size, the data and the nitems parameters have to be 0.

Parameters:

	list	List type variant.
	id	The id of the new variant.
	name	The name of the new variant.
	type	The type of the new variant.
	size	The size of the new variant.
	data	The data of the new variant.
	nitems	The number of items of the new variant. This value is usually 1, except for list and array types.
	item	Buffer for the new variant. It can be NULL. The reference counter of the new variant will be set to 1 so it does not need unreferencing.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_addvariantitem(), gx_createvariant(), gx_leavevariant(), gx_poperror(), gx_pusherror(), gx_unrefvariant(), and GX_VARIANT_LAST.

int gx_convertvariantitem	(	gxVARIANT	list,
		int	id,
		const wchar_t *	name,
		int	ix,
		GX_VARIANT_TYPES	type,
		void *	target,
		int	tgtlen,
		int *	size = 0,
		int *	nitems = 0
	)			[inline]

Returns the data of an item in a list type variant converted to a specified type.

Note:

The actual role of the id, name and ix parameters depends on the name parameter. If it is present the search is made by order and name, if it is NULL the system use the 'by order and id' algorithm.

Parameters:

	list	List type variant.
	id	Id of the requested item.
	name	Name of the requested item.
	ix	Index of the requested item.
	type	Type to convert to.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.
	size	Pointer to the item size. The function can modify this value. This value is useful in case of array handling or when the modified value is needed. Otherwise it can be NULL.
	nitems	Pointer to the number of items. The function can modify this value. This value is useful in case of array handling. Otherwise it can be NULL.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_convertvariant(), gx_getvariantitem(), gx_leavevariant(), gx_poperror(), gx_pusherror(), GX_VARIANT_BY_ORDER_AND_ID, and GX_VARIANT_BY_ORDER_AND_NAME.

int gx_getvariantchild	(	gxVARIANT	parent,
		int	flags,
		int	id,
		const wchar_t *	name,
		int *	ix,
		gxVARIANT *	target
	)			[inline]

Returns a child of a variant.

Note:

The actual role of the id, name and ix parameters depends on the flags parameter.

Parameters:

	parent	Parent variant to process.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	id	Id of the requested child.
	name	Name of the requested child.
	ix	Pointer to the index of the requested child. On success the child index is returned.
	target	Buffer for the result. The reference counter of this variant is increased internally. To sign the end of usage call the gx_unrefvariant() or the gx_leavevariant() function.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

Referenced by gxVariant::GetChild(), gx_convertvariantchild(), and gx_getvariantchild().

int gx_getvariantchild	(	gxVARIANT	parent,
		int	flags,
		int	id,
		const wchar_t *	name,
		int	ix,
		gxVARIANT *	target
	)			[inline]

Returns a child of a variant.

Note:

The actual role of the id, name and ix parameters depends on the flags parameter.

Parameters:

	parent	Parent variant to process.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	id	Id of the requested child.
	name	Name of the requested child.
	ix	Index of the requested child.
	target	Buffer for the result. The reference counter of this variant is increased internally. To sign the end of usage call the gx_unrefvariant() or the gx_leavevariant() function.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_getvariantchild().

int gx_cutvariantchild	(	gxVARIANT	parent,
		int	flags,
		int	id,
		const wchar_t *	name,
		int	ix,
		gxVARIANT *	target = 0
	)			[inline]

Cuts and returns a child of a variant.

Note:

The actual role of the id, name and ix parameters depends on the flags parameter.

Parameters:

	parent	Parent variant to process.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	id	The id of the requested child to cut.
	name	The name of the requested child to cut.
	ix	The index of the requested child to cut.
	target	Buffer for the result. To sign the end of usage call the gx_unrefvariant() or the gx_leavevariant() function. This parameter can be NULL to simply remove the child. In this case the function calls the gx_leavevariant function automatically.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call(), and gx_leavevariant().

Referenced by gxVariant::CutChild().

int gx_findvariantchild	(	gxVARIANT	parent,
		gxVARIANT	child,
		int	flags,
		int *	ix
	)			[inline]

Returns the index of a child element located in a variant's children list.

Parameters:

	parent	Parent variant to process.
	child	Child to search for.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	ix	Buffer for the child index according to the flags parameter.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

Referenced by gxVariant::FindChild().

int gx_addvariantchild	(	gxVARIANT	parent,
		int	flags,
		int	id,
		const wchar_t *	name,
		int	ix,
		gxVARIANT	child
	)			[inline]

Adds a child element to a variant.

Note:

The actual role of the id, name and ix parameters depends on the flags parameter.

Parameters:

	parent	Parent variant to process.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	id	The id of the child located on the position where to insert or append the new child.
	name	The name of the child located on the position where to insert or append the new child.
	ix	The index of the position where to insert or append the new child.
	child	The new child to add to the children list. The reference counter of this variant is increased internally.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_call().

Referenced by gxVariant::AddChild(), and gx_createvariantchild().

int gx_createvariantchild	(	gxVARIANT	parent,
		int	id,
		const wchar_t *	name,
		GX_VARIANT_TYPES	type,
		int	size,
		const void *	data,
		int	nitems = 1,
		gxVARIANT *	child = 0
	)			[inline]

Creates a new variant and appends it to a variant as a child.

Note:

For creating a list type variant the size, the data and the nitems parameters have to be 0.

Parameters:

	parent	Parent variant to process.
	id	The id of the new variant.
	name	The name of the new variant.
	type	The type of the new variant.
	size	The size of the new variant.
	data	The data of the new variant.
	nitems	The number of items of the new variant. This value is usually 1, except for list and array types.
	child	Buffer for the new variant. It can be NULL. The reference counter of the new variant will be set to 1 so it does not need unreferencing.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_addvariantchild(), gx_createvariant(), gx_leavevariant(), gx_poperror(), gx_pusherror(), gx_unrefvariant(), and GX_VARIANT_LAST.

int gx_convertvariantchild	(	gxVARIANT	parent,
		int	id,
		const wchar_t *	name,
		int	ix,
		GX_VARIANT_TYPES	type,
		void *	target,
		int	tgtlen,
		int *	size = 0,
		int *	nitems = 0
	)			[inline]

Returns the data of a variant's child converted to a specified type.

Note:

The actual role of the id, name and ix parameters depends on the name parameter. If it is present the search is made by order and name, if it is NULL the system use the 'by order and id' algorithm.

Parameters:

	parent	Parent variant to process.
	id	Id of the requested child.
	name	Name of the requested child.
	ix	Index of the requested child.
	type	Type to convert to.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.
	size	Pointer to the item size. The function can modify this value. This value is useful in case of array handling or when the modified value is needed. Otherwise it can be NULL.
	nitems	Pointer to the number of items. The function can modify this value. This value is useful in case of array handling. Otherwise it can be NULL.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_convertvariant(), gx_getvariantchild(), gx_leavevariant(), gx_poperror(), gx_pusherror(), GX_VARIANT_BY_ORDER_AND_ID, and GX_VARIANT_BY_ORDER_AND_NAME.

int gx_convertvariantbypath	(	gxVARIANT	root,
		const wchar_t *	path,
		GX_VARIANT_TYPES	type,
		void *	target,
		int	tgtlen,
		int *	size = 0,
		int *	nitems = 0
	)			[inline]

Returns the data of a variant located in a variant tree converted to a specified type.

The variant data type can constitute a tree structure: every item in the tree is a variant, and in turn can have child items. The trees can be traversed layer-by-layer with the help of gx_getvariantchild() and gx_getvariantitem() functions and then conversion can be made on some data with the gx_convertvariant() function. If there is a need to reach a descendant variant located in a deep layer for converting just one variant item, this function should be used instead. The item in the tree can be obtained by the path string, which defines the exact location of the requested variant and has the following format:

condition[=value] [,condition[=value]] [/condition[=value] [,condition[=value]]]

The path contains separators:

• the '/' separates the levels of the tree,
• the ',' separates the search conditions of a node,
• the '=' signs that a value follows,

and identifiers:

• the 'C' selects a child item,
• the 'L' selects a list item,
• the 'X' signs that the value defines the index of the item,
• the 'D' signs that the value defines the id of the item,
• the 'N' signs that the value defines the name of the item,
• the 'V' signs that the value defines the value of the item.

The values are used as integers except 'name' values which have to be quoted with " or ' character; and 'value' values which may be quoted with " or ' character to sign that string comparison is requested. Indexing is made by order. ( see GX_VARIANT_FLAGS )

for example:

 // select the 3-rd (started from 0-th) worker whose name is John from the variant
 swprintf(path, L"C,D=%i/L,N='%s',V='%s',X=%i", ID_WORKERS, L"name", L"John", 3);

Parameters:

	root	Root variant to process.
	path	The path string.
	type	Type to convert to.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.
	size	Pointer to the item size. The function can modify this value. This value is useful in case of array handling or when the modified value is needed. Otherwise it can be NULL.
	nitems	Pointer to the number of items. The function can modify this value. This value is useful in case of array handling. Otherwise it can be NULL.

Returns:

On error 0 is returned and the GX system error is set appropriately ( see gx_geterror() ).

References gx_convertvariant(), gx_getvariantbypath(), gx_leavevariant(), gx_poperror(), and gx_pusherror().