ISpRecoContext::Bookmark

Microsoft Speech SDK

The Microsoft.com Speech website Microsoft Speech SDK SAPI 5.1

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 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, 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.

    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());

    // Since 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