Header Header

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:

Go to the source code of this file.

General variant handling

#define gx_disposevariant   gx_leavevariant
static int gx_refvariant (gxVARIANT variant)
 Increases a variant's reference counter.
static int gx_unrefvariant (gxVARIANT variant)
 Decreases a variant's reference counter.
static int gx_leavevariant (gxVARIANT *variant)
 Decreases a variant's reference counter and clears the variant variable.
static 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
static int gx_createvariant (gxVARIANT *variant, int id, int type, int size, int nitems, const void *data)
 Creates a new variant.
static 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.
static int gx_updatevariantdata (gxVARIANT variant, int id, int type, int size, int nitems, const void *data)
 Modifies the data of a variant.
static int gx_changevariantid (gxVARIANT variant, int id)
 Changes the id of a variant.
static int gx_getvariant (gxVARIANT variant, int *id, int *type, int *size, int *nitems, int *nchildren)
 Gives information about a variant.
static 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,
  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,
  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
static int gx_getvariantitem (gxVARIANT list, int flags, int *id, int *ix, gxVARIANT *target)
 Returns an item from a list type variant.
static int gx_cutvariantitem (gxVARIANT list, int flags, int id, int ix, gxVARIANT *target)
 Cuts and returns an item from a list type variant.
static 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.
static int gx_addvariantitem (gxVARIANT list, int flags, int id, int ix, gxVARIANT item)
 Adds an item to a list type variant.
static int gx_removevariantitem (gxVARIANT list, int flags, int id, int ix)
 Unreferences and deletes an item from a list type variant.
static 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.
static 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
static int gx_getvariantchild (gxVARIANT parent, int flags, int *id, int *ix, gxVARIANT *target)
 Returns a child of a variant.
static int gx_cutvariantchild (gxVARIANT parent, int flags, int id, int ix, gxVARIANT *target)
 Cuts and returns a child of a variant.
static 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.
static int gx_addvariantchild (gxVARIANT parent, int flags, int id, int ix, gxVARIANT child)
 Adds a child element to a variant.
static int gx_removevariantchild (gxVARIANT parent, int flags, int id, int ix)
 Unreferences and deletes a child of a variant.
static 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.
static 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
static 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.
static int gx_cutvariantvalue (gxVARIANT varray, int size, GX_VARIANT_TYPES type, int ix, int nitems, void *target, int tgtlen)
 Cuts and returns a part of an array variant's data.
static 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.
static int gx_removevariantvalue (gxVARIANT array, int ix, int nitems)
 Removes one or more values from the array.
Work with descendant variants
static int gx_getvariantbypath (gxVARIANT root, const wchar_t *path, gxVARIANT *item)
 Returns a variant from a variant tree.
static int gx_getvariantbypatha (gxVARIANT root, const char *path, gxVARIANT *item)
 Returns a variant from a variant tree.
static 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.
static 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.


Typedef Documentation

typedef struct GX_VARIANT* gxVARIANT

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


Enumeration Type Documentation

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

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

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

static int gx_refvariant ( gxVARIANT  variant  )  [static]

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().

static int gx_unrefvariant ( gxVARIANT  variant  )  [static]

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().

static int gx_leavevariant ( gxVARIANT variant  )  [static]

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().

static int gx_duplicatevariant ( gxVARIANT target,
gxVARIANT  source 
) [static]

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().

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

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().

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

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().

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

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().

static int gx_changevariantid ( gxVARIANT  variant,
int  id 
) [static]

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().

static int gx_getvariant ( gxVARIANT  variant,
int *  id,
int *  type,
int *  size,
int *  nitems,
int *  nchildren 
) [static]

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().

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

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().

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

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().

static int gx_cutvariantitem ( gxVARIANT  list,
int  flags,
int  id,
int  ix,
gxVARIANT target 
) [static]

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().

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

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().

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

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().

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

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().

static int gx_createvariantitem ( gxVARIANT variant,
int  id,
int  type,
int  size,
int  nitems,
const void *  data,
gxVARIANT  list 
) [static]

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().

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

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().

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

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().

static int gx_cutvariantchild ( gxVARIANT  parent,
int  flags,
int  id,
int  ix,
gxVARIANT target 
) [static]

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().

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

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().

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

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().

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

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().

static int gx_createvariantchild ( gxVARIANT variant,
int  id,
int  type,
int  size,
int  nitems,
const void *  data,
gxVARIANT  parent 
) [static]

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().

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

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().

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

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().

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

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().

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

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().

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

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().

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

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().

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

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().

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

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().

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

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().


Generated  for GX
(c) Adaptive Recognition