IVoiceText::Register

This method registers an application to use voice text on a site.

Syntax

HRESULT Register( PTSTR pszSite, PTSTR pszApplication, PIVTXTNOTIFYSINK pNotifyInterface, IID IIDNotifyInterface, DWORD dwFlags, PVTSITEINFO pSiteInfo);

Parameters

pszSite

Ignored because there is only one site, “Local PC.”

pszApplication

[in] Pointer to a null-terminated string that identifies the application—for example, “Radio.” An application can use this information to display the source of text. This parameter must not be NULL.

pNotifyInterface

[in] Pointer to the notification interface through which the voice text object notifies the application about text-to-speech information. If this parameter is NULL, no notifications are sent. The interface identifier is specified by the IIDNotifyInterface parameter.

Because passing the pointer to the voice text object does not transfer ownership of the notification interface, the voice text object must call the AddRef method of the notification interface before returning from the call to Register. The voice text object must also call the Release method of the notification interface when it closes. The calling application must release any reference counts that the application holds on the notification interface after calling Register, unless the application needs the notification object to be valid when the voice text object releases notification interface.

IIDNotifyInterface

[in] Interface identifier of the interface used for notification. For Auto PC, this parameter must be IID_IVTxtNotifySinkW.

dwFlags

[in] Specifies whether the application is to receive all notifications. If this parameter is the VTXTF_ALLMESSAGES value, all notifications are sent to pNotifyInterface. The application can specify which notifications to receive by passing in the combination of the following values:

VTXTF_SPEAKDONE
VTXTF_SPEAKSTART

pSiteInfo

[in] Pointer to a VTSITEINFO structure that contains settings to apply to the site, such as the voice and talking speed. The settings are applied, even if the site is already open. If a VTSITEINFO structure is not specified, the voice text object uses the settings from the registry. If there are no registry settings, it uses the default settings, typically those for the computer.

Telephony applications pass this information to ensure that the proper settings are selected. Other applications set this parameter to NULL to leave the site settings unchanged.

Return Values

NOERROR: The method successfully registered an application to use voice text on a site.
VTXTERR_INVALIDPARAM: A parameter is invalid.
VTXTERR_OUTOFMEM: There is not enough memory.

Remarks

An application must call Register before it can call other methods in the IVoiceText interface.

An application cannot call Register a second time for the same voice text object. To change sites, the application must call the CoCreateInstance function to create a new voice text object for the desired site.