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.

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.

See Also

• Error and Success Codes
• IMediaControl Interface