vxiprompt.h

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

    * 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 VXIprompt_RESULT_SUCCESS on success
    */
   VXIpromptResult (*EndSession)(struct VXIpromptInterface  *pThis,
                                 VXIMap                     *args);
 
   /**
    * @name Play
    * @memo Start playing queued segments, non-blocking
    *
    * @doc
    * 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.
    *
    * @return VXIprompt_RESULT_SUCCESS on success
    */
   VXIpromptResult (*Play)(struct VXIpromptInterface  *pThis);
 
   /**
    * @name PlayFiller
    * @memo Queues and possibly starts the special play of a filler segment, 
    *       non-blocking
    * @doc
    * 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().
    *
    * @param 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.
    * @param src         [IN] URI or platform dependant path to the content;
    *                    NULL when specifying in-memory text.
    * @param 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.
    * @param properties  [IN] Properties to control the fetch, queue, and
    *                    play, as specified above. May be NULL.
    * @param 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.
    *
    * @return VXIprompt_RESULT_SUCCESS on success
    */
   VXIpromptResult (*PlayFiller)(struct VXIpromptInterface *pThis,
                                 const VXIchar             *type,
                                 const VXIchar             *src,
                                 const VXIchar             *text,
                                 const VXIMap              *properties,
                                 VXIlong                    minPlayMsec);
 
   /**
    * @name Prefetch
    * @memo Prefetch a segment, non-blocking
    * @doc
    * 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).
    *
    * @param 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.
    * @param src         [IN] URI or platform dependant path to the content,
    *                    pass NULL when specifying in-memory text
    * @param 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 sayas class playback is
    *                    determined by each class implementation. 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 also may support other formats.
    * @param properties  [IN] Properties to control the fetch, queue, and
    *                    play, as specified above. May be NULL.
    *
    * @return VXIprompt_RESULT_SUCCESS on success
    */
   VXIpromptResult (*Prefetch)(struct VXIpromptInterface *pThis,
                               const VXIchar             *type,
                               const VXIchar             *src,
                               const VXIchar             *text,
                               const VXIMap              *properties);
 
   /**
    * @name Queue
    * @memo Queue a segment for playing, blocking
    * @doc
    * The segment does not start playing until the Play() method is
    * called. This call blocks until the prompt's data is retrieved
    * (for streaming plays until the data stream starts arriving) so
    * that the caller can be assured the segment is available for
    * playback (important for supporting play with fallback).
    *
    * @param 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.
    * @param content     [IN] URI or platform dependant path to the content or
    *                    NULL when specifying in-memory text.
    * @param 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 sayas class playback is
    *                    determined by each class implementation. 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.
    * @param properties  [IN] Properties to control the fetch, queue, and
    *                    play, as specified above. May be NULL.
    *
    * @return VXIprompt_RESULT_SUCCESS on success
    */
   VXIpromptResult (*Queue)(struct VXIpromptInterface *pThis,
                            const VXIchar             *type,
                            const VXIchar             *content,
                            const VXIchar             *text,
                            const VXIMap              *properties);
 
   /**
    * @name Wait
    * @memo Wait until all played segments finish playing, blocking
    * @doc
    * Note that this stops the current PlayFiller() operation although
    * possibly after some delay, see PlayFiller() for more information.
    *
    * @param 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.
    *
    * @return VXIprompt_RESULT_SUCCESS on success
    */
   VXIpromptResult (*Wait)(struct VXIpromptInterface *pThis,
                           VXIpromptResult           *playResult);
 } VXIpromptInterface;
 
 /*@}*/
 
 #ifdef __cplusplus
 }
 #endif
 
 #include "VXIheaderSuffix.h"
 
 #endif  /* include guard */