IVoiceCmd::Register

This method is called by an application to register to use voice commands on a site.

Syntax

HRESULT Register( PTSTR pszSite, PIVCMDNOTIFYSINK pNotifyInterface, IID IIDNotifyInterface, DWORD dwFlags, PVCSITEINFO pSiteInfo);

Parameters

pszSite

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

pNotifyInterface

[in] Pointer to the notification interface that receives notifications from the voice command object. The interface identifier is specified by IIDNotifyInterface. If this parameter is NULL, no notifications are sent.

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

IIDNotifyInterface

[in] Interface identifier (IID) that uniquely identifies the type of notification sink being passed to the voice command object. It must be IID_IVCmdNotifySinkW.

dwFlags

[in] Specifies whether the application is to receive all notifications. It is one of the following flags:

VCMDRF_ALLBUTVUMETER: Sends all but VUMeter notifications to pNotifyInterface.
VCMDRF_NOMESSAGES: Does not send notifications.
VCMDRF_CMDOTHER: Sends CommandOther notifications to pNotifyInterface.
VCMDRF_CMDSTART: Sends CommandStart notifications to pNotifyInterface.
VCMDRF_ATTRIBCHANGE: Sends AttribChanged notifications to pNotifyInterface.
VCMDRF_CMDRECOG: Sends CommandRecognize notifications to pNotifyInterface.

pSiteInfo

[in] Pointer to a VCSITEINFO structure that contains settings to apply to the site, such as the speaker, confidence threshold, and speech-recognition mode. The settings are applied even if the site is already open. If this parameter is NULL, the voice command 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 from previous values.

Return Values

NOERROR: The method successfully registered to use voice commands on a site.
E_INVALIDARG: The argument is invalid.
VCMDERR_CANTCREATEAUDIODEVICE: An audio source object cannot be created for speech recognition.
VCMDERR_CANTCREATESRENUM: A speech recognition enumerator object cannot be created.
VCMDERR_CANTSELECTENGINE: A speech recognition engine cannot be selected.
VCMDERR_CANTSETDEVICE: The device identifier cannot be set into the audio source object.
VCMDERR_INVALIDMODE: No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_NOFINDINTERFACE: The speech recognition enumerator interface does not have a Find interface.
VCMDERR_NOSITEINFO: Information to open this site is not available.
VCMDERR_OUTOFMEM: There is no more memory.
VCMDERR_SRFINDFAILED: The speech recognition object could not find an appropriate mode.
VCMDERR_VALUEOUTOFRANGE: The value is out of range.

Remarks

An application cannot call Register a second time for the same voice command object. If a voice command object is already registered, calling Register returns an error. To change sites, the application must call the CoCreateInstance function to create a new voice command object for the desired site.