ISpRecoContext::Bookmark

Article
06/30/2006

This method sets a bookmark within the current recognition stream. When the engine reaches the specified stream position, a bookmark event is added to the event queue.

HRESULT Bookmark(
  SPBOOKMARKOPTIONS Options,
  ULONGLONG ullStreamPosition,
  LPARAM lParamEvent
);

Parameters

Options
[in] Options associated with the bookmark. Possible values are defined for the SPBOOKMARKOPTIONS enumeration.

ullStreamPosition
[in] Position of the bookmark in the stream. See Remarks section.

SP_STREAMPOS_ASAP	Bookmark event will occur when the SR engine reaches a synchronization point.
SP_STREAMPOS_REALTIME	Bookmark event will occur when the SR engine reaches the current audio device position.
Specific stream position value	Bookmark event will occur when the SR engine reaches the specified stream position value.

lParamEvent
[in] The value of the lparam member in the SPEVENT structure defining the bookmark event. This can be any value the application wants retrieved with the bookmark event (for example, unique identifier, data pointer, NULL, and so on).

Return Values

The following table shows the possible return values.

Value	Description
S_OK	Function completed successfully.
E_INVALIDARG	Options has a bad value.
FAILED(hr)	Appropriate error message.

Remarks

If Options is set to SPBO_PAUSE, then the SPEVENT wParam member will be set to SPREF_AutoPause.

An application that wants to display a recognition progress/latency meter might use ISpRecoContext::Bookmark with the stream position SP_STREAMPOS_REALTIME, and update the UI when each bookmark is received. See also ISpRecognizer::GetStatus.

An application that wants to pause the SR engine to perform specific processing ("auto-pause" bookmark) might use ISpRecoContext::Bookmark with the stream position SPBO_PAUSE SP_STREAMPOS_ASAP. Use of this setting pauses the SR engine automatically and asynchronously (for the application). The application should call ISpRecoContext::Resume to resume operation of the SR engine. See also ISpRecoGrammar::SetRuleState regarding auto-pause rules.

Example

The following code snippet illustrates the use of this method with an auto-pause bookmark.

HRESULT hr = S_OK;
// setup the recognition context and grammar
// ...
// start listening for recognitions
hr = cpRecoGrammar->SetRuleState( MY_RULE, NULL, SPRS_ACTIVE );
// Check hr
hr = cpRecoContext->Bookmark( SPBO_PAUSE, SP_STREAMPOS_ASAP, NULL );
// get the bookmark event in a CSpEvent object
// ...
// assert that the recognition context paused after the "auto-pause" bookmark
was sent
SPDBG_ASSERT(spEvent.IsPaused());
// Because the context was paused from the "auto-pause" rule, it must now be
reactivated to recognize the second rule
hr = cpRecoContext->Resume( NULL );
// Check hr

Requirements

OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.