vxirec.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 _VXIREC_H
 #define _VXIREC_H
 
 #include "VXItypes.h"                  /* For VXIchar definition */
 #include "VXIvalue.h"                  /* For VXIMap */
 #include "VXItel.h"
 
 #include "VXIheaderPrefix.h"
 #ifdef VXIREC_EXPORTS
 #define VXIREC_API SYMBOL_EXPORT_DECL
 #else
 #define VXIREC_API SYMBOL_IMPORT_DECL
 #endif
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 #ifdef __cplusplus
 struct VXIrecGrammar;
 #else
 typedef struct VXIrecGrammar { void * dummy; } VXIrecGrammar;
 #endif
 
 #define VXIREC_MIMETYPE_ULAW       VXI_MIME_ULAW
 #define VXIREC_MIMETYPE_XMLRESULT  L"application/x-vnd.speechworks.osb2"
 
 /**
  * @name VXIrec
  * @memo Recognizer Interface
  * @version 1.0
  * @doc
  * Abstract interface for recognition functionality required by
  * VoiceXML. Recognition is performed against VXIrecGrammars, abstract
  * grammar types managed by the interface. The exact grammar formats
  * handled are implementation dependant. <p>
  *
  * If an asynchronous problem/error occurs in the platform's
  * recognizer, the VXI is notified through the VXIrecResult code for
  * the current or next function call. <p>
  *
  * There is one recognizer interface per thread/line.
  */
 
 /*@{*/
 /**
  * Keys identifying properties in VXIMap
  *
  * For LoadGrammarURI( ) and LoadGrammarString( ), the only standard
  * properties are VXIinet properties that are simply passed through to
  * VXIinet for fetches as-is. The implementation may define additional
  * properties. <p>
  *
  * For Recognize( ) and Record( ), the following standard properties
  * are defined.  The implementation may define additional properties.
  */
 
 
 #define REC_BARGEIN_TYPE            L"vxi.rec.bargeinType"       /* VXIInteger, VXIrecBargeinType */
 #define REC_CONFIDENCE_LEVEL        L"vxi.rec.confidenceLevel"   /* VXIFloat 0.0 - 1.0 */
 #define REC_DTMF_FLUSH_QUEUE        L"vxi.rec.flushDTMFQueue"    /* VXIBoolean */
 #define REC_DTMF_TIMEOUT            L"vxi.rec.timeout"           /* VXIInteger */
 #define REC_DTMF_TIMEOUT_INTERDIGIT L"vxi.rec.timeoutInterdigit" /* VXIInteger */
 #define REC_DTMF_TIMEOUT_TERMINATOR L"vxi.rec.timeoutTerminator" /* VXIInteger */
 #define REC_DTMF_TERMINATOR_CHAR    L"vxi.rec.terminatorChar"    /* VXIString with one character */
 #define REC_INPUT_MODES             L"vxi.rec.inputModes"        /* VXIInteger, VXIrecInputMode value */
 #define REC_RESULT_SAVE_WAVEFORM    L"vxi.rec.saveWaveform"      /* VXIInteger, 0 for disabled, 1 for enabled */
 #define REC_RESULT_NBEST_SIZE       L"vxi.rec.resultNbestSize"   /* VXIInteger */
 #define REC_SENSITIVITY             L"vxi.rec.sensitivity"       /* VXIFloat 0.0 - 1.0 */
 #define REC_TIMEOUT                 L"vxi.rec.timeout"           /* VXIInteger */
 #define REC_TIMEOUT_COMPLETE        L"vxi.rec.timeoutComplete"   /* VXIInteger */
 #define REC_TIMEOUT_INCOMPLETE      L"vxi.rec.timeoutIncomplete" /* VXIInteger */
 #define REC_SPEED_VS_ACCURACY       L"vxi.rec.speedVsAccuracy"   /* VXIFloat 0.0-1.0 */
 #define REC_MAX_RECORDING_TIME      L"vxi.rec.maxRecordingTime"  /* VXIInteger */
 #define REC_TERMINATED_ON_DTMF      L"vxi.rec.terminatedOnDTMF"  /* VXIInteger, 0 for disabled, 1 for enabled */
 #define REC_RECORD_MIME_TYPE        L"vxi.rec.recordingMimeType" /* VXIString */
 
 
 /* LoadGrammarURI, LoadGrammarString, LoadGrammarOption only */
 
 #define REC_GRAMMAR_ACCEPTANCE      L"vxi.rec.grammarAcceptance" /* VXIInteger, 0 or undefined for exact, 1 for approximate */
 #define REC_GRAMMAR_WEIGHT          L"vxi.rec.grammarWeight"     /* VXIFloat */
 #define REC_LANGUAGE                L"vxi.rec.language"          /* VXIString */
 #define REC_PREFETCH_REQUEST        L"vxi.rec.prefetchLevel"     /* VXIInteger, 0 if no prefetch is requested, 1 is prefetch is desired */
 
 
 /**
  * Bargein types as set in the REC_BARGEIN_TYPE property defined above
  */
 typedef enum VXIrecBargeinType {
   REC_BARGEIN_SPEECH          = 2,  /* Terminate prompt when start of speech detected       */
   REC_BARGEIN_HOTWORD         = 4,  /* Terminate prompt on recognition success     */
 } VXIrecBargeinType;
 
 
 /**
  * Input modes as set in the REC_INPUT_MODE property defined above and
  * as returned in VXIrecResult structures
  */
 typedef enum VXIrecInputMode {
   REC_INPUT_MODE_DTMF         = 2,  /* Only DTMF input accepted       */
   REC_INPUT_MODE_SPEECH       = 4,  /* Only speech input accepted     */
   REC_INPUT_MODE_DTMF_SPEECH  = 6   /* DTMF and speech input accepted */
 } VXIrecInputMode;
 
 /**
  * MIME content types for LoadGrammarURI( ) and LoadGrammarString( ),
  * the implementation usually supports additional MIME types 
  */
 #define REC_MIME_CHOICE         L"text/x-grammar-choice"
 #define REC_MIME_CHOICE_DTMF    L"text/x-grammar-choice-dtmf"
 
 typedef struct VXIrecRecognitionResult {
   /*
    * Waveform of the caller's utterance. Returned a VXIContent which
    * stores the length and the mime type in one unit.
    */
   VXIContent*      waveform;
 
   /*
    * The semantic interpretation of the recognition expressed using the
    * Natural Language Semantic Markup Language (NLSML).  The mimetype
    * of the VXIContent may allow multiple formats to be supported.
    */
   VXIContent*     xmlresult;
 
   /*
    * Call to release the resources stored with this result structure
    */
   void            (*Destroy)(struct VXIrecRecognitionResult **result);
 } VXIrecRecognitionResult;
 
 
 /**
  * Record results structure as returned by Record( )
  */
 typedef struct VXIrecRecordResult {
   /** The bytes of the recording */
   VXIContent * waveform;
 
   VXIContent*  xmlresult;
 
   /** Duration of the recording in milliseconds */
   VXIunsigned duration;
 
   /** DTMF character which terminated the recording, or 0 if none. */
   VXIbyte termchar;
 
   VXIbool maxtime;
   /** True if the recording was terminated because the maximum time limit was
       reached **/
 
   /*
   ** Call to release the resources stored with this result structure
   */
   void            (*Destroy)(struct VXIrecRecordResult **result);
 } VXIrecRecordResult;
 
 
 /**
  * Record results structure as returned by Record( )
  */
 typedef struct VXIrecTransferResult {
   VXIContent*  xmlresult;
 
   /** Duration of the transfer in milliseconds */
   VXIunsigned duration;
 
   /** Result code for the transfer request */
   VXItelTransferStatus status;
 
   /*
   ** Call to release the resources stored with this result structure
   */
   void            (*Destroy)(struct VXIrecTransferResult **result);
 } VXIrecTransferResult;
 
 
 /**
  * Result codes for interface methods
  * 
  * Result codes less then zero are severe errors (likely to be
  * platform faults), those greater then zero are warnings (likely to
  * be application issues) 
  */
 typedef enum VXIrecResult {
   /* Fatal error, terminate call     */
   VXIrec_RESULT_FATAL_ERROR        = -100, 
   /* I/O error                       */
   VXIrec_RESULT_IO_ERROR           =   -8,
   /* Out of memory                   */
   VXIrec_RESULT_OUT_OF_MEMORY      =   -7, 
   /* System error, out of service    */
   VXIrec_RESULT_SYSTEM_ERROR       =   -6, 
   /* Errors from platform services   */
   VXIrec_RESULT_PLATFORM_ERROR     =   -5, 
   /* Return buffer too small         */
   VXIrec_RESULT_BUFFER_TOO_SMALL   =   -4, 
   /* Property name is not valid      */
   VXIrec_RESULT_INVALID_PROP_NAME  =   -3, 
   /* Property value is not valid     */
   VXIrec_RESULT_INVALID_PROP_VALUE =   -2, 
   /* Invalid function argument       */
   VXIrec_RESULT_INVALID_ARGUMENT   =   -1, 
   /* Success                         */
   VXIrec_RESULT_SUCCESS            =    0,
   /* Normal failure, nothing logged  */
   VXIrec_RESULT_FAILURE            =    1,
   /* Non-fatal non-specific error    */
   VXIrec_RESULT_NON_FATAL_ERROR    =    2, 
   /* URL fetch timeout               */
   VXIrec_RESULT_FETCH_TIMEOUT      =   50,
   /* URL fetch error                 */
   VXIrec_RESULT_FETCH_ERROR        =   51,
   /* Unsupported grammar type        */
   VXIrec_RESULT_BAD_GRAMMAR        =   52,
   /* Grammar syntax error            */
   VXIrec_RESULT_SYNTAX_ERROR       =   53,
   /* Unsupported MIME type           */
   VXIrec_RESULT_BAD_MIME_TYPE      =   54,
   VXIrec_RESULT_UNSUPPORTED_FORMAT =   VXIrec_RESULT_BAD_MIME_TYPE,
   /* Unsupported builtin		 */
   VXIrec_RESULT_UNSUPPORTED_BUILTIN =   55,
   /* Unsupported language            */
   VXIrec_RESULT_UNSUPPORTED_LANGUAGE =   56,
   /* Requested resource not available */
   VXIrec_RESULT_NO_RESOURCE        =   57,
   /* Operation is not authorized	 */
   VXIrec_RESULT_NO_AUTHORIZATION   =   58,
   /* User input is too long, exceeding */
   /* 'maxspeechtimeout' property 	 */
   VXIrec_RESULT_MAX_SPEECH_TIMEOUT =   59,
 
   /* HOT WORD TRANSFER RETURN CODES  */
 
   /* Call is not allowed to the destination */
   VXIrec_RESULT_CONNECTION_NO_AUTHORIZATION =   60,
   /* The destination URI is malformed */
   VXIrec_RESULT_CONNECTION_BAD_DESTINATION =   61,    
   /* The platform is not able to 	 */
   /* place a call to the destination */
   VXIrec_RESULT_CONNECTION_NO_ROUTE =   62,
   /* The platform cannot allocate    */
   /* resources to place the call     */
   VXIrec_RESULT_CONNECTION_NO_RESOURCE =   63,
   /* The platform does not support   */
   /* the URI format			 */
   VXIrec_RESULT_UNSUPPORTED_URI    =   64,
   /* Operation is not supported      */
   VXIrec_RESULT_UNSUPPORTED        =  100
 } VXIrecResult;
 
 
 /*
 ** ==================================================
 ** VXIrecInterface Interface definition
 ** ==================================================
 */
 /** @name VXIrecInterface
  ** @memo VXIrec interface for speech recognition
  **
  */
 typedef struct VXIrecInterface {
   /**
    * @name GetVersion
    * @memo Get the VXI interface version implemented
    *
    * @return  VXIint32 for the version number. The high high word is 
    *          the major version number, the low word is the minor version 
    *          number, using the native CPU/OS byte order. The current
    *          version is VXI_CURRENT_VERSION as defined in VXItypes.h.
    */ 
   VXIint32 (*GetVersion)(void);
   
   /**
    * @name GetImplementationName
    * @memo Get the name of the implementation
    *
    * @return  Implementation defined string that must be different from
    *          all other implementations. The recommended name is one
    *          where the interface name is prefixed by the implementator's
    *          Internet address in reverse order, such as com.xyz.rec for
    *          VXIrec from xyz.com. This is similar to how VoiceXML 1.0
    *          recommends defining application specific error types.
    */
   const VXIchar* (*GetImplementationName)(void);
   
   /**
    * @name BeginSession
    * @memo Reset for a new speaker
    *