gxvariant_compat.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.

Classes
class	gxVariant
	Class for the VARIANT functions. More...
General variant handling
#define	gx_disposevariant   gx_leavevariant
int	gx_refvariant (gxVARIANT variant)
	Increases a variant's reference counter.
int	gx_unrefvariant (gxVARIANT variant)
	Decreases a variant's reference counter.
int	gx_leavevariant (gxVARIANT *variant)
	Decreases a variant's reference counter and clears the variant variable.
int	gx_duplicatevariant (gxVARIANT *target, gxVARIANT source)
	Duplicates, copies a variant and all of its descendants into a newly allocated memory area.
Create, modify, read variants
#define	gx_updatevariantid   gx_changevariantid
int	gx_createvariant (gxVARIANT *variant, int id, int type, int size, int nitems, const void *data)
	Creates a new variant.
int	gx_updatevariant (gxVARIANT *variant, int id, int type, int size, int nitems, const void *data)
	Unreferences the memory area pointed by the variant and creates a new data structure.
int	gx_updatevariantdata (gxVARIANT variant, int id, int type, int size, int nitems, const void *data)
	Modifies the data of a variant.
int	gx_changevariantid (gxVARIANT variant, int id)
	Changes the id of a variant.
int	gx_getvariant (gxVARIANT variant, int *id, int *type, int *size, int *nitems, int *nchildren)
	Gives information about a variant.
int	gx_convertvariant (gxVARIANT variant, int *id, int type, int *size, int *nitems, void *target, int tgtlen)
	Returns a variant's data converted to a specified type.
Typedefs
typedef struct GX_VARIANT *	gxVARIANT
	Defining the variant type as a pointer to an empty structure (no automatic typecasts).
Enumerations
enum	GX_VARIANT_TYPES {   GX_VARIANT_NULL = 0x00,   GX_VARIANT_INT = 0x01,   GX_VARIANT_UINT = 0x02,   GX_VARIANT_FLOAT = 0x03,   GX_VARIANT_DATETIME = 0x04,   GX_VARIANT_ARRAY = 0x40,   GX_VARIANT_INTARRAY = 0x41,   GX_VARIANT_UINTARRAY = 0x42,   GX_VARIANT_FLOATARRAY = 0x43,   GX_VARIANT_DATETIMEARRAY = 0x44,   GX_VARIANT_LIST = 0x80,   GX_VARIANT_BINARY = 0x81,   GX_VARIANT_ASCII = 0x82,   GX_VARIANT_UNICODE = 0x83,   GX_VARIANT_CONTAINER = 0x84,   GX_VARIANT_AC_ASCII = 0x1082,   GX_VARIANT_AC_UNICODE = 0x1083,   GX_VARIANT_AS_ASCII = 0x2082,   GX_VARIANT_AS_UNICODE = 0x2083 }
	Available variant types. More...
enum	GX_VARIANT_FLAGS {   GX_VARIANT_BY_INDEX = 0x0002,   GX_VARIANT_BY_ID = 0x0001,   GX_VARIANT_BY_INDEX_AND_ID = 0x0003,   GX_VARIANT_BY_ORDER_AND_ID = 0x0004,   GX_VARIANT_BY_NAME = 0x0008,   GX_VARIANT_BY_INDEX_AND_NAME = 0x000a,   GX_VARIANT_BY_ORDER_AND_NAME = 0x0010,   GX_VARIANT_APPEND = 0x0100,   GX_VARIANT_LAST = 0x0200 }
	Flags for list item and child indexing functions. More...
Functions
Work with list type variants
int	gx_getvariantitem (gxVARIANT list, int flags, int *id, int *ix, gxVARIANT *target)
	Returns an item from a list type variant.
int	gx_getvariantitem (gxVARIANT list, int flags, int id, int ix, gxVARIANT *target)
	Returns an item from a list type variant.
int	gx_cutvariantitem (gxVARIANT list, int flags, int id, int ix, gxVARIANT *target)
	Cuts and returns an item from a list type variant.
int	gx_findvariantitem (gxVARIANT list, gxVARIANT item, int *id, int *ix)
	Returns the id and the index of a variant element located in a list type variant.
int	gx_addvariantitem (gxVARIANT list, int flags, int id, int ix, gxVARIANT item)
	Adds an item to a list type variant.
int	gx_removevariantitem (gxVARIANT list, int flags, int id, int ix)
	Unreferences and deletes an item from a list type variant.
int	gx_createvariantitem (gxVARIANT *variant, int id, int type, int size, int nitems, const void *data, gxVARIANT list)
	Creates a new variant and appends to a list type variant.
int	gx_convertvariantitem (gxVARIANT variant, int id, int ix, int type, int *size, int *nitems, void *target, int tgtlen)
	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, int *ix, gxVARIANT *target)
	Returns a child of a variant.
int	gx_getvariantchild (gxVARIANT parent, int flags, int id, int ix, gxVARIANT *target)
	Returns a child of a variant.
int	gx_cutvariantchild (gxVARIANT parent, int flags, int id, int ix, gxVARIANT *target)
	Cuts and returns a child of a variant.
int	gx_findvariantchild (gxVARIANT parent, gxVARIANT child, int *id, int *ix)
	Returns the id and the index of a child element located in a variant's children list.
int	gx_addvariantchild (gxVARIANT parent, int flags, int id, int ix, gxVARIANT child)
	Adds a child element to a variant.
int	gx_removevariantchild (gxVARIANT parent, int flags, int id, int ix)
	Unreferences and deletes a child of a variant.
int	gx_createvariantchild (gxVARIANT *variant, int id, int type, int size, int nitems, const void *data, gxVARIANT parent)
	Creates a new variant and appends it to a variant as a child.
int	gx_convertvariantchild (gxVARIANT variant, int id, int ix, int type, int *size, int *nitems, void *target, int tgtlen)
	Returns the data of a variant's child converted to a specified type.
Work with arrays
int	gx_getvariantvalue (gxVARIANT varray, int size, GX_VARIANT_TYPES type, int ix, int nitems, void *target, int tgtlen)
	Returns a part of an array variant's data.
int	gx_cutvariantvalue (gxVARIANT varray, int size, GX_VARIANT_TYPES type, int ix, int nitems, void *target=0, int tgtlen=0)
	Cuts and returns a part of an array variant's data.
int	gx_addvariantvalue (gxVARIANT varray, int size, GX_VARIANT_TYPES type, int ix, int nitems, const void *data)
	Inserts one or more values into an array variant's data.
int	gx_removevariantvalue (gxVARIANT array, int ix, int nitems)
	Removes one or more values from the array.
Work with descendant variants
int	gx_getvariantbypath (gxVARIANT root, const wchar_t *path, gxVARIANT *item)
	Returns a variant from a variant tree.
int	gx_getvariantbypatha (gxVARIANT root, const char *path, gxVARIANT *item)
	Returns a variant from a variant tree.
int	gx_getvariantbypath (gxVARIANT root, const char *path, gxVARIANT *item)
	Usable in C++.
int	gx_convertvariantbypath (gxVARIANT root, const wchar_t *path, int *id, int type, int *size, int *nitems, void *target, int tgtlen)
	Returns the data of a variant located in a variant tree converted to a specified type.
int	gx_convertvariantbypatha (gxVARIANT root, const char *path, int *id, int type, int *size, int *nitems, void *target, int tgtlen)
	Returns the data of a variant located in a variant tree converted to a specified type.
int	gx_convertvariantbypath (gxVARIANT root, const char *path, int *id, int type, int *size, int *nitems, void *target, int tgtlen)
	Usable in C++.

---

Typedef Documentation

typedef struct GX_VARIANT* gxVARIANT

Defining the variant type as a pointer to an empty structure (no automatic typecasts).

---

Enumeration Type Documentation

enum GX_VARIANT_TYPES

Available variant types.

Note:

The values with _AC_ tag are usable in creation operation only. For these types the value is automatically converted to the proper data type.

The values with _AS_ tag are usable in creation operation only. For these types the value is automatically converted to the proper string type.

Enumerator:

GX_VARIANT_NULL	NULL type (size: 0; nitems: 1).
GX_VARIANT_INT	Integer type (size: 0, 1, 2, 4, 8; nitems: 1).
GX_VARIANT_UINT	Unsigned integer type (size: 0, 1, 2, 4, 8; nitems: 1).
GX_VARIANT_FLOAT	Floating-point type (size: 0, 4, 8; nitems: 1).
GX_VARIANT_DATETIME	Datetime type (size: 0, 8; nitems: 1).
GX_VARIANT_ARRAY	NULL type array /NULL array/ (size: 0; nitems: x).
GX_VARIANT_INTARRAY	Integer type array (size: 0, 1, 2, 4, 8; nitems: x).
GX_VARIANT_UINTARRAY	Unsigned integer type array (size: 0, 1, 2, 4, 8; nitems: x).
GX_VARIANT_FLOATARRAY	Float type array (size: 0, 4, 8; nitems: x).
GX_VARIANT_DATETIMEARRAY	Datetime type array (size: 0, 8; nitems: x).
GX_VARIANT_LIST	List type (size=nitems: number of items).
GX_VARIANT_BINARY	Binary (size=number of bytes; nitems: 1).
GX_VARIANT_ASCII	String in ASCII format (size=number of characters; nitems: 1).
GX_VARIANT_UNICODE	String in unicode format (size=number of characters; nitems: 1).
GX_VARIANT_CONTAINER	Internally used binary structure (size=number of codes; nitems: 1).
GX_VARIANT_AC_ASCII	String in ASCII format (size=number of characters; nitems: 1) (see note above).
GX_VARIANT_AC_UNICODE	String in unicode format (size=number of characters; nitems: 1) (see note above).
GX_VARIANT_AS_ASCII	String in ASCII format (size=number of characters; nitems: 1) (see note above).
GX_VARIANT_AS_UNICODE	String in unicode format (size=number of characters; nitems: 1) (see note above).

enum GX_VARIANT_FLAGS

Flags for list item and child indexing functions.

Enumerator:

GX_VARIANT_BY_INDEX	Select the ix -th item.
GX_VARIANT_BY_ID	Search by id.
GX_VARIANT_BY_INDEX_AND_ID	Search for an item with id, starting from the ix -th item.
GX_VARIANT_BY_ORDER_AND_ID	Search for the ix -th item with the specified id.
GX_VARIANT_BY_NAME	Search by name.
GX_VARIANT_BY_INDEX_AND_NAME	Search for an item with name, starting from the ix -th item.
GX_VARIANT_BY_ORDER_AND_NAME	Search for the ix -th item with the specified name.
GX_VARIANT_APPEND	Appending after the index position instead of inserting.
GX_VARIANT_LAST	Select the last item.

---

Function Documentation

int gx_refvariant

(

gxVARIANT

variant

)

[inline]

Increases a variant's reference counter.

The counter indicates the number of threads/entities using the variant. Referencing the variant signs that two or more independent variables share the same memory area. In this case modifying the data structure of a variant affects all the variables. Referencing is useful when the same data is used in different contexts and no independent modifications are required in these contexts.

Parameters:

variant

Variant to reference.

Returns:

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

References gx_call().

Referenced by gxVariant::gxVariant(), gxVariant::operator=(), and gxVariant::Ref().

int gx_unrefvariant

(

gxVARIANT

variant

)

[inline]

Decreases a variant's reference counter.

The counter indicates the number of threads/entities using the variant. When the counter value becomes zero that means that no one is using the variant so its internally allocated memory is freed. In this case all of its children and list items will be unreferenced too.

Parameters:

variant

Variant to unreference.

Returns:

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

References gx_call().

Referenced by gx_createvariantchild(), gx_createvariantitem(), gxVariant::operator=(), gxTrafo::ToVariant(), gxImage::ToVariant(), and gxVariant::Unref().

int gx_leavevariant

(

gxVARIANT *

variant

)

[inline]

Decreases a variant's reference counter and clears the variant variable.

The counter indicates the number of threads/entities using the variant. When the counter value becomes zero that means that no one is using the variant so its internally allocated memory is freed. In this case all of its children and list items will be unreferenced too.

Parameters:

variant

Variant to leave.

Returns:

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

References gx_call().

Referenced by gx_convertvariantbypath(), gx_convertvariantchild(), gx_convertvariantitem(), gx_createvariantchild(), gx_createvariantitem(), gx_cutvariantchild(), and gx_cutvariantitem().

int gx_duplicatevariant	(	gxVARIANT *	target,
		gxVARIANT	source
	)			[inline]

Duplicates, copies a variant and all of its descendants into a newly allocated memory area.

The variants use refernce counter to track the number of threads/entities using them. Modifying the data structure of a variant affects all the variables that references the same memory area. To avoid this behaviour it is possible to duplicate the variant before modification.

Parameters:

	target	Buffer for the result. To free up the used memory call the gx_unrefvariant() or the gx_leavevariant() function.
	source	Variant to duplicate.

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::CutChild(), gxVariant::CutItem(), gxVariant::GetChild(), gxVariant::GetItem(), and gxVariant::GetItemByPath().

int gx_createvariant	(	gxVARIANT *	variant,
		int	id,
		int	type,
		int	size,
		int	nitems,
		const void *	data
	)			[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.
	type	The type of the new variant.
	size	The size of the new variant.
	nitems	The number of items of the new variant. This value is usually 1, except for list and array types.
	data	The data of the new variant.

Returns:

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

References gx_call().

int gx_updatevariant	(	gxVARIANT *	variant,
		int	id,
		int	type,
		int	size,
		int	nitems,
		const void *	data
	)			[inline]

Unreferences the memory area pointed by the variant and creates a new data structure.

Note:

The new variant will have no children after update.

Parameters:

	variant	Buffer for the result.
	id	The new id of the variant.
	type	The new type of the variant.
	size	The new size of the variant.
	nitems	The new number of items of the variant. This value is usually 1, except for list and array types.
	data	The new data 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_updatevariantdata	(	gxVARIANT	variant,
		int	id,
		int	type,
		int	size,
		int	nitems,
		const void *	data
	)			[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.
	id	The new id of the variant.
	type	The new type of the variant.
	size	The new size of the variant.
	nitems	The new number of items of the variant. This value is usually 1, except for list and array types.
	data	The new data 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_changevariantid	(	gxVARIANT	variant,
		int	id
	)			[inline]

Changes the id of a variant.

Changing the id 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.
	id	The new id 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_getvariant	(	gxVARIANT	variant,
		int *	id,
		int *	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.
	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().

Referenced by gxVariant::GetID(), gxVariant::GetNChildren(), gxVariant::GetNItems(), gxVariant::GetSize(), and gxVariant::GetType().

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

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

Parameters:

	variant	Variant to process.
	id	Buffer for the returned id.
	type	Type to convert to.
	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.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.

Returns:

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

References gx_call().

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

Returns an item from a list type variant.

Note:

The actual role of the id 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. On success the variant id is returned.
	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().

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

Returns an item from a list type variant.

Note:

The actual role of the id 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.
	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,
		int	ix,
		gxVARIANT *	target
	)			[inline]

Cuts and returns an item from a list type variant.

Note:

The actual role of the id 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.
	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().

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

Returns the id and 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.
	id	Buffer for the id of the variant.
	ix	Buffer for the index in the variant list.

Returns:

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

References gx_call().

int gx_addvariantitem	(	gxVARIANT	list,
		int	flags,
		int	id,
		int	ix,
		gxVARIANT	item
	)			[inline]

Adds an item to a list type variant.

Note:

The actual role of the id 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.
	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().

int gx_removevariantitem	(	gxVARIANT	list,
		int	flags,
		int	id,
		int	ix
	)			[inline]

Unreferences and deletes an item from a list type variant.

Parameters:

	list	Variant list to process.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	id	The id of the item to remove.
	ix	The index of the item to remove.

Returns:

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

References gx_call().

Referenced by gxVariant::RemoveChild(), and gxVariant::RemoveItem().

int gx_createvariantitem	(	gxVARIANT *	variant,
		int	id,
		int	type,
		int	size,
		int	nitems,
		const void *	data,
		gxVARIANT	list
	)			[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:

	variant	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.
	id	The id of the new variant.
	type	The type of the new variant.
	size	The size of the new variant.
	nitems	The number of items of the new variant. This value is usually 1, except for list and array types.
	data	The data of the new variant.
	list	List type variant.

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(), and gx_unrefvariant().

int gx_convertvariantitem	(	gxVARIANT	variant,
		int	id,
		int	ix,
		int	type,
		int *	size,
		int *	nitems,
		void *	target,
		int	tgtlen
	)			[inline]

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

Parameters:

	variant	List type variant.
	id	Id of the requested item.
	ix	Index of the requested item.
	type	Type to convert to.
	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.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.

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(), and gx_pusherror().

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

Returns a child of a variant.

Note:

The actual role of the id 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. On success the child id is returned.
	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().

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

Returns a child of a variant.

Note:

The actual role of the id 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.
	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,
		int	ix,
		gxVARIANT *	target
	)			[inline]

Cuts and returns a child of a variant.

Note:

The actual role of the id 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.
	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().

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

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

Parameters:

	parent	Parent variant to process.
	child	Child to search for.
	id	Buffer for the id of the variant.
	ix	Buffer for the index in the children list.

Returns:

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

References gx_call().

int gx_addvariantchild	(	gxVARIANT	parent,
		int	flags,
		int	id,
		int	ix,
		gxVARIANT	child
	)			[inline]

Adds a child element to a variant.

Note:

The actual role of the id 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.
	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().

int gx_removevariantchild	(	gxVARIANT	parent,
		int	flags,
		int	id,
		int	ix
	)			[inline]

Unreferences and deletes a child of a variant.

Parameters:

	parent	Variant to process.
	flags	Indexing flag ( see GX_VARIANT_FLAGS )
	id	The id of the child to remove.
	ix	The index of the child to remove.

Returns:

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

References gx_call().

int gx_createvariantchild	(	gxVARIANT *	variant,
		int	id,
		int	type,
		int	size,
		int	nitems,
		const void *	data,
		gxVARIANT	parent
	)			[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:

	variant	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.
	id	The id of the new variant.
	type	The type of the new variant.
	size	The size of the new variant.
	nitems	The number of items of the new variant. This value is usually 1, except for list and array types.
	data	The data of the new variant.
	parent	Parent variant to process.

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(), and gx_unrefvariant().

int gx_convertvariantchild	(	gxVARIANT	variant,
		int	id,
		int	ix,
		int	type,
		int *	size,
		int *	nitems,
		void *	target,
		int	tgtlen
	)			[inline]

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

Parameters:

	variant	Variant to process.
	id	Id of the requested child.
	ix	Index of the requested child.
	type	Type to convert to.
	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.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.

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(), and gx_pusherror().

int gx_getvariantvalue	(	gxVARIANT	varray,
		int	size,
		GX_VARIANT_TYPES	type,
		int	ix,
		int	nitems,
		void *	target,
		int	tgtlen
	)			[inline]

Returns a part of an array variant's data.

Parameters:

	varray	Array type variant to process.
	size	The expected size of a value in bytes.
	type	Type to convert to (GX_VARIANT_INT, GX_VARIANT_UINT, GX_VARIANT_FLOAT, GX_VARIANT_DATETIME, GX_VARIANT_ASCII, GX_VARIANT_UNICODE).
	ix	Index of the first expected value.
	nitems	Number of the expected values.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.

Returns:

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

References gx_call().

Referenced by gxVariant::GetFloatValue(), gxVariant::GetIntValue(), and gxVariant::GetUIntValue().

int gx_cutvariantvalue	(	gxVARIANT	varray,
		int	size,
		GX_VARIANT_TYPES	type,
		int	ix,
		int	nitems,
		void *	target = 0,
		int	tgtlen = 0
	)			[inline]

Cuts and returns a part of an array variant's data.

Parameters:

	varray	Array type variant to process.
	size	The expected size of a value in bytes.
	type	Type to convert to (GX_VARIANT_INT, GX_VARIANT_UINT, GX_VARIANT_FLOAT, GX_VARIANT_DATETIME, GX_VARIANT_ASCII, GX_VARIANT_UNICODE).
	ix	Index of the first expected value.
	nitems	Number of the expected values.
	target	Preallocated buffer for the resulted data. This buffer can be NULL to simply remove the data.
	tgtlen	Size of the target buffer.

Returns:

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

References gx_call().

Referenced by gxVariant::CutFloatValue(), gxVariant::CutIntValue(), and gxVariant::CutUIntValue().

int gx_addvariantvalue	(	gxVARIANT	varray,
		int	size,
		GX_VARIANT_TYPES	type,
		int	ix,
		int	nitems,
		const void *	data
	)			[inline]

Inserts one or more values into an array variant's data.

Parameters:

	varray	Array type variant to process.
	size	Size of an input data value in bytes.
	type	Type of the input data (GX_VARIANT_INT, GX_VARIANT_UINT, GX_VARIANT_FLOAT, GX_VARIANT_DATETIME).
	ix	The index of the position where to insert the data.
	nitems	Number of values to insert.
	data	Pointer to the data to insert.

Returns:

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

References gx_call().

Referenced by gxVariant::AddFloatValue(), gxVariant::AddIntValue(), and gxVariant::AddUIntValue().

int gx_removevariantvalue	(	gxVARIANT	array,
		int	ix,
		int	nitems
	)			[inline]

Removes one or more values from the array.

Parameters:

	array	Array type variant to process.
	ix	Index of the first value.
	nitems	Number of values.

Returns:

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

References gx_call().

Referenced by gxVariant::RemoveValue().

int gx_getvariantbypath	(	gxVARIANT	root,
		const wchar_t *	path,
		gxVARIANT *	item
	)			[inline]

Returns a variant from a variant tree.

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. If there is a need to reach a descendant variant located in a deep layer, 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.
	item	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::GetItemByPath(), and gx_convertvariantbypath().

int gx_getvariantbypatha	(	gxVARIANT	root,
		const char *	path,
		gxVARIANT *	item
	)			[inline]

Returns a variant from a variant tree.

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. If there is a need to reach a descendant variant located in a deep layer, 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.
	item	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 gx_getvariantbypath().

int gx_getvariantbypath	(	gxVARIANT	root,
		const char *	path,
		gxVARIANT *	item
	)			[inline]

Usable in C++.

It is the same function as the gx_getvariantbypatha.

Parameters:

	root	Root variant to process.
	path	The path string.
	item	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_getvariantbypatha().

int gx_convertvariantbypath	(	gxVARIANT	root,
		const wchar_t *	path,
		int *	id,
		int	type,
		int *	size,
		int *	nitems,
		void *	target,
		int	tgtlen
	)			[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.
	id	Buffer for the returned id.
	type	Type to convert to.
	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.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.

Returns:

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

References gx_call().

int gx_convertvariantbypatha	(	gxVARIANT	root,
		const char *	path,
		int *	id,
		int	type,
		int *	size,
		int *	nitems,
		void *	target,
		int	tgtlen
	)			[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.
	id	Buffer for the returned id.
	type	Type to convert to.
	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.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.

Returns:

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

References gx_call().

Referenced by gx_convertvariantbypath().

int gx_convertvariantbypath	(	gxVARIANT	root,
		const char *	path,
		int *	id,
		int	type,
		int *	size,
		int *	nitems,
		void *	target,
		int	tgtlen
	)			[inline]

Usable in C++.

It is the same function as the gx_convertvariantbypatha.

Parameters:

	root	Root variant to process.
	path	The path string.
	id	Buffer for the returned id.
	type	Type to convert to.
	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.
	target	Preallocated buffer for the resulted data.
	tgtlen	Size of the target buffer.

Returns:

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

References gx_convertvariantbypatha().