ISpRecoContext::Bookmark (SAPI 5.3)

Article
04/21/2017

Microsoft Speech API 5.3

ISpRecoContext::Bookmark

ISpRecoContext::Bookmark 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] Indicates the option associated with the bookmark. Must be one of type SPBOOKMARKOPTIONS.
ullStreamPosition
[in] Specifies the stream position. This value may be anywhere in the stream and will send a Bookmark event when that position is reached. Additionally it may be any one of two special values: SP_STREAMPOS_ASAP or SP_STREAMPOS_REALTIME. See Remarks section for additional information.
lParamEvent
[in] The lparam for the SAPI bookmark event, and can be any value the application wants returned with the bookmark event (e.g., unique identifier, data pointer, NULL, etc.).

Return values

Value

S_OK

E_INVALIDARG

FAILED(hr)

Remarks

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

An application that wants to implement display a recognition progress/latency meter could use ISpRecoContext::Bookmark with 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 could use ISpRecoContext::Bookmark with SPBO_PAUSE SP_STREAMPOS_ASAP, which will pause the SR engine automatically, and asynchronously for the application. The application should call ISpRecoContext::Resume to resume the recognition process. See also ISpRecoGrammar::SetRuleState regarding "auto-pause" rules.

It is possible to bookmark a stream position before starting a stream. If there is currently no stream and the caller specifies an offset of zero (or as soon as possible) or SP_STREAMPOS_REALTIME (indicating immediately for a live audio device) the bookmark fires immediately. In both cases the application gets the bookmark as soon as the stream is created. Otherwise, the bookmark is delayed until the next stream reaches the specified offset.

Example

The following code snippet illustrates the use of ISpRecoContext::Bookmark with an "auto-pause" bookmark.

  
// Declare local identifiers:
HRESULT	                   hr = S_OK;
CComPtr<ISpRecoContext>    cpRecoContext;
CComPtr<ISpRecoGrammar>    cpRecoGrammar;

// Set up the recognition context and grammar.
// ...

// Start listening for recognitions.
hr = cpRecoGrammar->SetRuleState(NULL, NULL, SPRS_ACTIVE_WITH_AUTO_PAUSE);

if (SUCCEEDED(hr))
{
   // Pause recognition context.
   hr = cpRecoContext->Bookmark(SPBO_PAUSE, SP_STREAMPOS_ASAP, NULL);
}

// Get the bookmark event in a CSpEvent object.
// ...

// Assert that recognition context paused after the "auto-pause" bookmark was sent.
_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);

if (SUCCEEDED(hr))
{
   // Do stuff here.
}

Share via