IAgentCharacterEx::Listen

HRESULT Listen(
   long bListen  // listening mode flag
);

Turns Listening mode (speech recognition input) on or off.

• Returns S_OK to indicate the operation was successful.

bListen

Listening mode flag. If this parameter is True, the Listening mode is turned on; if False, Listening mode is turned off.

Setting this method to True enables the Listening mode (turns on speech recognition) for a fixed period of time. While you cannot set the value of the time-out, you can turn off Listening mode before the time-out expires. In addition, if the Listening mode is already on because you (or another client) successfully set the method to True before the time-out expires, the method succeeds and resets the time-out. However, if Listening mode is already on because the user is pressing the Listening key, the method succeeds, but the time-out is ignored and the Listening mode ends based on the user's interaction with the Listening key.

This method will succeed only when called by the input-active client. Therefore, the method will fail if your client is not the active client of the topmost character. The method will also fail if you attempt to set the method to False and the user is pressing the Listening key. It can also fail if there is no compatible speech engine available that matches the character's language ID setting or the user has disabled speech input using the Microsoft Agent property sheet. However, the method will not fail if the audio device is busy.

When you successfully set this method to True, the server triggers the IAgentNotifySinkEx::ListeningState event. The server also sends IAgentNotifySinkEx::ListeningState when the Listening mode time-out completes or when you set IAgentCharacterEx::Listen to False.

This method does not automatically call IAgentCharacter::StopAll and play a Listening state animation of the character as occurs when the user presses the Listening key. This enables you to use the IAgentNotifySinkEx::ListeningStaate event to determine whether you wish to stop the current animation and play your own appropriate animation. However, once a user utterance is detected, the server automatically calls IAgentCharacter::StopAll and plays a Hearing state animation.

See Also

IAgentNotifySinkEx::ListeningState, IAgentSpeechInputProperties::GetEnabled