ISpRecoContext::Bookmark
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
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.
Syntax
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 Value
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
| Header | sapi.h, sapi.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |