vxivalue.h

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

 /****************License************************************************
  *
  * Copyright 2000-2003.  ScanSoft, Inc.    
  *
  * Use of this software is subject to notices and obligations set forth 
  * in the SpeechWorks Public License - Software Version 1.2 which is 
  * included with this software. 
  *
  * ScanSoft is a registered trademark of ScanSoft, Inc., and OpenSpeech, 
  * SpeechWorks and the SpeechWorks logo are registered trademarks or 
  * trademarks of SpeechWorks International, Inc. in the United States 
  * and other countries.
  *
  ***********************************************************************/
 

 #ifndef _VXIVALUE_H
 #define _VXIVALUE_H
 
 #include "VXItypes.h"                  /* For VXIchar, VXIint32, etc. */
 
 #include "VXIheaderPrefix.h"
 #ifdef VXIVALUE_EXPORTS
 #define VXIVALUE_API SYMBOL_EXPORT_DECL
 #else
 #define VXIVALUE_API SYMBOL_IMPORT_DECL
 #endif
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /** 
  ** @name VXIvalue
  ** @memo Abstract VXI type library
  ** @doc
  ** 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:
  **
  ** <table border=0>
  ** <tr>
  ** <td valign=top> <b>VXIValue</b></td>
  ** <td valign=top> 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. </td>
  ** </tr>
  ** <tr>
  ** <td valign=top><b>VXIBoolean</b></td><td>   Container for a boolean (VXIbool) </td>
  ** </tr>
  ** <tr>
  ** <td valign=top><b>VXIInteger</b></td><td>   Container for a 32-bit integer (VXIint32) </td>
  ** </tr>
  ** <tr>
  ** <td valign=top><b> VXIFloat</b></td><td>     Container for a 32-bit float type (VXIflt32) </td>
  ** </tr>
  ** <tr>
  ** <td valign=top><b> VXIString</b></td><td>    Container for a string (VXIchar) </td>
  ** </tr>
  ** <tr>
  ** <td valign=top><b> VXIPtr</b></td><td>       Container for a untyped pointer (VXIptr) </td>
  ** </tr>
  ** <tr>
  ** <td valign=top><b> VXIContent</b></td><td>   Container for MIME content typed data (VXIptr) </td>
  ** </tr>
  ** <tr>
  ** <td valign=top><b>  VXIMap</b></td>
  ** <td>    Simple key/value container where the keys are of VXIchar 
  **         type and the values are any of the abstract types defined 
  **        here.</td>
  ** </tr>
  ** <tr>
  ** <td valign=top><b>  VXIVector</b></td>
  **  <td>    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. </td>
  ** </tr>
  ** <tr>
  ** </table>
  **/
 
 /*@{*/
 
 #ifndef VXIVALUE_REAL_STRUCTS  /* If real structures aren't already declared */
 
 /*
  * Define each type as an opaque structure to get full information hiding
  * while ensuring strong compiler type checks. The actual implementation
  * defines these structures however it wants.
  */
 #ifdef __cplusplus
 struct VXIValue;
 struct VXIBoolean;
 struct VXIInteger;
 struct VXIFloat;
 struct VXIString;
 struct VXIPtr;
 struct VXIContent;
 struct VXIMap;
 struct VXIVector;
   
 struct VXIMapIterator;
 #else
 typedef struct VXIValue   { void * dummy; } VXIValue;
 typedef struct VXIBoolean { void * dummy; } VXIBoolean;
 typedef struct VXIInteger { void * dummy; } VXIInteger;
 typedef struct VXIFloat   { void * dummy; } VXIFloat;
 typedef struct VXIString  { void * dummy; } VXIString;
 typedef struct VXIPtr     { void * dummy; } VXIPtr;
 typedef struct VXIContent { void * dummy; } VXIContent;
 typedef struct VXIMap     { void * dummy; } VXIMap;
 typedef struct VXIVector  { void * dummy; } VXIVector;
 
 typedef struct VXIMapIterator  { void * dummy; } VXIMapIterator;
 #endif
 
 #define VXIArgs VXIMap /* For backward compatibility use only */
 
 #endif /* VXIVALUE_REAL_STRUCTS */
 
 
 /*
  * VXI Value types:
  *  0x0000 - 0x00FF           reserved for definition in this header
  *  0x0100 - 0xFFFF           reserved for implementation specific definition
  */
 typedef VXIint32 VXIvalueType;
 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
 };
 
 
 /**
  * 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 VXIvalueResult {
   /* Fatal error, terminate call    */
   VXIvalue_RESULT_FATAL_ERROR       =  -100, 
   /* I/O error                      */
   VXIvalue_RESULT_IO_ERROR           =   -8,
   /* Out of memory                  */
   VXIvalue_RESULT_OUT_OF_MEMORY      =   -7, 
   /* System error, out of service   */
   VXIvalue_RESULT_SYSTEM_ERROR       =   -6, 
   /* Errors from platform services  */
   VXIvalue_RESULT_PLATFORM_ERROR     =   -5, 
   /* Return buffer too small        */
   VXIvalue_RESULT_BUFFER_TOO_SMALL   =   -4, 
   /* Property name is not valid    */
   VXIvalue_RESULT_INVALID_PROP_NAME  =   -3, 
   /* Property value is not valid   */
   VXIvalue_RESULT_INVALID_PROP_VALUE =   -2, 
   /* Invalid function argument      */
   VXIvalue_RESULT_INVALID_ARGUMENT   =   -1, 
   /* Success                        */
   VXIvalue_RESULT_SUCCESS            =    0,
   /* Normal failure, nothing logged */
   VXIvalue_RESULT_FAILURE            =    1,
   /* Non-fatal non-specific error   */
   VXIvalue_RESULT_NON_FATAL_ERROR    =    2, 
   /* Operation is not supported     */
   VXIvalue_RESULT_UNSUPPORTED        =  100
 } VXIvalueResult;
 
 
 /**
  * Get the type of a Value
  *
  * @param   v   Value to check
  * @return      Type of value
  */
 VXIVALUE_API VXIvalueType VXIValueGetType(const VXIValue *v);
 
 /**
  * Generic Value destructor
  *
  * This automatically invokes the appropriate type specific
  * destructor.
  *
  * @param   v   Value to destroy
  */
 VXIVALUE_API void VXIValueDestroy(VXIValue **v);
 
 /**
  * Generic Value clone
  *
  * This automatically invokes the appropriate type specific clone
  * operation.
  *
  * @param   v   Value to clone
  * @return      Clone of v, NULL on error
  */
 VXIVALUE_API VXIValue *VXIValueClone(const VXIValue *v);
 
 /**
  * Create a Boolean from a VXIbool
  *
  * @param   n   VXIbool value, either TRUE or FALSE
  * @return      Boolean with the specified value on success, 
  *              NULL otherwise
  */
 VXIVALUE_API VXIBoolean *VXIBooleanCreate(VXIbool n);
 
 /**
  * Boolean destructor
  *
  * @param   i   Boolean to destroy
  */
 VXIVALUE_API void VXIBooleanDestroy(VXIBoolean **i);
 
 /**
  * Get the value of a Boolean
  *
  * @param   i   Boolean to obtain the value from
  * @return      VXIbool boolean value, either TRUE or FALSE
  */
 VXIVALUE_API VXIbool VXIBooleanValue(const VXIBoolean *i);
 
 /**
  * Create an Integer from a 32 bit integer
  *
  * @param   n   32 bit integer value
  * @return      Integer with the specified value on success, 
  *              NULL otherwise
  */
 VXIVALUE_API VXIInteger *VXIIntegerCreate(VXIint32 n);
 
 /**
  * Integer destructor
  *
  * @param   i   Integer to destroy
  */
 VXIVALUE_API void VXIIntegerDestroy(VXIInteger **i);
 
 /**
  * Get the value of an Integer
  *
  * @param   i   Integer to obtain the value from
  * @return      32 bit integer value
  */
 VXIVALUE_API VXIint32 VXIIntegerValue(const VXIInteger *i);
 
 /**
  * Create a Float from a 32 bit floating point number
  *
  * @param   n   32 bit floating point value
  * @return      Float with the specified value on success, 
  *              NULL otherwise
  */
 VXIVALUE_API VXIFloat *VXIFloatCreate(VXIflt32 n);
 
 /**
  * Float destructor
  *
  * @param   f   Float to destroy
  */
 VXIVALUE_API void VXIFloatDestroy(VXIFloat **f);
 
 /**
  * Get the value of a Float
  *
  * @param   f   Float to get the value from
  * @return      32 bit floating point value
  */
 VXIVALUE_API VXIflt32 VXIFloatValue(const VXIFloat *f);
 
 /**
  * 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