Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Class Members | File Members

VXIrecInterface Struct Reference
[Rec Interface]

#include <VXIrec.h>

List of all members.


Detailed Description

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.

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.

There is one recognizer interface per thread/line.


Public Attributes

VXIint32(* GetVersion )(void)
 Get the VXI interface version implemented.
const VXIchar *(* GetImplementationName )(void)
 Get the name of the implementation.
VXIrecResult(* BeginSession )(struct VXIrecInterface *pThis, VXIMap *args)
 Reset for a new speaker.
VXIrecResult(* EndSession )(struct VXIrecInterface *pThis, VXIMap *args)
 Performs cleanup at the end of a speaker's session.
VXIrecResult(* LoadGrammarURI )(struct VXIrecInterface *pThis, const VXIMap *properties, const VXIchar *type, const VXIchar *uri, const VXIMap *uriArgs, VXIrecGrammar **gram)
 Load a grammar from a URI, typically non-blocking.
VXIrecResult(* LoadGrammarString )(struct VXIrecInterface *pThis, const VXIMap *properties, const VXIchar *type, const VXIchar *gramDef, VXIrecGrammar **gram)
 Load an inline grammar, typically non-blocking.
VXIrecResult(* ActivateGrammar )(struct VXIrecInterface *pThis, const VXIMap *properties, VXIrecGrammar *gram)
 Activate a loaded VXIrecGrammar for subsequent recognition calls.
VXIrecResult(* DeactivateGrammar )(struct VXIrecInterface *pThis, VXIrecGrammar *gram)
 Deactivate a loaded VXIrecGrammar for subsequent recognition calls.
VXIrecResult(* FreeGrammar )(struct VXIrecInterface *pThis, VXIrecGrammar **gram)
 Free a loaded grammar.
VXIrecResult(* Recognize )(struct VXIrecInterface *pThis, const VXIMap *properties, VXIrecRecognitionResult **recogResult)
 Recognize against the currently active grammars.
VXIrecResult(* Record )(struct VXIrecInterface *pThis, const VXIMap *properties, VXIrecRecordResult **recordResult)
 Record audio content.
VXIrecResult(* GetMatchedGrammar )(struct VXIrecInterface *pThis, const VXIchar *grammarID, const VXIrecGrammar **gram)
 GetMatchedGrammar returns grammar for ID in recognition result.
VXIrecResult(* LoadGrammarOption )(struct VXIrecInterface *pThis, const VXIMap *properties, const VXIVector *gramChoices, const VXIVector *gramValues, const VXIVector *gramAcceptance, const VXIbool isDTMF, VXIrecGrammar **gram)
 LoadGrammarOption may build a grammar for a VXML <option> element.
VXIrecResult(* HotwordTransfer )(struct VXIrecInterface *pThis, struct VXItelInterface *tel, const VXIMap *properties, const VXIchar *transferDest, VXIrecTransferResult **transferResult)
 HotwordTransfer provides for recognition terminated transfer.
VXIbool(* SupportsHotwordTransfer )(struct VXIrecInterface *pThis, const VXIMap *properties, const VXIchar *transferDest)
 Returns whether the platform supports Hotword Transfers.


Member Data Documentation

VXIrecResult(* VXIrecInterface::ActivateGrammar)(struct VXIrecInterface *pThis, const VXIMap *properties, VXIrecGrammar *gram)
 

Activate a loaded VXIrecGrammar for subsequent recognition calls.

Multiple grammars may be activated before invoking Recognize( ). Once this returns, the grammar must be fully loaded and ready for recognition. See also LoadGrammarURI( ).

Parameters:
properties [IN] Set of properties as defined above
gram [IN] Grammar to activate
Returns:
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(* VXIrecInterface::BeginSession)(struct VXIrecInterface *pThis, VXIMap *args)
 

Reset for a new speaker.

This must be called for each new caller, allowing for caller-specific recognition adaptation to occur.

Parameters:
args [IN] Implementation defined input and output arguments for the new session
Returns:
VXIrec_RESULT_SUCCESS on success

VXIrecResult(* VXIrecInterface::DeactivateGrammar)(struct VXIrecInterface *pThis, VXIrecGrammar *gram)
 

Deactivate a loaded VXIrecGrammar for subsequent recognition calls.

Deactivate a grammar on this interface which should be used by one line. Subsequent recognitions will not use this grammar in the recognition.

Parameters:
gram [IN] Grammar to deactivate
Returns:
VXIrec_RESULT_SUCCESS on success

VXIrecResult(* VXIrecInterface::EndSession)(struct VXIrecInterface *pThis, VXIMap *args)
 

Performs cleanup at the end of a speaker's session.

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.

Parameters:
args [IN] Implementation defined input and output arguments for ending the session
Returns:
VXIrec_RESULT_SUCCESS on success

VXIrecResult(* VXIrecInterface::FreeGrammar)(struct VXIrecInterface *pThis, VXIrecGrammar **gram)
 

Free a loaded grammar.

Signals that the grammar is no longer needed. The implementation can recover resources as it sees fit.

Parameters:
gram [IN/OUT] Grammar to free, the pointer is set to NULL
Returns:
VXIrec_RESULT_SUCCESS on success

const VXIchar*(* VXIrecInterface::GetImplementationName)(void)
 

Get the name of the implementation.

Returns:
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.

VXIrecResult(* VXIrecInterface::GetMatchedGrammar)(struct VXIrecInterface *pThis, const VXIchar *grammarID, const VXIrecGrammar **gram)
 

GetMatchedGrammar returns grammar for ID in recognition result.

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.

Parameters:
grammarID [IN] String identifier from the XML result.
gram [OUT] Corresponding VXIrecGrammar.
Returns:
VXIrec_RESULT_SUCCESS on success

VXIint32(* VXIrecInterface::GetVersion)(void)
 

Get the VXI interface version implemented.

Returns:
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.

VXIrecResult(* VXIrecInterface::HotwordTransfer)(struct VXIrecInterface *pThis, struct VXItelInterface *tel, const VXIMap *properties, const VXIchar *transferDest, VXIrecTransferResult **transferResult)
 

HotwordTransfer provides for recognition terminated transfer.

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.

Parameters:
properties [IN] termination character, length, timeouts...
TEL_TRANSFER_TYPE = "consultation" or "bridge"
TEL_TRANSFER_DATA = aai info
TEL_MAX_CALL_TIME = VXIInteger
TEL_CONNECTTIMEOUT = VXIInteger
transferDest [IN] identifier of transfer location (e.g. a phone number to dial or a SIP URL)
transferResult [OUT] Newly allocated result structure containing the result of the transfer request; see structure definition above
Returns:
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_FAILURE

VXIrecResult(* VXIrecInterface::LoadGrammarOption)(struct VXIrecInterface *pThis, const VXIMap *properties, const VXIVector *gramChoices, const VXIVector *gramValues, const VXIVector *gramAcceptance, const VXIbool isDTMF, VXIrecGrammar **gram)
 

LoadGrammarOption may build a grammar for a VXML <option> element.

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.

Parameters:
properties [IN] Set of properties as per LoadGrammarString
gramChoices [IN] The utterance value for this choice
gramValues [IN] The corresponding semantic meaning
gramAcceptance [IN] The corresponding accept attribute value of VXIInteger type. The possible values are 0 for exact, 1 for approximate
isDTMF [IN] Is the utterance a DTMF choice?
gram [OUT] Handle to the new grammar; possibly NULL.
Returns:
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(* VXIrecInterface::LoadGrammarString)(struct VXIrecInterface *pThis, const VXIMap *properties, const VXIchar *type, const VXIchar *gramDef, VXIrecGrammar **gram)
 

Load an inline grammar, typically non-blocking.

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( ).

The supported grammar formats are determined by the implementor, but support for a minimal JSGF fragment of the following form is required:

"vocab_item {value} | vocab_item {value} | vocab_item"

This format is used by the VoiceXML interpreter for <field> and in some other cases.

Parameters:
properties [IN] Set of properties as defined above
type [IN] MIME type of the grammar, one of the REC_MIME_[...] defines above or an implementation defined grammar type
gramDef [IN] String containing the grammar definition
gram [OUT] Handle to the new grammar
Returns:
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(* VXIrecInterface::LoadGrammarURI)(struct VXIrecInterface *pThis, const VXIMap *properties, const VXIchar *type, const VXIchar *uri, const VXIMap *uriArgs, VXIrecGrammar **gram)
 

Load a grammar from a URI, typically non-blocking.

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.

Parameters:
properties [IN] Set of properties as defined above
type [IN] MIME type of the grammar, one of the REC_MIME_[...] defines above or an implementation defined grammar type
uri [IN] URI of the grammar definition
uriArgs [IN] Caching, timeout, base URI and other properties associated with URI retrieval.
gram [OUT] Handle to the new grammar
Returns:
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(* VXIrecInterface::Recognize)(struct VXIrecInterface *pThis, const VXIMap *properties, VXIrecRecognitionResult **recogResult)
 

Recognize against the currently active grammars.

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.

Parameters:
properties [IN] Set of properties as defined above
recogResult [OUT] Newly allocated result structure containing the result of the recognize operation, see the structure definition above
Returns:
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(* VXIrecInterface::Record)(struct VXIrecInterface *pThis, const VXIMap *properties, VXIrecRecordResult **recordResult)
 

Record audio content.

Blocks until termination input occurs, a timeout occurs, or an error occurs. Record results are returned in a structure.

Parameters:
properties [IN] Set of properties as defined above
recordResult [OUT] Newly allocated result structure containing the result of the record operation, see the structure definition above
Returns:
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

VXIbool(* VXIrecInterface::SupportsHotwordTransfer)(struct VXIrecInterface *pThis, const VXIMap *properties, const VXIchar *transferDest)
 

Returns whether the platform supports Hotword Transfers.

Parameters:
properties [IN] Rec and Transfer properties
transferDest [IN] identifier of transfer location (e.g. a phone number to dial or a SIP URL)
Returns:
TRUE if the platform supports HotwordTransfer, otherwise FALSE.


The documentation for this struct was generated from the following file:
Generated on Wed Jun 1 12:50:19 2005 for OpenVXI by  doxygen 1.4.2