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. |
VXIBoolean | Container for a boolean (VXIbool) |
VXIInteger | Container for a 32-bit integer (VXIint32) |
VXILong | Container for a 32-bit long (VXIlong) |
VXIULong | Container for a 32-bit unsigned int (VXIulong) |
VXIFloat | Container for a 32-bit float type (VXIflt32) |
VXIDouble | Container for a 32-bit double type (VXIflt64) |
VXIString | Container for a string (VXIchar) |
VXIPtr | Container for a untyped pointer (VXIptr) |
VXIContent | Container 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 VXIchar * | VXIContentGetTransferEncoding (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 VXIchar * | VXIStringValue (const VXIString *s, VXIchar *buf, VXIunsigned len) |
Get the value of a String. | |
VXIVALUE_API const VXIchar * | VXIStringCStr (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. |
|
|
|
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) |
|
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. |
|
|
|
|
|
|
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. |
|
Create a Boolean from a VXIbool.
|
|
Boolean destructor.
|
|
Get the value of a Boolean.
|
|
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.
|
|
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.
|
|
Content destructor.
|
|
Retrieve the content size (in bytes).
|
|
Retrieve the Content-Transfer-Encoding for MIME.
|
|
Retrieve the unique data pointer they passed to VXIContentCreate.
|
|
Set the Content-Transfer-Encoding for MIME.
|
|
Get the value of a Content.
|
|
Create a Double from a 32 bit floating point number.
|
|
Double destructor.
|
|
Get the value of a Double.
|
|
Create a Float from a 32 bit floating point number.
|
|
Float destructor.
|
|
Get the value of a Float.
|
|
Create an Integer from a 32 bit integer.
|
|
Integer destructor.
|
|
Get the value of an Integer.
|
|
Create an Long from a 32 bit long.
|
|
Long destructor.
|
|
Get the value of an Long.
|
|
Clear the content of the map and return an empty Map.
|
|
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
|
|
Create an empty Map.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
Destroy an iterator.
|
|
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.
|
|
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.
|
|
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.
|
|
Ptr destructor.
|
|
Get the value of a Ptr.
|
|
String clone. Note: functionally redundant with VXIValueClone( ), but provided to reduce the need for C casts for this common operation
|
|
Compares two Strings.
|
|
Compares a String to a NULL-terminated character array.
|
|
Create a String from a null-terminated character array.
|
|
Create a String from a known-length character array.
|
|
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).
|
|
String destructor.
|
|
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.
|
|
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).
|
|
Get the value of a String.
|
|
Create an ULong from a 32 bit unsigned long.
|
|
ULong destructor.
|
|
Get the value of an ULong.
|
|
Generic Value clone. This automatically invokes the appropriate type specific clone operation.
|
|
Generic Value destructor. This automatically invokes the appropriate type specific destructor.
|
|
Get the type of a Value.
|
|
Generic Value to string conversion. This converts any VXIValue type to a string.
|
|
Adds an element to the end of the Vector. The value can be a Vector so frames can be implemented.
|
|
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
|
|
Create an empty Vector.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|