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

VXIpromptInterface Struct Reference
[Prompt Interface]

#include <VXIprompt.h>

List of all members.


Detailed Description

Abstract interface for Prompting functionality.

Prompts are represented as a series of SSML documents.

The Prompt interface the handles prefetching, caching, and streaming audio as required to provide good response times and low CPU and network overhead.

There is one prompt 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.
VXIpromptResult(* BeginSession )(struct VXIpromptInterface *pThis, VXIMap *args)
 Reset for a new session.
VXIpromptResult(* EndSession )(struct VXIpromptInterface *pThis, VXIMap *args)
 Performs cleanup at the end of a call session.
VXIpromptResult(* Play )(struct VXIpromptInterface *pThis)
 Start playing queued segments (non-blocking).
VXIpromptResult(* PlayFiller )(struct VXIpromptInterface *pThis, const VXIchar *type, const VXIchar *src, const VXIchar *text, const VXIMap *properties, VXIlong minPlayMsec)
 Queues and possibly starts the special play of a filler segment, non-blocking.
VXIpromptResult(* Prefetch )(struct VXIpromptInterface *pThis, const VXIchar *type, const VXIchar *src, const VXIchar *text, const VXIMap *properties)
 Prefetch a segment (non-blocking).
VXIpromptResult(* Queue )(struct VXIpromptInterface *pThis, const VXIchar *type, const VXIchar *src, const VXIchar *text, const VXIMap *properties)
 Queue a segment for playing (non-blocking).
VXIpromptResult(* Wait )(struct VXIpromptInterface *pThis, VXIpromptResult *playResult)
 Wait until all played segments finish playing, blocking.


Member Data Documentation

VXIpromptResult(* VXIpromptInterface::BeginSession)(struct VXIpromptInterface *pThis, VXIMap *args)
 

Reset for a new session.

This must be called for each new session, allowing for call specific handling to occur. For some implementations, this can be a no-op. For others runtime binding of resources or other call start specific handling may be done on this call.

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

VXIpromptResult(* VXIpromptInterface::EndSession)(struct VXIpromptInterface *pThis, VXIMap *args)
 

Performs cleanup at the end of a call 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:
VXIprompt_RESULT_SUCCESS on success

const VXIchar*(* VXIpromptInterface::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.

VXIint32(* VXIpromptInterface::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.

VXIpromptResult(* VXIpromptInterface::Play)(struct VXIpromptInterface *pThis)
 

Start playing queued segments (non-blocking).

Segments queued after this is called will not be played until this is called again. It is possible errors may occur after this function has returned: Wait() will return the appropriate error if one occurred.

Note that this stops the current PlayFiller() operation although possibly after some delay, see PlayFiller() for more information.

Returns:
VXIprompt_RESULT_SUCCESS on success

VXIpromptResult(* VXIpromptInterface::PlayFiller)(struct VXIpromptInterface *pThis, const VXIchar *type, const VXIchar *src, const VXIchar *text, const VXIMap *properties, VXIlong minPlayMsec)
 

Queues and possibly starts the special play of a filler segment, non-blocking.

This plays a standard segment in a special manner in order to satisfy "filler" needs. A typical example is the VoiceXML fetchaudio attribute, used to specify filler audio that gets played while a document fetch is being performed and then interrupted once the fetch completes.

The filler segment is played to the caller once all active Play() operations, if any, have completed. If Play(), Wait(), or PlayFiller() is called before the filler segment starts playing it is cancelled and never played. If one of those functions is instead called after the filler segment starts playing, the filler segment is stopped once the minimum playback duration expires.

NOTE: this does not trigger the play of segments that have been queued but not yet played via Play().

Parameters:
type [IN] Type of segment, either a MIME content type, a sayas class name, or NULL to automatically detect a MIME content type (only valid when src is non-NULL). The supported MIME content types and sayas class names are implementation dependant.
src deprecated
text [IN] Text (possibly with markup) to play via TTS or sayas classes, pass NULL when src is non-NULL. The format of text for TTS playback may be W3C SSML (type set to VXI_MIME_SSML) or simple wchar_t text (type set to VXI_MIME_UNICODE_TEXT). The implementation may also support other formats.
properties [IN] Properties to control the fetch, queue, and play, as specified above. May be NULL.
minPlayMsec [IN] Minimum playback duration for the filler prompt once it starts playing, in milliseconds. This is used to "lock in" a play so that no less then this amount of audio is heard by the caller once it starts playing, avoiding confusion from audio that is played for an extremely brief duration and then cut off. Note that the filler prompt may never be played at all, however, if cancelled before it ever starts playing as described above.
Returns:
VXIprompt_RESULT_SUCCESS on success

VXIpromptResult(* VXIpromptInterface::Prefetch)(struct VXIpromptInterface *pThis, const VXIchar *type, const VXIchar *src,const VXIchar *text, const VXIMap *properties)
 

Prefetch a segment (non-blocking).

This fetches the segment in the background, since this returns before the fetch proceeds failures during the fetch will not be reported (invalid URI, missing file, etc.). This may be called prior to Queue() (possibily multiple times with increasing VXIinet prefetch priorities as the time for playback gets closer).

Parameters:
type [IN] Type of segment. Currently, the only type used is VXI_MIME_SSML.
src deprecated
text [IN] The prompt text. Currently, the only text format used is SSML.
properties [IN] Properties to control the fetch, queue, and play, as specified above. May be NULL.
Returns:
VXIprompt_RESULT_SUCCESS on success

VXIpromptResult(* VXIpromptInterface::Queue)(struct VXIpromptInterface *pThis, const VXIchar *type, const VXIchar *src,const VXIchar *text, const VXIMap *properties)
 

Queue a segment for playing (non-blocking).

The segment does not start playing until the Play() method is called.

VoiceXML allows audio collected during the <record> element to be played in the middle of SSML documents. These recordings are passed by VXI to the VXIprompt implementation inside the properties VXIMap. The PROMPT_AUDIO_REFS points to a second VXIMap containing pairs of identifiers (VXIStrings) and their associated recording (VXIContent).

Within the SSML document, the audio recording is replaced by a mark element whose 'name' attribute is a key inside the PROMPT_AUDIO_REFS map. i.e., Use the mark name as the key to access the VXIContent in the PROMPT_AUDIO_REFS map. The mark name for audio content will be prefixed with PROMPT_AUDIO_REFS_SCHEME so that it can be distinguished from other <mark> elements.

Parameters:
type [IN] Type of segment. Currently, the only type used is VXI_MIME_SSML.
src deprecated
text [IN] The prompt text. Currently, the only text format used is SSML.
properties [IN] Properties to control the fetch, queue, and play, as specified above. May be NULL.
Returns:
VXIprompt_RESULT_SUCCESS on success

VXIpromptResult(* VXIpromptInterface::Wait)(struct VXIpromptInterface *pThis, VXIpromptResult *playResult)
 

Wait until all played segments finish playing, blocking.

Note that this stops the current PlayFiller() operation although possibly after some delay, see PlayFiller() for more information.

If Wait is called, and no audio is playing, this function should not block.

Parameters:
playResult [OUT] Most severe error code resulting from a Play() operation since the last Wait() call, since Play() is asynchronous, errors may have occurred after one or more calls to it have returned. Note that this ignores any errors resulting from PlayFiller() operations.
Returns:
VXIprompt_RESULT_SUCCESS on success


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