vxirec.h

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

    * @doc
    * This must be called for each new caller, allowing for
    * caller-specific recognition adaptation to occur.
    *
    * @param args  [IN] Implementation defined input and output
    *                    arguments for the new session
    *
    * @return VXIrec_RESULT_SUCCESS on success 
    */
   VXIrecResult (*BeginSession)(struct VXIrecInterface  *pThis,  
                                VXIMap                 *args);
 
   /**
    * @name EndSession
    * @memo Performs cleanup at the end of a speaker's session
    * @doc 
    * This must be called at the termination of a call, allowing for
    * call specific termination to occur. For some implementations, this 
    * can be a no-op. For others runtime resources may be released or other
    * adaptation may be completed.
    *
    * @param args  [IN] Implementation defined input and output
    *                    arguments for ending the session
    *
    * @return VXIrec_RESULT_SUCCESS on success
    */
   VXIrecResult (*EndSession)(struct VXIrecInterface  *pThis, 
                              VXIMap                 *args);
 
   /**
    * @name LoadGrammarURI
    * @memo Load a grammar from a URI, typically non-blocking.
    *
    * @doc
    * Initiates grammar creation from a URI (Universal Resource
    * Identifier).  The resulting grammar must be activated before use.
    * This allows for multiple grammars to be loaded when the page is
    * read.  Grammar creation may proceed either synchronously or
    * asynchronously, but must be available once ActivateGrammar( )
    * returns.
    *
    * The supported grammar formats are determined by the implementor,
    * but certain VoiceXML built-in types (e.g., grammar
    * src=builtin:grammar/digits?length=5) must be supported.
    *
    * @param properties  [IN]  Set of properties as defined above
    * @param type        [IN]  MIME type of the grammar, one of the
    *                           REC_MIME_[...] defines above or an
    *                           implementation defined grammar type
    * @param uri         [IN]  URI of the grammar definition
    * @param uriArgs     [IN]  Caching, timeout, base URI and other properties
    *                           associated with URI retrieval.
    * @param gram        [OUT] Handle to the new grammar 
    *
    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:
    *         VXIrec_RESULT_UNSUPPORTED_FORMAT,
    *         VXIrec_RESULT_UNSUPPORTED_LANGUAGE,
    *         VXIrec_RESULT_UNSUPPORTED_BUILTIN,
    *         VXIrec_RESULT_NO_AUTHORIZATION i.e: restricted builtin uri,
    *         VXIrec_RESULT_FETCH_TIMEOUT,
    *         VXIrec_RESULT_FETCH_ERROR,
    *         VXIrec_RESULT_OUT_OF_MEMORY,
    *         VXIrec_RESULT_NO_RESOURCE,
    *         VXIrec_RESULT_FAILURE
    */
   VXIrecResult (*LoadGrammarURI)(struct VXIrecInterface  *pThis,
                                  const VXIMap            *properties,
                                  const VXIchar           *type, 
                                  const VXIchar           *uri,
                                  const VXIMap            *uriArgs,
                                  VXIrecGrammar          **gram);
 
   /**
    * @name LoadGrammarString
    * @memo Load an inline grammar, typically non-blocking
    *
    * @doc
    * Initiates grammar creation from a string inlined in the VoiceXML
    * page.  As with URIs, the resulting grammar must be activated
    * before use and creation may be either synchronous or
    * asynchronous.  See LoadGrammarURI( ). <p>
    *
    * The supported grammar formats are determined by the implementor,
    * but support for a minimal JSGF fragment of the following form is
    * required: <p>
    *
    *    "vocab_item {value} | vocab_item {value} | vocab_item" <p>
    *
    * This format is used by the VoiceXML interpreter for <fields> and
    * in some other cases. 
    *
    * @param properties  [IN]  Set of properties as defined above
    * @param type        [IN]  MIME type of the grammar, one of the
    *                           REC_MIME_[...] defines above or an
    *                           implementation defined grammar type
    * @param gramDef     [IN]  String containing the grammar definition
    * @param gram        [OUT] Handle to the new grammar 
    *
    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:
    *         VXIrec_RESULT_UNSUPPORTED_FORMAT,
    *         VXIrec_RESULT_UNSUPPORTED_LANGUAGE,
    *         VXIrec_RESULT_OUT_OF_MEMORY,
    *         VXIrec_RESULT_NO_RESOURCE,
    *         VXIrec_RESULT_FAILURE
    */
   VXIrecResult (*LoadGrammarString)(struct VXIrecInterface  *pThis,
                                     const VXIMap            *properties,
                                     const VXIchar           *type,
                                     const VXIchar           *gramDef,
                                     VXIrecGrammar          **gram);
 
   /**
    * @name ActivateGrammar
    * @memo Activate a loaded VXIrecGrammar for subsequent recognition calls
    *
    * @doc
    * Multiple grammars may be activated before invoking Recognize( ).
    * Once this returns, the grammar must be fully loaded and ready for
    * recognition. See also LoadGrammarURI( ).
    *
    * @param gram        [IN]  Grammar to activate
    *
    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:
    *         VXIrec_RESULT_UNSUPPORTED_FORMAT,
    *         VXIrec_RESULT_UNSUPPORTED_LANGUAGE,
    *         VXIrec_RESULT_UNSUPPORTED_BUILTIN,
    *         VXIrec_RESULT_NO_AUTHORIZATION i.e: restricted builtin uri,
    *         VXIrec_RESULT_FETCH_TIMEOUT,
    *         VXIrec_RESULT_FETCH_ERROR,
    *         VXIrec_RESULT_OUT_OF_MEMORY,
    *         VXIrec_RESULT_NO_RESOURCE,
    *         VXIrec_RESULT_FAILURE
    */
   VXIrecResult (*ActivateGrammar)(struct VXIrecInterface  *pThis,
                                   const VXIMap            *properties,
                                   VXIrecGrammar           *gram);
 
   /**
    * @name DeactivateGrammar
    * @memo Deactivate a loaded VXIrecGrammar for subsequent recognition calls
    * @doc Deactivate a grammar on this interface which should be used by one line.  Subsequent recognitions
    * will not use this grammar in the recognition.
    *
    * @param gram        [IN]  Grammar to deactivate
    *
    * @return VXIrec_RESULT_SUCCESS on success
    */
   VXIrecResult (*DeactivateGrammar)(struct VXIrecInterface  *pThis,
                                     VXIrecGrammar           *gram);
 
   /**
    * @name FreeGrammar
    * @memo Free a loaded grammar.
    * 
    * @doc
    * Signals that the grammar is no longer needed.  The implementation
    * can recover resources as it sees fit.
    *
    * @param gram       [IN/OUT] Grammar to free, the pointer is set to
    *                             NULL
    *
    * @return VXIrec_RESULT_SUCCESS on success 
    */
   VXIrecResult (*FreeGrammar)(struct VXIrecInterface  *pThis,
                               VXIrecGrammar          **gram);
 
   /**
    * @name Recognize
    * @memo Recognize against the currently active grammars
    * @doc
    * Blocks until recognition completes (possibly unsuccessfully),
    * DTMF input completes, a timeout occurs, or an error
    * occurs. Recognition results are returned in a structure. All
    * activated grammars are deactivated after the recognition.
    *
    * @param properties   [IN]  Set of properties as defined above
    * @param recogResult  [OUT] Newly allocated result structure 
    *                            containing the result of the
    *                            recognize operation, see the structure
    *                            definition above
    *
    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:
    *         VXIrec_RESULT_MAX_SPEECH_TIMEOUT,
    *         VXIrec_RESULT_OUT_OF_MEMORY,
    *         VXIrec_RESULT_NO_RESOURCE,
    *         VXIrec_RESULT_FAILURE
    */
   VXIrecResult (*Recognize)(struct VXIrecInterface    *pThis,
                             const VXIMap              *properties,
                             VXIrecRecognitionResult  **recogResult);
 
   /**
    * @name Record
    * @memo Record an utterance
    * @doc
    * Blocks until termination input occurs, a timeout occurs, or an
    * error occurs. Record results are returned in a structure.
    *
    * @param properties   [IN]  Set of properties as defined above
    * @param recordResult [OUT] Newly allocated result structure 
    *                            containing the result of the
    *                            record operation, see the structure
    *                            definition above
    *
    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:
    *         VXIrec_RESULT_UNSUPPORTED_FORMAT,
    *         VXIrec_RESULT_OUT_OF_MEMORY,
    *         VXIrec_RESULT_NO_RESOURCE,
    *         VXIrec_RESULT_FAILURE
    */
   VXIrecResult (*Record)(struct VXIrecInterface  *pThis,
                          const VXIMap            *properties,
                          VXIrecRecordResult     **recordResult);
 
   /*
    * @name GetMatchedGrammar
    * @memo GetMatchedGrammar returns grammar for ID in recognition result
    * @doc
    * An XML result returned by a successful recognition contains a string
    * identifying the matched grammar.  This function is use to map that 
    * string back to the corresponding VXIrecGrammar.
    *
    * @param grammarID     [IN] String identifier from the XML result.
    * @param gram          [OUT] Corresponding VXIrecGrammar.
    *
    * @return VXIrec_RESULT_SUCCESS on success
    */
   VXIrecResult (*GetMatchedGrammar)(struct VXIrecInterface * pThis,
                                     const VXIchar *grammarID,
                                     const VXIrecGrammar **gram);
 
   /*
    * @name LoadGrammarOption
    * @memo LoadGrammarOption may build a grammar for a VXML <option> element.
    * @doc
    * VoiceXML 2.0 requires support for the SRGS XML format but provides no
    * standard for building semantic results inside the grammar.  The <option>
    * element is unique in that it requires this mapping.  The interpreter will
    * invoke this function to build each option grammar.  For each <field>,
    * LoadGrammarOption may be called once for speech grammars and once for
    * DTMF grammars.
    *
    * @param properties  [IN] Set of properties as per LoadGrammarString
    * @param gramChoices [IN] The utterance value for this choice
    * @param gramValues  [IN] The corresponding semantic meaning
    * @param gramAcceptance  [IN] The corresponding accept attribute value of VXIInteger type.
    *                             The possible values are 0 for exact, 1 for approximate
    * @param isDTMF      [IN] Is the utterance a DTMF choice?
    * @param gram        [OUT] Handle to the new grammar; possibly NULL.
    *
    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:
    *         VXIrec_RESULT_UNSUPPORTED_LANGUAGE,
    *         VXIrec_RESULT_OUT_OF_MEMORY,
    *         VXIrec_RESULT_NO_RESOURCE,
    *         VXIrec_RESULT_FAILURE
    */
   VXIrecResult (*LoadGrammarOption)(struct VXIrecInterface  *pThis,
                                     const VXIMap            *properties,
                                     const VXIVector         *gramChoices,
                                     const VXIVector         *gramValues,
                                     const VXIVector         *gramAcceptance,
                                     const VXIbool            isDTMF,
                                     VXIrecGrammar          **gram);
 
   /*
    * @name HotwordTransfer
    * @memo HotwordTransfer provides for recognition terminated transfer
    * @doc
    * Called by the interpreter to perform a bridged transfer.
    *
    * If a platform returns VXIrec_RESULT_UNSUPPORTED, indicating that hotword
    * recognition is not supported during this transfer, the interpreter will
    * call VXItelInterface::TransferBridge.
    *
    * @param properties     [IN] termination character, length, timeouts...
    * @param transferDest   [in] identifier of transfer location (e.g. a
    *                       phone number to dial or a SIP URL)
    * @param data           [IN] the data to be sent to the transfer target
    * @param transferResult [OUT] Newly allocated result structure containing
    *                       the result of the transfer request; see structure
    *                       definition above
    *
    * @return VXIrec_RESULT_SUCCESS on success or one of the followings:
    *         VXIrec_RESULT_CONNECTION_NO_AUTHORIZATION,
    *         VXIrec_RESULT_CONNECTION_BAD_DESTINATION,
    *         VXIrec_RESULT_NO_ROUTE,
    *         VXIrec_RESULT_CONNECTION_NO_RESOURCE,
    *         VXIrec_RESULT_UNSUPPORTED_URI,
    *         VXIrec_RESULT_UNSUPPORTED i.e: skip to tel. Bridge-transfer,
    *         VXIrec_RESULT_FAILURE
    */
   VXIrecResult (*HotwordTransfer)(struct VXIrecInterface * pThis,
                                   struct VXItelInterface * tel,
                                   const VXIMap *properties,
                                   const VXIchar* transferDest,
                                   VXIrecTransferResult  ** transferResult);
 } VXIrecInterface;
 
 /*@}*/
 
 #ifdef __cplusplus
 }
 #endif
 
 #include "VXIheaderSuffix.h"
 
 #endif  /* include guard */