vxivalue.h

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

  * referenced memory location remains valid, and for freeing memory
  * when appropriate on Ptr destruction.
  *
  * @param   n     Pointer to memory
  */
 VXIVALUE_API VXIPtr *VXIPtrCreate(void *n);
 
 /**
  * Ptr destructor
  *
  * @param   p   Ptr to destroy
  */
 VXIVALUE_API void VXIPtrDestroy(VXIPtr **p);
 
 /**
  * Get the value of a Ptr
  *
  * @param   p   Ptr to retrieve the pointer from
  * @return      Pointer to memory retrieved
  */
 VXIVALUE_API void *VXIPtrValue(const VXIPtr *p);
 
 /**
  * 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.
  *
  * @param   contentType       MIME content type for the data
  * @param   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.
  * @param   contentSizeBytes  Size of the data, in bytes
  * @param   Destroy           Destructor called to release the data when
  *                            no longer needed. Since this construction
  *                            merely copies the pointer, this is mandatory.
  * @param   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 *
 VXIContentCreate(const VXIchar  *contentType,
 		 VXIbyte        *content,
 		 VXIulong        contentSizeBytes,
 		 void          (*Destroy)(VXIbyte **content, void *userData),
 		 void           *userData);
 
 /**
  * Content destructor
  *
  * @param   c   Content to destroy
  */
 VXIVALUE_API void VXIContentDestroy(VXIContent **c);
 
 /**
  * Get the value of a Content
  *
  * @param   c                 Content to retrieve the data from
  * @param   contentType       Returns the MIME content type for the data
  * @param   content           Returns the pointer to the data
  * @param   contentSizeBytes  Returns the size of the data, in bytes
  * @return                    VXIvalue_RESULT_SUCCESS on success 
  */
 VXIVALUE_API VXIvalueResult 
 VXIContentValue(const VXIContent  *c,
 		const VXIchar    **contentType,
 		const VXIbyte    **content,
 		VXIulong          *contentSizeBytes);
 
 /**
  * Create a String from a null-terminated character array
  *
  * @param   str   NULL-terminated character array
  * @return        String with the specified value on success, 
  *                NULL otherwise
  */
 VXIVALUE_API VXIString *VXIStringCreate(const VXIchar *str);
 
 /**
  * Create a String from a known-length character array
  *
  * @param   str   Character array (null characters may be embedded in 
  *                the array)
  * @param   len   Number of characters which will be copied.
  * @return        String with the specified value on success, 
  *                NULL otherwise
  */
 VXIVALUE_API VXIString *VXIStringCreateN(const VXIchar *str, VXIunsigned len);
 
 /**
  * String destructor
  *
  * @param   s   String to destroy
  */
 VXIVALUE_API void VXIStringDestroy(VXIString **s);
 
 /**
  * String clone
  *
  * Note: functionally redundant with VXIValueClone( ), but provided to
  * reduce the need for C casts for this common operation
  *
  * @param    s   String to clone
  * @return       Clone of the string on success, NULL otherwise
  */
 VXIVALUE_API VXIString *VXIStringClone(const VXIString *s);
 
 /**
  * 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).
  *
  * @param   s     String to change the value of
  * @param   str   NULL-terminated character array
  * @return        VXIvalue_RESULT_SUCCESS on success 
  */
 VXIVALUE_API VXIvalueResult VXIStringSetValue(VXIString      *s, 
                                               const VXIchar  *str);
 
 /**
  * Get the value of a String
  *
  * @param   s     String to access
  * @param   buf   Character buffer to copy the value into as a
  *                NULL-terminated character array.  The buffer size must be
  *                at least VXIStringLength() + 1.
  * @param   len   Size of the buffer, in characters
  * @return        Pointer to buf on success, NULL on failure (most likely
  *                buffer too small) 
  */
 VXIVALUE_API VXIchar *VXIStringValue(const VXIString  *s, 
                                      VXIchar          *buf, 
                                      VXIunsigned       len);
 
 /**
  * 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).
  *
  * @param   s   String to retrieve the data from
  * @return      Pointer to the NULL-terminated character array retrieved
  */
 VXIVALUE_API const VXIchar* VXIStringCStr(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.
  *
  * @param   s   String to access
  * @return      Length of the string, in characters
  */
 VXIVALUE_API VXIunsigned VXIStringLength(const VXIString *s);
 
 /**
  * Compares two Strings
  *
  * @param   s1   First String to compare
  * @param   s2   Second String to compare
  * @return       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 VXIStringCompare(const VXIString *s1, 
                                      const VXIString *s2);
 
 /**
  * Compares a String to a NULL-terminated character array
  *
  * @param   str   String to compare
  * @param   buf   NULL-terminated character array to compare
  * @return        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 VXIint VXIStringCompareC(const VXIString *str, 
                                       const VXIchar   *buf);
 
 /**
  * Create an empty Map
  *
  * @return   New map on success, NULL otherwise
  */
 VXIVALUE_API VXIMap *VXIMapCreate(void);
 
 /**
  * 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.
  *
  * @param m   Map to destroy 
  */
 VXIVALUE_API void VXIMapDestroy(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
  *
  * @param    m   Map to clone
  * @return       Clone of the Map on success, NULL otherwise 
  */
 VXIVALUE_API VXIMap *VXIMapClone(const VXIMap *m);
 
 /**
  * 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.
  *
  * @param   m     Map to access
  * @param   key   NULL terminated property name
  * @param   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.
  * @return        VXIvalue_RESULT_SUCCESS on success
  */
 VXIVALUE_API VXIvalueResult VXIMapSetProperty(VXIMap         *m, 
                                               const VXIchar  *key,
                                               VXIValue       *val);
 
 /**
  * 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.
  *
  * @param   m     Map to access
  * @param   key   NULL terminated property name
  * @return        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 const VXIValue *VXIMapGetProperty(const 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.
  *
  * @param   m     Map to access
  * @param   key   NULL terminated property name
  * @return        VXIvalue_RESULT_SUCCESS on success 
  */
 VXIVALUE_API VXIvalueResult VXIMapDeleteProperty(VXIMap         *m, 
                                                  const VXIchar  *key);
 
 /**
  * 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.
  *
  * @param   m   Map to access
  * @return      Number of properties stored in the Map
  */
 VXIVALUE_API VXIunsigned VXIMapNumProperties(const VXIMap *m);
 
 /**
  * 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