vxivalue.h

OSB-PIK-OpenVXI-3.0.0源代码 “中国XML论坛 - 专业的XML技术讨论区--XML在语音技术中的应用”

  * modified in any way.
  *
  * @param   m      Map to access
  * @param   key    Set to point at the property name for read-only 
  *                 access (must not be modified)                 
  * @param   value  Set to point at the property value for read-only 
  *                 access (must not be modified)
  * @return         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 
 VXIMapIterator *VXIMapGetFirstProperty(const VXIMap     *m,
                                        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.
  *
  * @param   it     Iterator used to access the map as obtained
  *                 from VXIMapGetFirstProperty( ), this operation
  *                 will advance the iterator to the next property on
  *                 success
  * @param   key    Set to point at the property name for read-only 
  *                 access (must not be modified, invalidated if the
  *                 Map is modified)                 
  * @param   value  Set to point at the property value for read-only 
  *                 access (must not be modified, invalidated if the
  *                 Map is modified)
  * @return         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 VXIvalueResult VXIMapGetNextProperty(VXIMapIterator  *it,
                                                   const VXIchar  **key,
                                                   const VXIValue **value);
 
 /**
  * Destroy an iterator
  *
  * @param   it     Iterator to destroy as obtained from 
  *                 VXIMapGetFirstProperty( )
  */
 VXIVALUE_API void VXIMapIteratorDestroy(VXIMapIterator **it);
 
 /**
  * Create an empty Vector
  *
  * @return   New vector on success, NULL otherwise
  */
 VXIVALUE_API VXIVector *VXIVectorCreate(void);
 
 /**
  * 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.
  *
  * @param   v   Vector to destroy 
  */
 VXIVALUE_API void VXIVectorDestroy(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
  *
  * @param    v   Vector to clone
  * @return Clone of the Vector on success, NULL otherwise */
 VXIVALUE_API VXIVector *VXIVectorClone(const VXIVector *v);
 
 /**
  * Adds an element to the end of the Vector
  *
  * The value can be a Vector so frames can be implemented.
  *
  * @param   v    Vector to access
  * @param   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.
  * @return       VXIvalue_RESULT_SUCCESS on success
  */
 VXIVALUE_API VXIvalueResult VXIVectorAddElement(VXIVector      *v, 
                                                 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.
  *
  * @param   v     Vector to access
  * @param   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
  * @param   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.
  * @return        VXIvalue_RESULT_SUCCESS on success
  */
 VXIVALUE_API VXIvalueResult VXIVectorSetElement(VXIVector      *v, 
                                                 VXIunsigned     n, 
                                                 VXIValue       *val);
 
 /**
  * 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.
  *
  * @param   v     Vector to access
  * @param   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)
  * @return        On success the value of the property for read-only 
  *                access (invalidated if the Vector is modified), NULL
  *                on error 
  */
 VXIVALUE_API const VXIValue *VXIVectorGetElement(const VXIVector *v, 
                                                  VXIunsigned      n);
 
 /**
  * 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.
  *
  * @param   v    Vector to access
  * @return       Number of elements stored in the Vector
  */
 VXIVALUE_API VXIunsigned VXIVectorLength(const VXIVector *v);
 
 /**
  * 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 SpeechWorks 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 enum VXIValueStringFormat {
   VALUE_FORMAT_URL_QUERY_ARGS,
 } VXIValueStringFormat;
 
 
 /**
  * Generic Value to string conversion
  *
  * This converts any VXIValue type to a string.
  *
  * @param   v       Value to convert to a string
  * @param   name    Name to use for labeling the VXIValue data
  * @param   format  Format to use for the string, see above
  * @return          VXIString, NULL on error
  */
 VXIVALUE_API VXIString *VXIValueToString(const VXIValue      *v,
 					 const VXIchar       *name,
 					 VXIValueStringFormat format);
 
 #ifdef __cplusplus
 } /* This ends the extern "C". */
 
 
 /**
  * C++ wrapper class that makes it easier to work with VXIMaps
  *
  * Used correctly, this class can eliminate common memory leaks associated with
  * VXIMap usage.  For instance:
  *
  *   VXIMap * GenerateMapFromParams(void)
  *   { 
  *     VXIMapHolder result;
  *     DoStuff();  // this code may throw an exception.
  *     return result.Release();
  *   }
  *
  * If an exception is raised by the DoStuff function, the map will be cleaned
  * up automatically when the stack is unwound.  Likewise, the calling code may
  * benefit:
  *
  *   int Foo(void)
  *   {
  *     VXIMapHolder params(GenerateMapFromParams());
  *     ProcessParams(params);  // This code may throw an exception.
  *     return 0;
  *   }
  *
  * If either an exception occurs or the function exits normally, the associated
  * map will be freed.
  */
 class VXIMapHolder {
 public:
   /* On creation, the map will either create a new map or take ownership of
    * an existing one.  This map will be freed when the holder is destroyed.
    */
 
   VXIMapHolder() : _map(NULL)        { _map = VXIMapCreate(); }
   VXIMapHolder(VXIMap * m) : _map(m) { }
   ~VXIMapHolder()                    { if (_map != NULL) VXIMapDestroy(&_map);}
 
   /* Operator= allows you to copy MapHolders.
    */
 
   VXIMapHolder & operator=(const VXIMapHolder & x)
   { if (this != &x) {
       if (_map != NULL) VXIMapDestroy(&_map);
       _map = VXIMapClone(x._map); }
     return *this; }
 
   /* GetValue returns the internal map.  The standard map manipulation
    * functions may then be used.
    */
 
   VXIMap * GetValue() const       { return _map; }
 
   /* These functions allow the holder to take ownership of an existing map
    * or to release the internal one.
    */
 
   VXIMap * Release()              { VXIMap * m = _map; _map = NULL; return m; }
   void Acquire(VXIMap * m)        { if (_map != NULL) VXIMapDestroy(&_map);
                                     _map = m; }
 private:
   VXIMapHolder(const VXIMapHolder &);   /* intentionally not defined. */
 
   VXIMap * _map;
 };
 
 /*@}*/
 #endif /* end #ifdef _cplusplus */
 
 #include "VXIheaderSuffix.h"
 
 #endif  /* include guard */