Edit

IMediaControl::Run method (control.h)

  • Article

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The Run method runs all the filters in the filter graph. While the graph is running, data moves through the graph and is rendered.

Syntax

HRESULT Run();

Return value

Returns an HRESULT value. Possible values include the following.

Return code Description
S_FALSE
 The graph is preparing to run, but some filters have not completed the transition to a running state.
S_OK
 All filters in the graph completed the transition to a running state.

Remarks

If the filter graph is stopped, this method pauses the graph before running. If the graph is already running, the method returns S_OK but has no effect.

The graph runs until the application calls the IMediaControl::Pause or IMediaControl::Stop method. When playback reaches the end of the stream, the graph continues to run, but the filters do not stream any more data. At that point, the application can pause or stop the graph. For information about the end-of-stream event, see IMediaControl::Pause and EC_COMPLETE.

This method does not seek to the beginning of the stream. Therefore, if you run the graph, pause it, and then run it again, playback resumes from the paused position. If you run the graph after it has reached the end of the stream, nothing is rendered. To seek the graph, use the IMediaSeeking interface.

If method returns S_FALSE, it means that the method returned before all of the filters switched to a running state. The filters will complete the transition after the method returns. Optionally, you can wait for the transition to complete by calling the IMediaControl::GetState method with a timeout value. However, this is not required.

If the Run method returns an error code, it means that one or more filters failed to run. However, some filters might be in a running state. In a multistream graph, entire streams might be playing successfully. Typically the application would tear down the graph and report an error in this case.

Requirements

Requirement Value
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