VXIrec.h
上传用户:xqtpzdz
上传日期:2022-05-21
资源大小:1764k
文件大小:30k
源码类别:

xml/soap/webservice

开发平台:

Visual C++

  1. /****************License************************************************
  2.  * Vocalocity OpenVXI
  3.  * Copyright (C) 2004-2005 by Vocalocity, Inc. All Rights Reserved.
  4.  * This program is free software; you can redistribute it and/or
  5.  * modify it under the terms of the GNU General Public License
  6.  * as published by the Free Software Foundation; either version 2
  7.  * of the License, or (at your option) any later version.
  8.  *  
  9.  * This program is distributed in the hope that it will be useful,
  10.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12.  * GNU General Public License for more details.
  13.  *
  14.  * You should have received a copy of the GNU General Public License
  15.  * along with this program; if not, write to the Free Software
  16.  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  17.  * Vocalocity, the Vocalocity logo, and VocalOS are trademarks or 
  18.  * registered trademarks of Vocalocity, Inc. 
  19.  * OpenVXI is a trademark of Scansoft, Inc. and used under license 
  20.  * by Vocalocity.
  21.  ***********************************************************************/
  22. #ifndef _VXIREC_H
  23. #define _VXIREC_H
  24. #include "VXItypes.h"
  25. #include "VXIvalue.h"
  26. #include "VXItel.h"
  27. #include "VXIheaderPrefix.h"
  28. #ifdef VXIREC_EXPORTS
  29. #define VXIREC_API SYMBOL_EXPORT_DECL
  30. #else
  31. #define VXIREC_API SYMBOL_IMPORT_DECL
  32. #endif
  33. #ifdef __cplusplus
  34. extern "C" {
  35. struct VXIrecGrammar;
  36. #else
  37. typedef struct VXIrecGrammar { void * dummy; } VXIrecGrammar;
  38. #endif
  39. /**
  40.  * defgroup VXIrec Rec Interface
  41.  *
  42.  * Abstract interface for recognition functionality required by
  43.  * VoiceXML. Recognition is performed against VXIrecGrammars, abstract
  44.  * grammar types managed by the interface. The exact grammar formats
  45.  * handled are implementation dependant. <p>
  46.  */
  47. /*@{*/
  48. #define VXIREC_MIMETYPE_ULAW       VXI_MIME_ULAW
  49. #define VXIREC_MIMETYPE_XMLRESULT  L"application/x-vocalocity.nlsml"
  50. /**
  51.  * @name Properties
  52.  * Keys identifying properties in VXIMap
  53.  *
  54.  * For VXIrecInterface::LoadGrammarURI and VXIrecInterface::LoadGrammarString, 
  55.  * the only standard properties are VXIinet properties that are simply passed 
  56.  * through to VXIinet for fetches as-is. The implementation may define additional
  57.  * properties. <p>
  58.  *
  59.  * For VXIrecInterface::Recognize and VXIrecInterface::Record, the following 
  60.  * standard properties are defined:
  61.  */
  62. /*@{*/
  63. #define REC_BARGEIN_TYPE            L"vxi.rec.bargeinType"         /* VXIInteger, VXIrecBargeinType */
  64. #define REC_BEEP                    L"vxi.rec.beep"
  65. #define REC_CONFIDENCE_LEVEL        L"vxi.rec.confidenceLevel"     /* VXIFloat 0.0 - 1.0 */
  66. #define REC_DTMF_FLUSH_QUEUE        L"vxi.rec.flushDTMFQueue"      /* VXIBoolean */
  67. #define REC_DTMF_TERMINATOR_CHAR    L"vxi.rec.terminatorChar"      /* VXIString with one character */
  68. #define REC_DTMF_TIMEOUT            L"vxi.rec.timeout"             /* VXIInteger */
  69. #define REC_DTMF_TIMEOUT_INTERDIGIT L"vxi.rec.timeoutInterdigit"   /* VXIInteger */
  70. #define REC_DTMF_TIMEOUT_TERMINATOR L"vxi.rec.timeoutTerminator"   /* VXIInteger */
  71. #define REC_INPUT_MODES             L"vxi.rec.inputModes"          /* VXIInteger, VXIrecInputMode value */
  72. #define REC_MAX_RECORDING_TIME      L"vxi.rec.maxRecordingTime"    /* VXIInteger */
  73. #define REC_RECORD_MIME_TYPE        L"vxi.rec.recordingMimeType"   /* VXIString */
  74. #define REC_RECORDUTTERANCE         L"vxi.rec.recordutterance"     /* VXIString ('true' | 'false') */
  75. #define REC_RECORDUTTERANCETYPE     L"vxi.rec.recordutterancetype" /* VXIString */
  76. #define REC_RESULT_NBEST_SIZE       L"vxi.rec.resultNbestSize"     /* VXIInteger */
  77. #define REC_SENSITIVITY             L"vxi.rec.sensitivity"         /* VXIFloat 0.0 - 1.0 */
  78. #define REC_SPEED_VS_ACCURACY       L"vxi.rec.speedVsAccuracy"     /* VXIFloat 0.0-1.0 */
  79. #define REC_TERMINATED_ON_DTMF      L"vxi.rec.terminatedOnDTMF"    /* VXIInteger, 0 for disabled, 1 for enabled */
  80. #define REC_TIMEOUT                 L"vxi.rec.timeout"             /* VXIInteger */
  81. #define REC_TIMEOUT_COMPLETE        L"vxi.rec.timeoutComplete"     /* VXIInteger */
  82. #define REC_TIMEOUT_INCOMPLETE      L"vxi.rec.timeoutIncomplete"   /* VXIInteger */
  83. #define REC_TIMEOUT_SPEECH          L"vxi.rec.maxspeechtime"       /* VXIInteger */
  84. /*@}*/
  85. /**
  86.  * @name Grammar Properties
  87.  *
  88.  * For VXIrecInterface::LoadGrammarURI, VXIrecInterface::LoadGrammarString, and 
  89.  * VXIrecInterface::LoadGrammarOption, the following standard properties are defined:
  90.  */
  91. /*@{*/
  92. #define REC_GRAMMAR_ACCEPTANCE      L"vxi.rec.grammarAcceptance" /* VXIInteger, 0 or undefined for exact, 1 for approximate */
  93. #define REC_GRAMMAR_MODE            L"vxi.rec.grammarMode"       /* VXIString ('voice' | 'dtmf' */
  94. #define REC_GRAMMAR_WEIGHT          L"vxi.rec.grammarWeight"     /* VXIFloat */
  95. #define REC_LANGUAGE                L"vxi.rec.language"          /* VXIString */
  96. #define REC_PREFETCH_REQUEST        L"vxi.rec.prefetchLevel"     /* VXIInteger, 0 if no prefetch is requested, 1 is prefetch is desired */
  97. /*@}*/
  98. /**
  99.  * Bargein types as set in the REC_BARGEIN_TYPE property defined above
  100.  */
  101. typedef enum VXIrecBargeinType {
  102.   REC_BARGEIN_SPEECH          = 2,  /** Terminate prompt when start of speech detected */
  103.   REC_BARGEIN_HOTWORD         = 4   /** Terminate prompt on recognition success        */
  104. } VXIrecBargeinType;
  105. /**
  106.  * Input modes as set in the REC_INPUT_MODE property defined above and
  107.  * as returned in VXIrecResult structures
  108.  */
  109. typedef enum VXIrecInputMode {
  110.   REC_INPUT_MODE_DTMF         = 2,  /** Only DTMF input accepted       */
  111.   REC_INPUT_MODE_SPEECH       = 4,  /** Only speech input accepted     */
  112.   REC_INPUT_MODE_DTMF_SPEECH  = 6   /** DTMF and speech input accepted */
  113. } VXIrecInputMode;
  114. /**
  115.  * MIME content types for LoadGrammarURI and LoadGrammarString,
  116.  * the implementation usually supports additional MIME types 
  117.  */
  118. #define REC_MIME_CHOICE         L"text/x-grammar-choice"
  119. #define REC_MIME_CHOICE_DTMF    L"text/x-grammar-choice-dtmf"
  120. /**
  121.  * Recognition result as returned by Recognize().
  122.  */
  123. typedef struct VXIrecRecognitionResult {
  124.   /**
  125.    * The semantic interpretation of the recognition expressed using the
  126.    * Natural Language Semantic Markup Language (NLSML).  The mimetype
  127.    * of the VXIContent may allow multiple formats to be supported.
  128.    */
  129.   VXIContent*     xmlresult;
  130.   /**
  131.    * Waveform of the caller's utterance.
  132.    *
  133.    * If the VXML property 'recordutterance' is true, the audio data
  134.    * of the callers utterance should be placed here.  Otherwise,
  135.    * this field should be set to NULL.
  136.    *
  137.    * The MIME type of the utterance, as specified by 'recordutterancetype'
  138.    * should be used when calling VXIContentCreate.
  139.    */
  140.   VXIContent*     utterance;
  141.   /**
  142.    * Utterance length in milliseconds.  This field is ignored if
  143.    * 'utterance' is NULL.
  144.    */
  145.   VXIunsigned     utteranceDuration;
  146.   /**
  147.    * The name of the mark last executed by the SSML processor before 
  148.    * barge-in occurred or the end of audio playback occurred. If no 
  149.    * mark was executed, this variable is NULL.
  150.    */
  151.   VXIString*      markname;
  152.   /**
  153.    * The number of milliseconds that elapsed since the last mark was 
  154.    * executed by the SSML processor until barge-in occurred or the end 
  155.    * of audio playback occurred. If no mark was executed, this variable 
  156.    * is NULL.
  157.    */
  158.   VXIunsigned     marktime;
  159.   /**
  160.    * Call to release the resources stored with this result structure.
  161.    * The implementor of this function is expected to destroy all members
  162.    * of this structure.  i.e., VXIContentDestory, VXIStringDestroy,
  163.    * or VXIULongDestroy respectively.
  164.    */
  165.   void            (*Destroy)(struct VXIrecRecognitionResult **result);
  166. } VXIrecRecognitionResult;
  167. /**
  168.  * Record results structure as returned by Record()
  169.  */
  170. typedef struct VXIrecRecordResult {
  171.   /** 
  172.    * The bytes of the recording 
  173.    */
  174.   VXIContent * waveform;
  175.   /**
  176.    * The semantic interpretation of the recognition expressed using the
  177.    * Natural Language Semantic Markup Language (NLSML).  The mimetype
  178.    * of the VXIContent may allow multiple formats to be supported.
  179.    */
  180.   VXIContent*  xmlresult;
  181.   /**
  182.    * The name of the mark last executed by the SSML processor before 
  183.    * barge-in occurred or the end of audio playback occurred. If no 
  184.    * mark was executed, this variable is NULL.
  185.    */
  186.   VXIString*      markname;
  187.   /**
  188.    * The number of milliseconds that elapsed since the last mark was 
  189.    * executed by the SSML processor until barge-in occurred or the end 
  190.    * of audio playback occurred. If no mark was executed, this variable 
  191.    * is NULL.
  192.    */
  193.   VXIunsigned     marktime;
  194.   /** 
  195.    * Duration of the recording in milliseconds 
  196.    */
  197.   VXIunsigned duration;
  198.   /** 
  199.    * DTMF character which terminated the recording, or 0 if none. 
  200.    */
  201.   VXIbyte termchar;
  202.   /** 
  203.    * True if the recording was terminated because the maximum time 
  204.    * limit was reached 
  205.    */
  206.   VXIbool maxtime;
  207.   /**
  208.    * Call to release the resources stored with this result structure.
  209.    * The implementor of this function is expected to destroy all members
  210.    * of this structure.  i.e., VXIContentDestory, VXIStringDestroy,
  211.    * or VXIULongDestroy respectively.
  212.    */
  213.   void (*Destroy)(struct VXIrecRecordResult **result);
  214. } VXIrecRecordResult;
  215. /**
  216.  * Record results structure as returned by HotwordTransfer()
  217.  */
  218. typedef struct VXIrecTransferResult {
  219.   /**
  220.    * The semantic interpretation of the recognition expressed using the
  221.    * Natural Language Semantic Markup Language (NLSML).  The mimetype
  222.    * of the VXIContent may allow multiple formats to be supported.
  223.    */
  224.   VXIContent*  xmlresult;
  225.   /** 
  226.    * Duration of the transfer in milliseconds
  227.    */
  228.   VXIunsigned duration;
  229.   /**
  230.    * Result code for the transfer request 
  231.    */
  232.   VXItelTransferStatus status;
  233.   /**
  234.    * The name of the mark last executed by the SSML processor before 
  235.    * barge-in occurred or the end of audio playback occurred. If no 
  236.    * mark was executed, this variable is NULL.
  237.    */
  238.   VXIString*      markname;
  239.   /**
  240.    * The number of milliseconds that elapsed since the last mark was 
  241.    * executed by the SSML processor until barge-in occurred or the end 
  242.    * of audio playback occurred. If no mark was executed, this variable 
  243.    * is NULL.
  244.    */
  245.   VXIunsigned     marktime;
  246.   /**
  247.    * Waveform of the caller's utterance.
  248.    *
  249.    * If the VXML property 'recordutterance' is true, the audio data
  250.    * of the callers utterance should be placed here.  Otherwise,
  251.    * this field should be set to NULL.
  252.    *
  253.    * The MIME type of the utterance, as specified by 'recordutterancetype'
  254.    * should be used when calling VXIContentCreate.
  255.    */
  256.   VXIContent*     utterance;
  257.   /**
  258.    * Utterance length in milliseconds.  This field is ignored if
  259.    * 'utterance' is NULL.
  260.    */
  261.   VXIunsigned     utteranceDuration;
  262.   /**
  263.    * Call to release the resources stored with this result structure.
  264.    * The implementor of this function is expected to destroy all members
  265.    * of this structure.  i.e., VXIContentDestory, VXIStringDestroy,
  266.    * or VXIULongDestroy respectively.
  267.    */
  268.   void            (*Destroy)(struct VXIrecTransferResult **result);
  269. } VXIrecTransferResult;
  270. /**
  271.  * Result codes for interface methods
  272.  * 
  273.  * Result codes less then zero are severe errors (likely to be
  274.  * platform faults), those greater then zero are warnings (likely to
  275.  * be application issues) 
  276.  */
  277. typedef enum VXIrecResult {
  278.   /* Fatal error, terminate call     */
  279.   VXIrec_RESULT_FATAL_ERROR        = -100, 
  280.   /* I/O error                       */
  281.   VXIrec_RESULT_IO_ERROR           =   -8,
  282.   /* Out of memory                   */
  283.   VXIrec_RESULT_OUT_OF_MEMORY      =   -7, 
  284.   /* System error, out of service    */
  285.   VXIrec_RESULT_SYSTEM_ERROR       =   -6, 
  286.   /* Errors from platform services   */
  287.   VXIrec_RESULT_PLATFORM_ERROR     =   -5, 
  288.   /* Return buffer too small         */
  289.   VXIrec_RESULT_BUFFER_TOO_SMALL   =   -4, 
  290.   /* Property name is not valid      */
  291.   VXIrec_RESULT_INVALID_PROP_NAME  =   -3, 
  292.   /* Property value is not valid     */
  293.   VXIrec_RESULT_INVALID_PROP_VALUE =   -2, 
  294.   /* Invalid function argument       */
  295.   VXIrec_RESULT_INVALID_ARGUMENT   =   -1, 
  296.   /* Success                         */
  297.   VXIrec_RESULT_SUCCESS            =    0,
  298.   /* Normal failure, nothing logged  */
  299.   VXIrec_RESULT_FAILURE            =    1,
  300.   /* Non-fatal non-specific error    */
  301.   VXIrec_RESULT_NON_FATAL_ERROR    =    2, 
  302.   /* URL fetch timeout               */
  303.   VXIrec_RESULT_FETCH_TIMEOUT      =   50,
  304.   /* URL fetch error                 */
  305.   VXIrec_RESULT_FETCH_ERROR        =   51,
  306.   /* Unsupported grammar type        */
  307.   VXIrec_RESULT_BAD_GRAMMAR        =   52,
  308.   /* Grammar syntax error            */
  309.   VXIrec_RESULT_SYNTAX_ERROR       =   53,
  310.   /* Unsupported MIME type           */
  311.   VXIrec_RESULT_BAD_MIME_TYPE      =   54,
  312.   VXIrec_RESULT_UNSUPPORTED_FORMAT =   VXIrec_RESULT_BAD_MIME_TYPE,
  313.   /* Unsupported builtin  */
  314.   VXIrec_RESULT_UNSUPPORTED_BUILTIN =   55,
  315.   /* Unsupported language            */
  316.   VXIrec_RESULT_UNSUPPORTED_LANGUAGE =   56,
  317.   /* Requested resource not available */
  318.   VXIrec_RESULT_NO_RESOURCE        =   57,
  319.   /* Operation is not authorized  */
  320.   VXIrec_RESULT_NO_AUTHORIZATION   =   58,
  321.   /* User input is too long, exceeding */
  322.   /* 'maxspeechtimeout' property   */
  323.   VXIrec_RESULT_MAX_SPEECH_TIMEOUT =   59,
  324.   /* HOT WORD TRANSFER RETURN CODES  */
  325.   /* Call is not allowed to the destination */
  326.   VXIrec_RESULT_CONNECTION_NO_AUTHORIZATION =   60,
  327.   /* The destination URI is malformed */
  328.   VXIrec_RESULT_CONNECTION_BAD_DESTINATION =   61,    
  329.   /* The platform is not able to   */
  330.   /* place a call to the destination */
  331.   VXIrec_RESULT_CONNECTION_NO_ROUTE =   62,
  332.   /* The platform cannot allocate    */
  333.   /* resources to place the call     */
  334.   VXIrec_RESULT_CONNECTION_NO_RESOURCE =   63,
  335.   /* The platform does not support   */
  336.   /* the URI format  */
  337.   VXIrec_RESULT_UNSUPPORTED_URI    =   64,
  338.   /* Operation is not supported      */
  339.   VXIrec_RESULT_UNSUPPORTED        =  100
  340. } VXIrecResult;
  341. /** 
  342.  * Abstract interface for recognition functionality required by
  343.  * VoiceXML. Recognition is performed against VXIrecGrammars, abstract
  344.  * grammar types managed by the interface. The exact grammar formats
  345.  * handled are implementation dependant. <p>
  346.  *
  347.  * If an asynchronous problem/error occurs in the platform's
  348.  * recognizer, the VXI is notified through the VXIrecResult code for
  349.  * the current or next function call. <p>
  350.  *
  351.  * There is one recognizer interface per thread/line.
  352.  */
  353. typedef struct VXIrecInterface {
  354.   /**
  355.    * Get the VXI interface version implemented
  356.    *
  357.    * @return  VXIint32 for the version number. The high high word is 
  358.    *          the major version number, the low word is the minor version 
  359.    *          number, using the native CPU/OS byte order. The current
  360.    *          version is VXI_CURRENT_VERSION as defined in VXItypes.h.
  361.    */ 
  362.   VXIint32 (*GetVersion)(void);
  363.   
  364.   /**
  365.    * Get the name of the implementation
  366.    *
  367.    * @return  Implementation defined string that must be different from
  368.    *          all other implementations. The recommended name is one
  369.    *          where the interface name is prefixed by the implementator's
  370.    *          Internet address in reverse order, such as com.xyz.rec for
  371.    *          VXIrec from xyz.com. This is similar to how VoiceXML 1.0
  372.    *          recommends defining application specific error types.
  373.    */
  374.   const VXIchar* (*GetImplementationName)(void);
  375.   
  376.   /**
  377.    * Reset for a new speaker
  378.    *
  379.    * This must be called for each new caller, allowing for
  380.    * caller-specific recognition adaptation to occur.
  381.    *
  382.    * @param args  <b>[IN]</b> Implementation defined input and output
  383.    *                          arguments for the new session
  384.    *
  385.    * @return VXIrec_RESULT_SUCCESS on success 
  386.    */
  387.   VXIrecResult (*BeginSession)(struct VXIrecInterface  *pThis,  
  388.                                VXIMap                 *args);
  389.   /**
  390.    * Performs cleanup at the end of a speaker's session
  391.    *
  392.    * This must be called at the termination of a call, allowing for
  393.    * call specific termination to occur. For some implementations, this 
  394.    * can be a no-op. For others runtime resources may be released or other
  395.    * adaptation may be completed.
  396.    *
  397.    * @param args  <b>[IN]</b> Implementation defined input and output
  398.    *                          arguments for ending the session
  399.    *
  400.    * @return VXIrec_RESULT_SUCCESS on success
  401.    */
  402.   VXIrecResult (*EndSession)(struct VXIrecInterface  *pThis, 
  403.                              VXIMap                 *args);
  404.   /**
  405.    * Load a grammar from a URI, typically non-blocking.
  406.    *
  407.    * Initiates grammar creation from a URI (Universal Resource
  408.    * Identifier).  The resulting grammar must be activated before use.
  409.    * This allows for multiple grammars to be loaded when the page is
  410.    * read.  Grammar creation may proceed either synchronously or
  411.    * asynchronously, but must be available once ActivateGrammar( )
  412.    * returns.
  413.    *
  414.    * The supported grammar formats are determined by the implementor,
  415.    * but certain VoiceXML built-in types (e.g., grammar
  416.    * src=builtin:grammar/digits?length=5) must be supported.
  417.    *
  418.    * @param properties  <b>[IN]</b>  Set of properties as defined above
  419.    * @param type        <b>[IN]</b>  MIME type of the grammar, one of the
  420.    *                                 REC_MIME_[...] defines above or an
  421.    *                                 implementation defined grammar type
  422.    * @param uri         <b>[IN]</b>  URI of the grammar definition
  423.    * @param uriArgs     <b>[IN]</b>  Caching, timeout, base URI and other properties
  424.    *                                 associated with URI retrieval.
  425.    * @param gram        <b>[OUT]</b> Handle to the new grammar 
  426.    *
  427.    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:<br>
  428.    *         VXIrec_RESULT_UNSUPPORTED_FORMAT,<br>
  429.    *         VXIrec_RESULT_UNSUPPORTED_LANGUAGE,<br>
  430.    *         VXIrec_RESULT_UNSUPPORTED_BUILTIN,<br>
  431.    *         VXIrec_RESULT_NO_AUTHORIZATION i.e: restricted builtin uri,<br>
  432.    *         VXIrec_RESULT_FETCH_TIMEOUT,<br>
  433.    *         VXIrec_RESULT_FETCH_ERROR,<br>
  434.    *         VXIrec_RESULT_OUT_OF_MEMORY,<br>
  435.    *         VXIrec_RESULT_NO_RESOURCE,<br>
  436.    *         VXIrec_RESULT_FAILURE
  437.    */
  438.   VXIrecResult (*LoadGrammarURI)(struct VXIrecInterface  *pThis,
  439.                                  const VXIMap            *properties,
  440.                                  const VXIchar           *type, 
  441.                                  const VXIchar           *uri,
  442.                                  const VXIMap            *uriArgs,
  443.                                  VXIrecGrammar          **gram);
  444.   /**
  445.    * Load an inline grammar, typically non-blocking
  446.    *
  447.    * Initiates grammar creation from a string inlined in the VoiceXML
  448.    * page.  As with URIs, the resulting grammar must be activated
  449.    * before use and creation may be either synchronous or
  450.    * asynchronous.  See LoadGrammarURI( ). <p>
  451.    *
  452.    * The supported grammar formats are determined by the implementor,
  453.    * but support for a minimal JSGF fragment of the following form is
  454.    * required: <p>
  455.    *
  456.    *    "vocab_item {value} | vocab_item {value} | vocab_item" <p>
  457.    *
  458.    * This format is used by the VoiceXML interpreter for &lt;field&gt; and
  459.    * in some other cases. 
  460.    *
  461.    * @param properties  <b>[IN]</b>  Set of properties as defined above
  462.    * @param type        <b>[IN]</b>  MIME type of the grammar, one of the
  463.    *                                 REC_MIME_[...] defines above or an
  464.    *                                 implementation defined grammar type
  465.    * @param gramDef     <b>[IN]</b>  String containing the grammar definition
  466.    * @param gram        <b>[OUT]</b> Handle to the new grammar 
  467.    *
  468.    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:<br>
  469.    *         VXIrec_RESULT_UNSUPPORTED_FORMAT,<br>
  470.    *         VXIrec_RESULT_UNSUPPORTED_LANGUAGE,<br>
  471.    *         VXIrec_RESULT_OUT_OF_MEMORY,<br>
  472.    *         VXIrec_RESULT_NO_RESOURCE,<br>
  473.    *         VXIrec_RESULT_FAILURE
  474.    */
  475.   VXIrecResult (*LoadGrammarString)(struct VXIrecInterface  *pThis,
  476.                                     const VXIMap            *properties,
  477.                                     const VXIchar           *type,
  478.                                     const VXIchar           *gramDef,
  479.                                     VXIrecGrammar          **gram);
  480.   /**
  481.    * Activate a loaded VXIrecGrammar for subsequent recognition calls
  482.    *
  483.    * Multiple grammars may be activated before invoking Recognize( ).
  484.    * Once this returns, the grammar must be fully loaded and ready for
  485.    * recognition. See also LoadGrammarURI( ).
  486.    *
  487.    * @param properties  <b>[IN]</b>  Set of properties as defined above
  488.    * @param gram        <b>[IN]</b>  Grammar to activate
  489.    *
  490.    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:<br>
  491.    *         VXIrec_RESULT_UNSUPPORTED_FORMAT,<br>
  492.    *         VXIrec_RESULT_UNSUPPORTED_LANGUAGE,<br>
  493.    *         VXIrec_RESULT_UNSUPPORTED_BUILTIN,<br>
  494.    *         VXIrec_RESULT_NO_AUTHORIZATION i.e: restricted builtin uri,<br>
  495.    *         VXIrec_RESULT_FETCH_TIMEOUT,<br>
  496.    *         VXIrec_RESULT_FETCH_ERROR,<br>
  497.    *         VXIrec_RESULT_OUT_OF_MEMORY,<br>
  498.    *         VXIrec_RESULT_NO_RESOURCE,<br>
  499.    *         VXIrec_RESULT_FAILURE
  500.    */
  501.   VXIrecResult (*ActivateGrammar)(struct VXIrecInterface  *pThis,
  502.                                   const VXIMap            *properties,
  503.                                   VXIrecGrammar           *gram);
  504.   /**
  505.    * Deactivate a loaded VXIrecGrammar for subsequent recognition calls.
  506.    *
  507.    * Deactivate a grammar on this interface which should be used by one 
  508.    * line.  Subsequent recognitions will not use this grammar in the 
  509.    * recognition.
  510.    *
  511.    * @param gram        <b>[IN]</b>  Grammar to deactivate
  512.    *
  513.    * @return VXIrec_RESULT_SUCCESS on success
  514.    */
  515.   VXIrecResult (*DeactivateGrammar)(struct VXIrecInterface  *pThis,
  516.                                     VXIrecGrammar           *gram);
  517.   /**
  518.    * Free a loaded grammar.
  519.    * 
  520.    * Signals that the grammar is no longer needed.  The implementation
  521.    * can recover resources as it sees fit.
  522.    *
  523.    * @param gram       <b>[IN/OUT]</b> Grammar to free, the pointer is set to
  524.    *                                   NULL
  525.    *
  526.    * @return VXIrec_RESULT_SUCCESS on success 
  527.    */
  528.   VXIrecResult (*FreeGrammar)(struct VXIrecInterface  *pThis,
  529.                               VXIrecGrammar          **gram);
  530.   /**
  531.    * Recognize against the currently active grammars.
  532.    *
  533.    * Blocks until recognition completes (possibly unsuccessfully),
  534.    * DTMF input completes, a timeout occurs, or an error
  535.    * occurs. Recognition results are returned in a structure. All
  536.    * activated grammars are deactivated after the recognition.
  537.    *
  538.    * @param properties   <b>[IN]</b>  Set of properties as defined above
  539.    * @param recogResult  <b>[OUT]</b> Newly allocated result structure 
  540.    *                                  containing the result of the
  541.    *                                  recognize operation, see the structure
  542.    *                                  definition above
  543.    *
  544.    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:<br>
  545.    *         VXIrec_RESULT_MAX_SPEECH_TIMEOUT,<br>
  546.    *         VXIrec_RESULT_OUT_OF_MEMORY,<br>
  547.    *         VXIrec_RESULT_NO_RESOURCE,<br>
  548.    *         VXIrec_RESULT_FAILURE
  549.    */
  550.   VXIrecResult (*Recognize)(struct VXIrecInterface    *pThis,
  551.                             const VXIMap              *properties,
  552.                             VXIrecRecognitionResult  **recogResult);
  553.   /**
  554.    * Record audio content.
  555.    *
  556.    * Blocks until termination input occurs, a timeout occurs, or an
  557.    * error occurs. Record results are returned in a structure.
  558.    *
  559.    * @param properties   <b>[IN]</b>  Set of properties as defined above
  560.    * @param recordResult <b>[OUT]</b> Newly allocated result structure 
  561.    *                                  containing the result of the
  562.    *                                  record operation, see the structure
  563.    *                                  definition above
  564.    *
  565.    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:<br>
  566.    *         VXIrec_RESULT_UNSUPPORTED_FORMAT,<br>
  567.    *         VXIrec_RESULT_OUT_OF_MEMORY,<br>
  568.    *         VXIrec_RESULT_NO_RESOURCE,<br>
  569.    *         VXIrec_RESULT_FAILURE
  570.    */
  571.   VXIrecResult (*Record)(struct VXIrecInterface  *pThis,
  572.                          const VXIMap            *properties,
  573.                          VXIrecRecordResult     **recordResult);
  574.   /**
  575.    * GetMatchedGrammar returns grammar for ID in recognition result.
  576.    *
  577.    * An XML result returned by a successful recognition contains a string
  578.    * identifying the matched grammar.  This function is use to map that 
  579.    * string back to the corresponding VXIrecGrammar.
  580.    *
  581.    * @param grammarID     <b>[IN]</b> String identifier from the XML result.
  582.    * @param gram          <b>[OUT]</b> Corresponding VXIrecGrammar.
  583.    *
  584.    * @return VXIrec_RESULT_SUCCESS on success
  585.    */
  586.   VXIrecResult (*GetMatchedGrammar)(struct VXIrecInterface * pThis,
  587.                                     const VXIchar *grammarID,
  588.                                     const VXIrecGrammar **gram);
  589.   /**
  590.    * LoadGrammarOption may build a grammar for a VXML &lt;option&gt; element.
  591.    *
  592.    * VoiceXML 2.0 requires support for the SRGS XML format but provides no
  593.    * standard for building semantic results inside the grammar.  The &lt;option&gt;
  594.    * element is unique in that it requires this mapping.  The interpreter will
  595.    * invoke this function to build each option grammar.  For each &lt;field&gt;,
  596.    * LoadGrammarOption may be called once for speech grammars and once for
  597.    * DTMF grammars.
  598.    *
  599.    * @param properties  <b>[IN]</b> Set of properties as per LoadGrammarString
  600.    * @param gramChoices <b>[IN]</b> The utterance value for this choice
  601.    * @param gramValues  <b>[IN]</b> The corresponding semantic meaning
  602.    * @param gramAcceptance  <b>[IN]</b> The corresponding accept attribute value of VXIInteger type.
  603.    *                             The possible values are 0 for exact, 1 for approximate
  604.    * @param isDTMF      <b>[IN]</b> Is the utterance a DTMF choice?
  605.    * @param gram        <b>[OUT]</b> Handle to the new grammar; possibly NULL.
  606.    *
  607.    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:<br>
  608.    *         VXIrec_RESULT_UNSUPPORTED_LANGUAGE,<br>
  609.    *         VXIrec_RESULT_OUT_OF_MEMORY,<br>
  610.    *         VXIrec_RESULT_NO_RESOURCE,<br>
  611.    *         VXIrec_RESULT_FAILURE
  612.    */
  613.   VXIrecResult (*LoadGrammarOption)(struct VXIrecInterface  *pThis,
  614.                                     const VXIMap            *properties,
  615.                                     const VXIVector         *gramChoices,
  616.                                     const VXIVector         *gramValues,
  617.                                     const VXIVector         *gramAcceptance,
  618.                                     const VXIbool            isDTMF,
  619.                                     VXIrecGrammar          **gram);
  620.   /**
  621.    * HotwordTransfer provides for recognition terminated transfer.
  622.    * 
  623.    * Called by the interpreter to perform a bridged transfer.
  624.    *
  625.    * If a platform returns VXIrec_RESULT_UNSUPPORTED, indicating that hotword
  626.    * recognition is not supported during this transfer, the interpreter will
  627.    * call VXItelInterface::TransferBridge.
  628.    *
  629.    * @param properties     <b>[IN]</b>  termination character, length, timeouts...<br>
  630.    *                                    TEL_TRANSFER_TYPE = "consultation" or "bridge"<br>
  631.    *                                    TEL_TRANSFER_DATA = aai info<br>
  632.    *                                    TEL_MAX_CALL_TIME = VXIInteger<br>
  633.    *                                    TEL_CONNECTTIMEOUT = VXIInteger
  634.    * @param transferDest   <b>[IN]</b>  identifier of transfer location (e.g. a
  635.    *                                    phone number to dial or a SIP URL)
  636.    * @param transferResult <b>[OUT]</b> Newly allocated result structure containing
  637.    *                                    the result of the transfer request; see structure
  638.    *                                    definition above
  639.    *
  640.    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:<br>
  641.    *         VXIrec_RESULT_CONNECTION_NO_AUTHORIZATION,<br>
  642.    *         VXIrec_RESULT_CONNECTION_BAD_DESTINATION,<br>
  643.    *         VXIrec_RESULT_NO_ROUTE,<br>
  644.    *         VXIrec_RESULT_CONNECTION_NO_RESOURCE,<br>
  645.    *         VXIrec_RESULT_UNSUPPORTED_URI,<br>
  646.    *         VXIrec_RESULT_FAILURE
  647.    */
  648.   VXIrecResult (*HotwordTransfer)(struct VXIrecInterface * pThis,
  649.                                   struct VXItelInterface * tel,
  650.                                   const VXIMap *properties,
  651.                                   const VXIchar* transferDest,
  652.                                   VXIrecTransferResult  ** transferResult);
  653.   /**
  654.    * Returns whether the platform supports Hotword Transfers.
  655.    * @param properties     <b>[IN]</b>  Rec and Transfer properties<br>
  656.    * @param transferDest   <b>[IN]</b>  identifier of transfer location (e.g. a
  657.    *                                    phone number to dial or a SIP URL)
  658.    * @return TRUE if the platform supports HotwordTransfer, otherwise FALSE.
  659.    */
  660.   VXIbool (*SupportsHotwordTransfer)(struct VXIrecInterface *pThis,
  661.                                   const VXIMap  * properties,
  662.                                   const VXIchar * transferDest);
  663. } VXIrecInterface;
  664. #ifdef __cplusplus
  665. }
  666. #endif
  667. /*@}*/
  668. #include "VXIheaderSuffix.h"
  669. #endif  /* include guard */