HRESULT Speak(PTSTR pszSpeak, DWORD dwFlags, PTSTR pszTags);
Starts playing the specified text.
· Returns NOERROR if successful, or one of these error values:
VTXTERR_INVALIDMODE
VTXTERR_INVALIDPARAM
VTXTERR_NOTENABLED
VTXTERR_OUTOFMEM
VTXTERR_QUEUEFULL
VTXTERR_WAVEDEVICEBUSY
pszSpeak
[in] Address of a buffer that contains the text to speak. An application can free or modify the buffer as soon as Speak returns. The string pointed to by this parameter must not contain text-to-speech control tags, but is affected by tags in pszTags.
dwFlags
[in] Flags that indicate the type and priority of the text. This parameter is a combination of one type flag and one priority flag.
The type flag can be one of these values:
Value | Meaning |
VTXTST_COMMAND | An instruction to the user, such as "Insert the disk." |
VTXTST_NUMBERS | Text that is numeric and that should be read in numeric style. |
VTXTST_QUESTION | A question, such as "Do you want to save the file?" |
VTXTST_READING | Text that is being read from a document, such as an email message. |
VTXTST_SPREADSHEET | Text that is being read from a spreadsheet, such as columns of numbers. |
VTXTST_STATEMENT | A neutral, informative statement, such as "You have new messages." This is the default type of speech. |
VTXTST_WARNING | A warning, such as "Your printer is out of paper." |
The priority flag can be one of these values:
Value | Meaning |
VTXTSP_HIGH | Play the text as soon as possible, after text that is currently being spoken but before any other text in the playback queue. |
VTXTSP_NORMAL | Add the text to the end of the playback queue. This is the default priority. |
VTXTSP_VERYHIGH | Play the text immediately, interrupting text that is currently being spoken, if any. The interrupted text resumes playing as soon as the very high priority text is finished, although the interrupted text may not be correctly synchronized. |
For example, a text-to-speech engine speaks a warning with the highest priority if this parameter is set with VTXTST_WARNING and VTXTSP_VERYHIGH. Setting this parameter to zero is the same as specifying VTXTST_STATEMENT and VTXTSP_NORMAL.
pszTags
[in] Address of a buffer that contains text-to-speech control tags to change the voice, language, or context of the text specified by pszSpeak, or NULL to use the default settings for the text-to-speech voice. For more information about control tags, see Appendix A, "Text-to-Speech Control Tags."
If an application calls Speak when other text is being played, the specified text is added to the end of the playback queue, unless the application specifies a higher priority in dwFlags.
Calling Speak affects all applications using voice text on the site, because all applications share the same playback queue.
The type of speech specified by dwFlags is communicated to the text-to-speech engine though control tags. Support of most control tags is optional; the engine ignores unsupported tags.