IMediaControl::StopWhenReady

 
Microsoft DirectShow 9.0

IMediaControl::StopWhenReady

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

Syntax

  HRESULT StopWhenReady(void);

Return Values

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

Header: Declared in Control.h; include Dshow.h.

Library: Use Strmiids.lib.

See Also