Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Class Members | File Members

Type library


Detailed Description

Abstract run-time types for VXI interferences and optionally implementation.

These types mirror ECMAScript types (and could be implemented as such). They could also be implemented using C++ and STL, or using C. Using these abstract types rather than directly using an externally defined class library increases portability, and allows the implementers of each interface to independantly select external class libraries (or none at all) for their own implementation.

Each type is implemented as a handle that is obtained from a constructor and supports run-time typing. The owner (creator) of each type is responsible for freeing it by calling the appropriate destructor.

Note: When errors occur, constructors return a NULL object. Typically this is due to running out of memory, or a type mismatch for copy constructors.

The value types are as follows, note that the naming convention is VXI followed by the type name starting with an uppercase letter, while the simple VXI types in VXIvalue.h use VXI followed by the type name starting with a lowercase letter:

VXIValue Abstract base type for all the rest, can cast any type to this type and still determine the original type. Used to provide input/return values where the actual underlying type can vary.
VXIBooleanContainer for a boolean (VXIbool)
VXIIntegerContainer for a 32-bit integer (VXIint32)
VXILongContainer for a 32-bit long (VXIlong)
VXIULongContainer for a 32-bit unsigned int (VXIulong)
VXIFloatContainer for a 32-bit float type (VXIflt32)
VXIDoubleContainer for a 32-bit double type (VXIflt64)
VXIStringContainer for a string (VXIchar)
VXIPtrContainer for a untyped pointer (VXIptr)
VXIContentContainer for MIME content typed data (VXIptr)
VXIMap Simple key/value container where the keys are of VXIchar type and the values are any of the abstract types defined here.
VXIVector Simple indexed vector that supports appending elements at the end, and getting and setting elements by index. There is no support for removing elements or insertions.


Classes

class  VXIMapHolder
 C++ wrapper class that makes it easier to work with VXIMaps. More...
class  VXIContentHolder
 C++ wrapper class that makes it easier to work with VXIContent. More...

Defines

#define VXIArgs   VXIMap

Typedefs

typedef VXIint32 VXIvalueType
typedef enum VXIvalueResult VXIvalueResult
 Result codes for function methods.
typedef enum VXIValueStringFormat VXIValueStringFormat
 Formats for the string result of VXIValueToString, currently:.

Enumerations

enum  {
  VALUE_INTEGER = 0, VALUE_FLOAT = 1, VALUE_STRING = 2, VALUE_PTR = 3,
  VALUE_MAP = 4, VALUE_VECTOR = 5, VALUE_CONTENT = 6, VALUE_BOOLEAN = 7,
  VALUE_DOUBLE = 8, VALUE_LONG = 9, VALUE_ULONG = 10
}
enum  VXIvalueResult {
  VXIvalue_RESULT_FATAL_ERROR = -100, VXIvalue_RESULT_IO_ERROR = -8, VXIvalue_RESULT_OUT_OF_MEMORY = -7, VXIvalue_RESULT_SYSTEM_ERROR = -6,
  VXIvalue_RESULT_PLATFORM_ERROR = -5, VXIvalue_RESULT_BUFFER_TOO_SMALL = -4, VXIvalue_RESULT_INVALID_PROP_NAME = -3, VXIvalue_RESULT_INVALID_PROP_VALUE = -2,
  VXIvalue_RESULT_INVALID_ARGUMENT = -1, VXIvalue_RESULT_SUCCESS = 0, VXIvalue_RESULT_FAILURE = 1, VXIvalue_RESULT_NON_FATAL_ERROR = 2,
  VXIvalue_RESULT_UNSUPPORTED = 100
}
 Result codes for function methods. More...
enum  VXIValueStringFormat { VALUE_FORMAT_URL_QUERY_ARGS }
 Formats for the string result of VXIValueToString, currently:. More...

Functions

VXIVALUE_API VXIvalueType VXIValueGetType (const VXIValue *v)
 Get the type of a Value.
VXIVALUE_API void VXIValueDestroy (VXIValue **v)
 Generic Value destructor.
VXIVALUE_API VXIValue * VXIValueClone (const VXIValue *v)
 Generic Value clone.
VXIVALUE_API VXIBoolean * VXIBooleanCreate (VXIbool n)
 Create a Boolean from a VXIbool.
VXIVALUE_API void VXIBooleanDestroy (VXIBoolean **i)
 Boolean destructor.
VXIVALUE_API VXIbool VXIBooleanValue (const VXIBoolean *i)
 Get the value of a Boolean.
VXIVALUE_API VXIInteger * VXIIntegerCreate (VXIint32 n)
 Create an Integer from a 32 bit integer.
VXIVALUE_API void VXIIntegerDestroy (VXIInteger **i)
 Integer destructor.
VXIVALUE_API VXIint32 VXIIntegerValue (const VXIInteger *i)
 Get the value of an Integer.
VXIVALUE_API VXILong * VXILongCreate (VXIlong n)
 Create an Long from a 32 bit long.
VXIVALUE_API void VXILongDestroy (VXILong **i)
 Long destructor.
VXIVALUE_API VXIlong VXILongValue (const VXILong *i)
 Get the value of an Long.
VXIVALUE_API VXIULong * VXIULongCreate (VXIulong n)
 Create an ULong from a 32 bit unsigned long.
VXIVALUE_API void VXIULongDestroy (VXIULong **i)
 ULong destructor.
VXIVALUE_API VXIulong VXIULongValue (const VXIULong *i)
 Get the value of an ULong.
VXIVALUE_API VXIFloat * VXIFloatCreate (VXIflt32 n)
 Create a Float from a 32 bit floating point number.
VXIVALUE_API void VXIFloatDestroy (VXIFloat **f)
 Float destructor.
VXIVALUE_API VXIflt32 VXIFloatValue (const VXIFloat *f)
 Get the value of a Float.
VXIVALUE_API VXIDouble * VXIDoubleCreate (VXIflt64 n)
 Create a Double from a 32 bit floating point number.
VXIVALUE_API void VXIDoubleDestroy (VXIDouble **f)
 Double destructor.
VXIVALUE_API VXIflt64 VXIDoubleValue (const VXIDouble *f)
 Get the value of a Double.
VXIVALUE_API VXIPtr * VXIPtrCreate (void *n)
 Create a Ptr from a C pointer.
VXIVALUE_API void VXIPtrDestroy (VXIPtr **p)
 Ptr destructor.
VXIVALUE_API void * VXIPtrValue (const VXIPtr *p)
 Get the value of a Ptr.
VXIVALUE_API VXIContent * VXIContentCreate (const VXIchar *contentType, VXIbyte *content, VXIulong contentSizeBytes, void(*Destroy)(VXIbyte **content, void *userData), void *userData)
 Create a Content from MIME content typed data.
VXIVALUE_API VXIContent * VXIContentCreateEx (const VXIchar *contentType, VXIbyte *content, VXIulong contentSizeBytes, void(*Destroy)(VXIbyte **content, void *userData), void(*GetValue)(void *userData, const VXIbyte *currcontent, const VXIbyte **realcontent, VXIulong *realcontentSizeBytes), void *userData)
 Create a Content from MIME content typed data.
VXIVALUE_API void VXIContentGetUserData (const VXIContent *c, void **u)
 Retrieve the unique data pointer they passed to VXIContentCreate.
VXIVALUE_API void VXIContentSetTransferEncoding (const VXIContent *c, const VXIchar *e)
 Set the Content-Transfer-Encoding for MIME.
VXIVALUE_API const VXIcharVXIContentGetTransferEncoding (const VXIContent *c)
 Retrieve the Content-Transfer-Encoding for MIME.
VXIVALUE_API VXIulong VXIContentGetContentSizeBytes (const VXIContent *c)
 Retrieve the content size (in bytes).
VXIVALUE_API void VXIContentDestroy (VXIContent **c)
 Content destructor.
VXIVALUE_API VXIvalueResult VXIContentValue (const VXIContent *c, const VXIchar **contentType, const VXIbyte **content, VXIulong *contentSizeBytes)
 Get the value of a Content.
VXIVALUE_API VXIString * VXIStringCreate (const VXIchar *str)
 Create a String from a null-terminated character array.
VXIVALUE_API VXIString * VXIStringCreateN (const VXIchar *str, VXIunsigned len)
 Create a String from a known-length character array.
VXIVALUE_API void VXIStringDestroy (VXIString **s)
 String destructor.
VXIVALUE_API VXIString * VXIStringClone (const VXIString *s)
 String clone.
VXIVALUE_API VXIvalueResult VXIStringSetValue (VXIString *s, const VXIchar *str)
 Set the value of a String from a null-terminated character array.
VXIVALUE_API VXIcharVXIStringValue (const VXIString *s, VXIchar *buf, VXIunsigned len)
 Get the value of a String.
VXIVALUE_API const VXIcharVXIStringCStr (const VXIString *s)
 Get direct access to the NULL-terminated character value.
VXIVALUE_API VXIunsigned VXIStringLength (const VXIString *s)
 Get the number of characters in a String's value.
VXIVALUE_API VXIint VXIStringCompare (const VXIString *s1, const VXIString *s2)
 Compares two Strings.
VXIVALUE_API VXIint VXIStringCompareC (const VXIString *str, const VXIchar *buf)
 Compares a String to a NULL-terminated character array.
VXIVALUE_API VXIMap * VXIMapCreate (void)
 Create an empty Map.
VXIVALUE_API void VXIMapClear (VXIMap *m)
 Clear the content of the map and return an empty Map.
VXIVALUE_API void VXIMapDestroy (VXIMap **m)
 Map destructor.
VXIVALUE_API VXIMap * VXIMapClone (const VXIMap *m)
 Map clone.
VXIVALUE_API VXIvalueResult VXIMapSetProperty (VXIMap *m, const VXIchar *key, VXIValue *val)
 Set a named property on an Map.
VXIVALUE_API const VXIValue * VXIMapGetProperty (const VXIMap *m, const VXIchar *key)
 Get a named property from an Map.
VXIVALUE_API VXIvalueResult VXIMapDeleteProperty (VXIMap *m, const VXIchar *key)
 Delete a named property from an Map.
VXIVALUE_API VXIunsigned VXIMapNumProperties (const VXIMap *m)
 Return the number of properties for an Map.
VXIVALUE_API VXIMapIterator * VXIMapGetFirstProperty (const VXIMap *m, const VXIchar **key, const VXIValue **value)
 Get the first property of an Map and an iterator.
VXIVALUE_API VXIvalueResult VXIMapGetNextProperty (VXIMapIterator *it, const VXIchar **key, const VXIValue **value)
 Get the next property of an Map based on an iterator.
VXIVALUE_API void VXIMapIteratorDestroy (VXIMapIterator **it)
 Destroy an iterator.
VXIVALUE_API VXIVector * VXIVectorCreate (void)
 Create an empty Vector.
VXIVALUE_API void VXIVectorDestroy (VXIVector **v)
 Vector destructor.
VXIVALUE_API VXIVector * VXIVectorClone (const VXIVector *v)
 Vector clone.
VXIVALUE_API VXIvalueResult VXIVectorAddElement (VXIVector *v, VXIValue *val)
 Adds an element to the end of the Vector.
VXIVALUE_API VXIvalueResult VXIVectorSetElement (VXIVector *v, VXIunsigned n, VXIValue *val)
 Set an indexed vector element.
VXIVALUE_API const VXIValue * VXIVectorGetElement (const VXIVector *v, VXIunsigned n)
 Get an indexed vector element.
VXIVALUE_API VXIunsigned VXIVectorLength (const VXIVector *v)
 Return number of elements in a Vector.
VXIVALUE_API VXIString * VXIValueToString (const VXIValue *v, const VXIchar *name, VXIValueStringFormat format)
 Generic Value to string conversion.


Define Documentation

#define VXIArgs   VXIMap
 


Typedef Documentation

typedef enum VXIvalueResult VXIvalueResult
 

Result codes for function methods.

Result codes less than zero are severe errors (likely to be platform faults), those greater than zero are warnings (likely to be application issues)

typedef enum VXIValueStringFormat VXIValueStringFormat
 

Formats for the string result of VXIValueToString, currently:.

VALUE_FORMAT_URL_QUERY_ARGS

URL query argument format as specified in IETF RFC 2396. Note: this encoding is not appropriate for generically serializing and later restoring VXIValue based types, see below.

This will return a string of the format "key1=value1&key2=value2[...]" where '=' seperates keys and '&' seperates key/value pairs. Map keys are output by using dot notation such as "mymap.mymember=true" for "mymember" in "mymap". Similarly, vector keys are output using dot notation, such as "myvec.1=200" for myvec element 1. This dot notation may be arbitrarily deep for handling nested maps/vectors. Boolean values are output as "true" or "false", and VXIContent values are encoded by inserting the escaped bytes (see below).

As required by IETF RFC 2396, all keys and values are escaped to ensure the resulting string is only composed of a subset of visible ASCII characters. All other characters/bytes (including a percent sign) are encoded as a percent sign followed by the byte value such as "%20" for a space. Since VXIMap key names and VXIStrings are wchar_t based data that may include Unicode characters, each character in those are first converted to the Unicode UTF-8 character encoding (where each character is represented by 1 to 6 bytes, with the UTF-8 byte code and ASCII byte codes identical for the ASCII character set, and Latin 1 [ISO-8859] and Unicode characters consuming 2 or more bytes), then each byte is escaped as necessary. NOTE: The use of UTF-8 to encode Latin 1 and Unicode characters is Vocalocity defined and thus may not seemlessly interoperate with other software: IETF RFC 2396 acknoledges the issue of the transmission of non-ASCII character set characters, and allows for the use of UTF-8, but does not mandate the use of UTF-8 to solve this problem and thus encoding choices vary between systems (although UTF-8 is the clearest choice).

Note that with this format the types of each key is ambiguous: for example the VXIString "100" and the VXIInteger 100 have an identical representation, and VXIContent byte streams are not distinguishable from other types (particulary VXIStrings) unless they contain byte codes that are not permissable in the other types, such as NULL (0) bytes. When used for HTTP operations, this ambiguity is not an issue, as the target CGI/servlet/etc. knows what data to expect and thus the appropriate data type for each key. Thus while useful for serializing and transmitting application defined data over HTTP or other ASCII based protocols for delivery to the application elsewhere, this encoding is not appropriate for generically serializing and later restoring VXIValue based types.

typedef VXIint32 VXIvalueType
 


Enumeration Type Documentation

anonymous enum
 

Enumeration values:
VALUE_INTEGER 
VALUE_FLOAT 
VALUE_STRING 
VALUE_PTR 
VALUE_MAP 
VALUE_VECTOR 
VALUE_CONTENT 
VALUE_BOOLEAN 
VALUE_DOUBLE 
VALUE_LONG 
VALUE_ULONG 

enum VXIvalueResult
 

Result codes for function methods.

Result codes less than zero are severe errors (likely to be platform faults), those greater than zero are warnings (likely to be application issues)

Enumeration values:
VXIvalue_RESULT_FATAL_ERROR 
VXIvalue_RESULT_IO_ERROR 
VXIvalue_RESULT_OUT_OF_MEMORY 
VXIvalue_RESULT_SYSTEM_ERROR 
VXIvalue_RESULT_PLATFORM_ERROR 
VXIvalue_RESULT_BUFFER_TOO_SMALL 
VXIvalue_RESULT_INVALID_PROP_NAME 
VXIvalue_RESULT_INVALID_PROP_VALUE 
VXIvalue_RESULT_INVALID_ARGUMENT 
VXIvalue_RESULT_SUCCESS 
VXIvalue_RESULT_FAILURE 
VXIvalue_RESULT_NON_FATAL_ERROR 
VXIvalue_RESULT_UNSUPPORTED 

enum VXIValueStringFormat
 

Formats for the string result of VXIValueToString, currently:.

VALUE_FORMAT_URL_QUERY_ARGS

URL query argument format as specified in IETF RFC 2396. Note: this encoding is not appropriate for generically serializing and later restoring VXIValue based types, see below.

This will return a string of the format "key1=value1&key2=value2[...]" where '=' seperates keys and '&' seperates key/value pairs. Map keys are output by using dot notation such as "mymap.mymember=true" for "mymember" in "mymap". Similarly, vector keys are output using dot notation, such as "myvec.1=200" for myvec element 1. This dot notation may be arbitrarily deep for handling nested maps/vectors. Boolean values are output as "true" or "false", and VXIContent values are encoded by inserting the escaped bytes (see below).

As required by IETF RFC 2396, all keys and values are escaped to ensure the resulting string is only composed of a subset of visible ASCII characters. All other characters/bytes (including a percent sign) are encoded as a percent sign followed by the byte value such as "%20" for a space. Since VXIMap key names and VXIStrings are wchar_t based data that may include Unicode characters, each character in those are first converted to the Unicode UTF-8 character encoding (where each character is represented by 1 to 6 bytes, with the UTF-8 byte code and ASCII byte codes identical for the ASCII character set, and Latin 1 [ISO-8859] and Unicode characters consuming 2 or more bytes), then each byte is escaped as necessary. NOTE: The use of UTF-8 to encode Latin 1 and Unicode characters is Vocalocity defined and thus may not seemlessly interoperate with other software: IETF RFC 2396 acknoledges the issue of the transmission of non-ASCII character set characters, and allows for the use of UTF-8, but does not mandate the use of UTF-8 to solve this problem and thus encoding choices vary between systems (although UTF-8 is the clearest choice).

Note that with this format the types of each key is ambiguous: for example the VXIString "100" and the VXIInteger 100 have an identical representation, and VXIContent byte streams are not distinguishable from other types (particulary VXIStrings) unless they contain byte codes that are not permissable in the other types, such as NULL (0) bytes. When used for HTTP operations, this ambiguity is not an issue, as the target CGI/servlet/etc. knows what data to expect and thus the appropriate data type for each key. Thus while useful for serializing and transmitting application defined data over HTTP or other ASCII based protocols for delivery to the application elsewhere, this encoding is not appropriate for generically serializing and later restoring VXIValue based types.

Enumeration values:
VALUE_FORMAT_URL_QUERY_ARGS 


Function Documentation

VXIVALUE_API VXIBoolean* VXIBooleanCreate VXIbool  n  ) 
 

Create a Boolean from a VXIbool.

Parameters:
n VXIbool value, either TRUE or FALSE
Returns:
Boolean with the specified value on success, NULL otherwise

VXIVALUE_API void VXIBooleanDestroy VXIBoolean **  i  ) 
 

Boolean destructor.

Parameters:
i Boolean to destroy

VXIVALUE_API VXIbool VXIBooleanValue const VXIBoolean *  i  ) 
 

Get the value of a Boolean.

Parameters:
i Boolean to obtain the value from
Returns:
VXIbool boolean value, either TRUE or FALSE

VXIVALUE_API VXIContent* VXIContentCreate const VXIchar contentType,
VXIbyte content,
VXIulong  contentSizeBytes,
void(*)(VXIbyte **content, void *userData)  Destroy,
void *  userData
 

Create a Content from MIME content typed data.

Thread-safe reference counting is used to allow sharing the data (typically large) across multiple clones while minimizing memory use. The passed Destroy( ) function is only called when the reference count drops to zero.

Parameters:
contentType MIME content type for the data
content Data to store, this pointer will merely be copied (no deep copy of the data will be done) so this pointer must remain valid until the Destroy function is called.
contentSizeBytes Size of the data, in bytes
Destroy Destructor called to release the data when no longer needed. Since this construction merely copies the pointer, this is mandatory.
userData Optional user data pointer passed to destroy, typically used to hold a pointer to some larger data structure that contains the content so that larger data structure can be destroyed when the content is no longer required.

VXIVALUE_API VXIContent* VXIContentCreateEx const VXIchar contentType,
VXIbyte content,
VXIulong  contentSizeBytes,
void(*)(VXIbyte **content, void *userData)  Destroy,
void(*)(void *userData, const VXIbyte *currcontent, const VXIbyte **realcontent, VXIulong *realcontentSizeBytes)  GetValue,
void *  userData
 

Create a Content from MIME content typed data.

Thread-safe reference counting is used to allow sharing the data (typically large) across multiple clones while minimizing memory use. The passed Destroy( ) function is only called when the reference count drops to zero.

Parameters:
contentType MIME content type for the data
content Data to store, this pointer will merely be copied (no deep copy of the data will be done) so this pointer must remain valid until the Destroy function is called.
contentSizeBytes Size of the data, in bytes
Destroy Destructor called to release the data when no longer needed. Since this construction merely copies the pointer, this is mandatory.
GetValue Method called to override the reading of the memory stream from the content, this allows for the Content to be a place holder and the real memory content could be stored elsewhere.
userData Optional user data pointer passed to destroy, typically used to hold a pointer to some larger data structure that contains the content so that larger data structure can be destroyed when the content is no longer required.

VXIVALUE_API void VXIContentDestroy VXIContent **  c  ) 
 

Content destructor.

Parameters:
c Content to destroy

VXIVALUE_API VXIulong VXIContentGetContentSizeBytes const VXIContent *  c  ) 
 

Retrieve the content size (in bytes).

Parameters:
c Content to retrieve the data from

VXIVALUE_API const VXIchar* VXIContentGetTransferEncoding const VXIContent *  c  ) 
 

Retrieve the Content-Transfer-Encoding for MIME.

Parameters:
c Content to retrieve the data from

VXIVALUE_API void VXIContentGetUserData const VXIContent *  c,
void **  u
 

Retrieve the unique data pointer they passed to VXIContentCreate.

Parameters:
c Content to retrieve the data from
u Returns the unique pointer associated with the content

VXIVALUE_API void VXIContentSetTransferEncoding const VXIContent *  c,
const VXIchar e
 

Set the Content-Transfer-Encoding for MIME.

Parameters:
c Content to retrieve the data from
e Sets the Content-Transfer-Encoding for MIME

VXIVALUE_API VXIvalueResult VXIContentValue const VXIContent *  c,
const VXIchar **  contentType,
const VXIbyte **  content,
VXIulong contentSizeBytes
 

Get the value of a Content.

Parameters:
c Content to retrieve the data from
contentType Returns the MIME content type for the data
content Returns the pointer to the data
contentSizeBytes Returns the size of the data, in bytes
Returns:
VXIvalue_RESULT_SUCCESS on success

VXIVALUE_API VXIDouble* VXIDoubleCreate VXIflt64  n  ) 
 

Create a Double from a 32 bit floating point number.

Parameters:
n 32 bit floating point value
Returns:
Double with the specified value on success, NULL otherwise

VXIVALUE_API void VXIDoubleDestroy VXIDouble **  f  ) 
 

Double destructor.

Parameters:
f Double to destroy

VXIVALUE_API VXIflt64 VXIDoubleValue const VXIDouble *  f  ) 
 

Get the value of a Double.

Parameters:
f Double to get the value from
Returns:
32 bit floating point value

VXIVALUE_API VXIFloat* VXIFloatCreate VXIflt32  n  ) 
 

Create a Float from a 32 bit floating point number.

Parameters:
n 32 bit floating point value
Returns:
Float with the specified value on success, NULL otherwise

VXIVALUE_API void VXIFloatDestroy VXIFloat **  f  ) 
 

Float destructor.

Parameters:
f Float to destroy

VXIVALUE_API VXIflt32 VXIFloatValue const VXIFloat *  f  ) 
 

Get the value of a Float.

Parameters:
f Float to get the value from
Returns:
32 bit floating point value

VXIVALUE_API VXIInteger* VXIIntegerCreate VXIint32  n  ) 
 

Create an Integer from a 32 bit integer.

Parameters:
n 32 bit integer value
Returns:
Integer with the specified value on success, NULL otherwise

VXIVALUE_API void VXIIntegerDestroy VXIInteger **  i  ) 
 

Integer destructor.

Parameters:
i Integer to destroy

VXIVALUE_API VXIint32 VXIIntegerValue const VXIInteger *  i  ) 
 

Get the value of an Integer.

Parameters:
i Integer to obtain the value from
Returns:
32 bit integer value

VXIVALUE_API VXILong* VXILongCreate VXIlong  n  ) 
 

Create an Long from a 32 bit long.

Parameters:
n 32 bit long value
Returns:
Long with the specified value on success, NULL otherwise

VXIVALUE_API void VXILongDestroy VXILong **  i  ) 
 

Long destructor.

Parameters:
i Long to destroy

VXIVALUE_API VXIlong VXILongValue const VXILong *  i  ) 
 

Get the value of an Long.

Parameters:
i Long to obtain the value from
Returns:
32 bit long value

VXIVALUE_API void VXIMapClear VXIMap *  m  ) 
 

Clear the content of the map and return an empty Map.

Returns:
None

VXIVALUE_API VXIMap* VXIMapClone const VXIMap *  m  ) 
 

Map clone.

Recursively copies all values contained within the map, including all the values of Maps and Vectors stored within this map.

Note: functionally redundant with VXIValueClone( ), but provided to reduce the need for C casts for this common operation

Parameters:
m Map to clone
Returns:
Clone of the Map on success, NULL otherwise

VXIVALUE_API VXIMap* VXIMapCreate void   ) 
 

Create an empty Map.

Returns:
New map on success, NULL otherwise

VXIVALUE_API VXIvalueResult VXIMapDeleteProperty VXIMap *  m,
const VXIchar key
 

Delete a named property from an Map.

This does a VXIValueDestroy( ) on the value for the named property (thus recursively deleting held values within it if it is an Map or Vector). However, for Ptr properties the user is responsible for freeing the held memory if appropriate.

Parameters:
m Map to access
key NULL terminated property name
Returns:
VXIvalue_RESULT_SUCCESS on success

VXIVALUE_API void VXIMapDestroy VXIMap **  m  ) 
 

Map destructor.

Note: this recursively destroys all the values contained within the Map, including all the values of Maps and Vectors stored within this map. However, for Ptr values the user is responsible for freeing the held memory if appropriate.

Parameters:
m Map to destroy

VXIVALUE_API VXIMapIterator* VXIMapGetFirstProperty const VXIMap *  m,
const VXIchar **  key,
const VXIValue **  value
 

Get the first property of an Map and an iterator.

Note: this is used to traverse all the properties within an map, there is no guarantee on what order the properties will be returned. The iterator must be eventually freed with VXIMapIteratorDestroy( ), and is invalidated if the Map is modified in any way.

Parameters:
m Map to access
key Set to point at the property name for read-only access (must not be modified)
value Set to point at the property value for read-only access (must not be modified)
Returns:
Pointer to an iterator that may be used to get additional properties via VXIMapGetNextProperty( ), or NULL on failure (typically no properties in the map)

VXIVALUE_API VXIvalueResult VXIMapGetNextProperty VXIMapIterator *  it,
const VXIchar **  key,
const VXIValue **  value
 

Get the next property of an Map based on an iterator.

Note: this is used to traverse all the properties within an map, there is no guarantee on what order the properties will be returned.

Parameters:
it Iterator used to access the map as obtained from VXIMapGetFirstProperty( ), this operation will advance the iterator to the next property on success
key Set to point at the property name for read-only access (must not be modified, invalidated if the Map is modified)
value Set to point at the property value for read-only access (must not be modified, invalidated if the Map is modified)
Returns:
VXIvalue_RESULT_SUCCESS on success (property name and value returned, iterator advanced), VXIvalue_RESULT_FAILURE if there are no more properties to read, or a VXIvalueResult error code for severe errors

VXIVALUE_API const VXIValue* VXIMapGetProperty const VXIMap *  m,
const VXIchar key
 

Get a named property from an Map.

The property value is returned for read-only access and is invalidated if the Map is modified. The client must clone it if they wish to perform modifications or wish to retain the value even afer modifying this Map.

Parameters:
m Map to access
key NULL terminated property name
Returns:
On success the value of the property for read-only access (invalidated if the Map is modified), NULL if the property was never set or was deleted

VXIVALUE_API void VXIMapIteratorDestroy VXIMapIterator **  it  ) 
 

Destroy an iterator.

Parameters:
it Iterator to destroy as obtained from VXIMapGetFirstProperty( )

VXIVALUE_API VXIunsigned VXIMapNumProperties const VXIMap *  m  ) 
 

Return the number of properties for an Map.

Note: this only returns the number of properties that are direct children of the Map, it does not include the number of properties held in Maps and Vectors stored within this map.

Parameters:
m Map to access
Returns:
Number of properties stored in the Map

VXIVALUE_API VXIvalueResult VXIMapSetProperty VXIMap *  m,
const VXIchar key,
VXIValue *  val
 

Set a named property on an Map.

The value can be an Map so a tree can be constructed.

If the property already exists, the existing value is first destroyed using VXIValueDestroy( ) (thus recursively deleting held values within it if it is an Map or Vector), then does the set operation with the new value.

Parameters:
m Map to access
key NULL terminated property name
val Value to set the property to, ownership is passed to the Map (a simple pointer copy is done), so on success the user must not delete, modify, or otherwise use this. Also be careful to not add a Map as a property of itself (directly or indirectly), otherwise infinite loops may occur on access or deletion.
Returns:
VXIvalue_RESULT_SUCCESS on success

VXIVALUE_API VXIPtr* VXIPtrCreate void *  n  ) 
 

Create a Ptr from a C pointer.

Note: This only stores the pointer blindly, it does not perform a deep copy and the reference memory is not freed on destruction. Thus the user is responsible for ensuring the referenced memory location remains valid, and for freeing memory when appropriate on Ptr destruction.

Parameters:
n Pointer to memory

VXIVALUE_API void VXIPtrDestroy VXIPtr **  p  ) 
 

Ptr destructor.

Parameters:
p Ptr to destroy

VXIVALUE_API void* VXIPtrValue const VXIPtr *  p  ) 
 

Get the value of a Ptr.

Parameters:
p Ptr to retrieve the pointer from
Returns:
Pointer to memory retrieved

VXIVALUE_API VXIString* VXIStringClone const VXIString *  s  ) 
 

String clone.

Note: functionally redundant with VXIValueClone( ), but provided to reduce the need for C casts for this common operation

Parameters:
s String to clone
Returns:
Clone of the string on success, NULL otherwise

VXIVALUE_API VXIint VXIStringCompare const VXIString *  s1,
const VXIString *  s2
 

Compares two Strings.

Parameters:
s1 First String to compare
s2 Second String to compare
Returns:
Returns a value that is less than, equal to, or greater than zero depending on whether s1 is lexicographically less than, equal to, or greater than s2

VXIVALUE_API VXIint VXIStringCompareC const VXIString *  str,
const VXIchar buf
 

Compares a String to a NULL-terminated character array.

Parameters:
str String to compare
buf NULL-terminated character array to compare
Returns:
Returns a value that is less than, equal to, or greater than zero depending on whether str is lexicographically less than, equal to, or greater than buf

VXIVALUE_API VXIString* VXIStringCreate const VXIchar str  ) 
 

Create a String from a null-terminated character array.

Parameters:
str NULL-terminated character array
Returns:
String with the specified value on success, NULL otherwise

VXIVALUE_API VXIString* VXIStringCreateN const VXIchar str,
VXIunsigned  len
 

Create a String from a known-length character array.

Parameters:
str Character array (null characters may be embedded in the array)
len Number of characters which will be copied.
Returns:
String with the specified value on success, NULL otherwise

VXIVALUE_API const VXIchar* VXIStringCStr const VXIString *  s  ) 
 

Get direct access to the NULL-terminated character value.

Note: the returned buffer must never be modified, and is only provided for transient use (i.e. immediately logging it, comparing it, etc. rather than storing or returning the pointer for longer term access).

Parameters:
s String to retrieve the data from
Returns:
Pointer to the NULL-terminated character array retrieved

VXIVALUE_API void VXIStringDestroy VXIString **  s  ) 
 

String destructor.

Parameters:
s String to destroy

VXIVALUE_API VXIunsigned VXIStringLength const VXIString *  s  ) 
 

Get the number of characters in a String's value.

Note: Add one byte for the NULL terminator when using this to determine the length of the array required for a VXIStringValue( ) call.

Parameters:
s String to access
Returns:
Length of the string, in characters

VXIVALUE_API VXIvalueResult VXIStringSetValue VXIString *  s,
const VXIchar str
 

Set the value of a String from a null-terminated character array.

Note: this functionality is provided to allow defining interfaces where the caller passes in a VXIString from VXIStringCreate( ) (typically with an empty string as its value) with the interface changing that value to return a string as output. This avoids having to define interfaces where the client has to provide a fixed length buffer (and thus worry about "buffer too small" errors and complicated handling).

Parameters:
s String to change the value of
str NULL-terminated character array
Returns:
VXIvalue_RESULT_SUCCESS on success

VXIVALUE_API VXIchar* VXIStringValue const VXIString *  s,
VXIchar buf,
VXIunsigned  len
 

Get the value of a String.

Parameters:
s String to access
buf Character buffer to copy the value into as a NULL-terminated character array. The buffer size must be at least VXIStringLength() + 1.
len Size of the buffer, in characters
Returns:
Pointer to buf on success, NULL on failure (most likely buffer too small)

VXIVALUE_API VXIULong* VXIULongCreate VXIulong  n  ) 
 

Create an ULong from a 32 bit unsigned long.

Parameters:
n 32 bit unsigned long value
Returns:
ULong with the specified value on success, NULL otherwise

VXIVALUE_API void VXIULongDestroy VXIULong **  i  ) 
 

ULong destructor.

Parameters:
i ULong to destroy

VXIVALUE_API VXIulong VXIULongValue const VXIULong *  i  ) 
 

Get the value of an ULong.

Parameters:
i ULong to obtain the value from
Returns:
32 bit unsigned long value

VXIVALUE_API VXIValue* VXIValueClone const VXIValue *  v  ) 
 

Generic Value clone.

This automatically invokes the appropriate type specific clone operation.

Parameters:
v Value to clone
Returns:
Clone of v, NULL on error

VXIVALUE_API void VXIValueDestroy VXIValue **  v  ) 
 

Generic Value destructor.

This automatically invokes the appropriate type specific destructor.

Parameters:
v Value to destroy

VXIVALUE_API VXIvalueType VXIValueGetType const VXIValue *  v  ) 
 

Get the type of a Value.

Parameters:
v Value to check
Returns:
Type of value

VXIVALUE_API VXIString* VXIValueToString const VXIValue *  v,
const VXIchar name,
VXIValueStringFormat  format
 

Generic Value to string conversion.

This converts any VXIValue type to a string.

Parameters:
v Value to convert to a string
name Name to use for labeling the VXIValue data
format Format to use for the string, see above
Returns:
VXIString, NULL on error

VXIVALUE_API VXIvalueResult VXIVectorAddElement VXIVector *  v,
VXIValue *  val
 

Adds an element to the end of the Vector.

The value can be a Vector so frames can be implemented.

Parameters:
v Vector to access
val Value to append to the vector, ownership is passed to the Vector (a simple pointer copy is done), so on success the user must not delete, modify, or otherwise use this. Also be careful to not add a Vector as a element of itself (directly or indirectly), otherwise infinite loops may occur on access or deletion.
Returns:
VXIvalue_RESULT_SUCCESS on success

VXIVALUE_API VXIVector* VXIVectorClone const VXIVector *  v  ) 
 

Vector clone.

Recursively copies all values contained within the vector, including all the values of Vectors and Maps stored within this vector.

Note: functionally redundant with VXIValueClone( ), but provided to reduce the need for C casts for this common operation

Parameters:
v Vector to clone
Returns:
Clone of the Vector on success, NULL otherwise

VXIVALUE_API VXIVector* VXIVectorCreate void   ) 
 

Create an empty Vector.

Returns:
New vector on success, NULL otherwise

VXIVALUE_API void VXIVectorDestroy VXIVector **  v  ) 
 

Vector destructor.

Note: this recursively destroys all the values contained within the Vector, including all the values of Vectors stored within this vector. However, for Ptr values the user is responsible for freeing the held memory if appropriate.

Parameters:
v Vector to destroy

VXIVALUE_API const VXIValue* VXIVectorGetElement const VXIVector *  v,
VXIunsigned  n
 

Get an indexed vector element.

The element value is returned for read-only access and is invalidated if the Vector is modified. The client must clone it if they wish to perform modifications or wish to retain the value even after modifying this Vector.

Parameters:
v Vector to access
n Element index to set, it is an error to pass a index that is greater or equal to then the number of values currently in the vector (i.e. range is 0 to length-1)
Returns:
On success the value of the property for read-only access (invalidated if the Vector is modified), NULL on error

VXIVALUE_API VXIunsigned VXIVectorLength const VXIVector *  v  ) 
 

Return number of elements in a Vector.

This computes only the length of the Vector, elements within Vectors and Maps within it are not counted.

Parameters:
v Vector to access
Returns:
Number of elements stored in the Vector

VXIVALUE_API VXIvalueResult VXIVectorSetElement VXIVector *  v,
VXIunsigned  n,
VXIValue *  val
 

Set an indexed vector element.

Overwrites the specified element with the new value. The existing value is first destroyed using VXIValueDestroy( ) (thus recursively deleting held values within it if it is an Map or Vector), then does the set operation with the new value.

The value can be a Vector so frames can be implemented.

Parameters:
v Vector to access
n Element index to set, it is an error to pass a index that is greater then the number of values currently in the vector
val Value to set the element to, ownership is passed to the Vector (a simple pointer copy is done), so on success the user must not delete, modify, or otherwise use this. Also be careful to not add a Vector as a element of itself (directly or indirectly), otherwise infinite loops may occur on access or deletion.
Returns:
VXIvalue_RESULT_SUCCESS on success


Generated on Wed Jun 1 12:50:19 2005 for OpenVXI by  doxygen 1.4.2