Header Header

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:

Go to the source code of this file.

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

General variant handling
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
static int gx_createvariant (gxVARIANT *variant, int id, const wchar_t *name, GX_VARIANT_TYPES type, int size, const void *data, int nitems)
 Creates a new variant.
static int gx_updatevariant (gxVARIANT variant, int id, const wchar_t *name, GX_VARIANT_TYPES type, int size, const void *data, int nitems)
 Modifies a variant.
static int gx_updatevariantdata (gxVARIANT variant, GX_VARIANT_TYPES type, int size, const void *data, int nitems)
 Modifies the data of a variant.
static int gx_changevariantid (gxVARIANT variant, int id)
 Changes the id of a variant.
static int gx_changevariantname (gxVARIANT variant, const wchar_t *name)
 Changes the name of a variant.
static 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.
static int gx_convertvariant (gxVARIANT variant, GX_VARIANT_TYPES type, void *target, int tgtlen, int *size, int *nitems)
 Returns a variant's data converted to a specified type.
Work with list type variants
static 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.
static int gx_cutvariantitem (gxVARIANT list, int flags, int id, const wchar_t *name, int ix, gxVARIANT *target)
 Cuts and returns an item from a list type variant.
static int gx_findvariantitem (gxVARIANT list, gxVARIANT item, int flags, int *ix)
 Returns the index of a variant element located in a list type variant.
static 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.
static int gx_createvariantitem (gxVARIANT list, int id, const wchar_t *name, GX_VARIANT_TYPES type, int size, const void *data, int nitems, gxVARIANT *item)
 Creates a new variant and appends to a list type variant.
static int gx_convertvariantitem (gxVARIANT list, int id, const wchar_t *name, int ix, GX_VARIANT_TYPES type, void *target, int tgtlen, int *size, int *nitems)
 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, const wchar_t *name, int *ix, gxVARIANT *target)
 Returns a child of a variant.
static int gx_cutvariantchild (gxVARIANT parent, int flags, int id, const wchar_t *name, int ix, gxVARIANT *target)
 Cuts and returns a child of a variant.
static 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.
static int gx_addvariantchild (gxVARIANT parent, int flags, int id, const wchar_t *name, int ix, gxVARIANT child)
 Adds a child element to a variant.
static int gx_createvariantchild (gxVARIANT parent, int id, const wchar_t *name, GX_VARIANT_TYPES type, int size, const void *data, int nitems, gxVARIANT *child)
 Creates a new variant and appends it to a variant as a child.
static int gx_convertvariantchild (gxVARIANT parent, int id, const wchar_t *name, int ix, GX_VARIANT_TYPES type, void *target, int tgtlen, int *size, int *nitems)
 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.
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_convertvariantbypath (gxVARIANT root, const wchar_t *path, GX_VARIANT_TYPES type, void *target, int tgtlen, int *size, int *nitems)
 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().

Referenced by gx_createvariantchild(), and gx_createvariantitem().

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

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

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,
const wchar_t *  name,
GX_VARIANT_TYPES  type,
int  size,
const void *  data,
int  nitems 
) [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.
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 gx_createvariantchild(), and gx_createvariantitem().

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

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

static int gx_updatevariantdata ( gxVARIANT  variant,
GX_VARIANT_TYPES  type,
int  size,
const void *  data,
int  nitems 
) [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.
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().

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_changevariantname ( gxVARIANT  variant,
const wchar_t *  name 
) [static]

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

static int gx_getvariantinfo ( gxVARIANT  variant,
int *  id,
wchar_t *  namebuff,
int  namebuffsize,
GX_VARIANT_TYPES 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.
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().

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

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 gx_convertvariantbypath(), gx_convertvariantchild(), and gx_convertvariantitem().

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

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

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

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

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

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

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

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

static int gx_createvariantitem ( gxVARIANT  list,
int  id,
const wchar_t *  name,
GX_VARIANT_TYPES  type,
int  size,
const void *  data,
int  nitems,
gxVARIANT item 
) [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:
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.

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

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.

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

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

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

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

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

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

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

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

static int gx_createvariantchild ( gxVARIANT  parent,
int  id,
const wchar_t *  name,
GX_VARIANT_TYPES  type,
int  size,
const void *  data,
int  nitems,
gxVARIANT child 
) [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:
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.

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

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.

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

Referenced by gx_convertvariantbypath().

static int gx_convertvariantbypath ( gxVARIANT  root,
const wchar_t *  path,
GX_VARIANT_TYPES  type,
void *  target,
int  tgtlen,
int *  size,
int *  nitems 
) [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.
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().


Generated  for GX
(c) Adaptive Recognition