IMediaControl::StopWhenReady method (control.h)

The StopWhenReady method pauses the filter graph, allowing filters to queue data, and then stops the filter graph.

Syntax

HRESULT StopWhenReady();

Return value

Returns an HRESULT value. Possible values include the following.

Return code Description
S_OK
Success.
S_FALSE
The graph was still transitioning to the paused state when the method returned.

Remarks

This method is useful if you want to seek the filter graph while the graph is stopped. As long as the filter graph is stopped, changes in the current position do not repaint the video window with a new frame. Therefore, calling IMediaSeeking::SetPositions does not update the video window. To update the window after the seek operation, call StopWhenReady. This method transitions the graph to a paused state, waits for the pause operation to complete, and then transitions the graph back to stopped. The pause operation queues data in the graph, so that the video renderer receives and displays the new frame.

This method is asynchronous. It waits on a separate thread for the pause to complete. The calling thread does not block, which enables the application to respond to user input. When the method returns, the logical state of the graph is stopped, even before the pause operation completes. If you call the IMediaControl::GetState method at this point, it returns State_Stopped.

If the application issues another state-change command (such as pause, run, or seek) before the pause operation completes, the new command cancels the pending stop command. The pause operation completes, but the graph does not stop.

Requirements

   
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header control.h (include Dshow.h)
Library Strmiids.lib

See also

Error and Success Codes

IMediaControl Interface