Microsoft DirectX 8.0

IMediaControl Interface

This interface provides methods for controlling the flow of data through the filter graph. It includes methods for running, pausing, and stopping the graph. The filter graph manager implements this interface. For more information on filter graph states, see Data Flow in the Filter Graph.

IMediaControl also provides Automation-compatible methods for building graphs. Applications written in Microsoft® Visual Basic® can use these methods to construct filter graphs or retrieve information about the graph. Applications written in C or C++ should use the methods in IGraphBuilder and IFilterGraph2 instead, because they are more efficient.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IDispatch methodsDescription
GetTypeInfoCount Determines whether type information is available for this dispinterface.
GetTypeInfo Retrieves the type information for this dispinterface if GetTypeInfoCount returns successfully.
GetIDsOfNames Converts text names of properties and methods, including arguments, to their corresponding dispatch identifiers (DISPIDs).
Invoke Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IMediaControl methodsDescription
RunRuns all the filters in the filter graph.
PausePauses all filters in the filter graph.
StopStops all the filters in the filter graph.
StopWhenReadyPauses the filter graph, allowing filters to queue data, and then stops the filter graph.
GetStateRetrieves the state of the filter graph.
RenderFileUsed by Visual Basic applications to build a filter graph that renders the specified file.
AddSourceFilterUsed by Visual Basic applications to add to the graph the source filter that can read the given file name.
get_FilterCollectionUsed by Visual Basic applications to build a filter graph that renders the specified file to retrieve a collection of IFilterInfo interfaces that represent the filters in the graph.
get_RegFilterCollectionUsed by Visual Basic applications to retrieve a collection of IRegFilterInfo interfaces that represent the registered filters available on the local system.

IMediaControl::AddSourceFilter

IMediaControl Interface

Used by Visual Basic applications to add to the graph the source filter that can read the given file name.

Syntax

HRESULT AddSourceFilter(
    BSTR strFilename,
    IDispatch **ppUnk
);

Parameters

strFilename
[in] Name of the file containing the source video.
ppUnk
[out] Address of a pointer that will receive the IFilterInfo interface on the filter.

Return Values

Returns an HRESULT value. Possible values include the following.

Success.
S_OK
E_OUTOFMEMORYInsufficient memory.
VFW_E_CANNOT_LOAD_SOURCE_FILTERThe source filter for this file could not be loaded.
VFW_E_NOT_FOUNDAn object or name was not found.
VFW_E_UNKNOWN_FILE_TYPEThe media type of this file is not recognized.

Remarks

This method is primarily for use by Automation clients because it returns an IDispatch interface pointer. C and C++ applications should call the IGraphBuilder::AddSourceFilter method to perform this operation for maximum efficiency.

IMediaControl::get_FilterCollection

IMediaControl Interface

Used by Visual Basic applications to build a filter graph that renders the specified file to retrieve a collection of IFilterInfo interfaces that represent the filters in the graph.

Syntax

HRESULT get_FilterCollection(
    IDispatch **ppUnk
);

Parameters

ppUnk
[out, retval] Address of a pointer that will receive the IAMCollection interface on a collection of IFilterInfo objects.

Return Values

Returns an HRESULT value. Possible values include the following.

Success.
S_OK
E_OUTOFMEMORYInsufficient memory.

Remarks

This method is primarily for use by Automation clients because it returns an IDispatch interface pointer. C and C++ applications should call the IFilterGraph::EnumFilters method to perform this operation for maximum efficiency.

IMediaControl::get_RegFilterCollection

IMediaControl Interface

Used by Visual Basic applications to retrieve a collection of IRegFilterInfo interfaces that represent the registered filters available on the local system.

Syntax

HRESULT get_RegFilterCollection(
    IDispatch **ppUnk
);

Parameters

ppUnk
[out, retval] Address of a pointer that will receive the IDispatch interface of the IAMCollection object.

Return Values

Returns an HRESULT value. Possible values include the following.

Success.
S_OK
E_OUTOFMEMORYInsufficient memory.

Remarks

This method is primarily for use by Automation clients because it returns an IDispatch interface pointer. C and C++ applications should call the IFilterMapper::EnumMatchingFilters method to perform this operation for maximum efficiency.

IMediaControl::GetState

IMediaControl Interface

Retrieves the state of the filter graph—paused, running, or stopped.

State transitions are not necessarily synchronous. Therefore, when you call this method, the filter graph might be in transition to a new state. In that case, the method blocks until the transition completes or until the specified time-out elapses.

Syntax

HRESULT GetState(
    LONG msTimeout,
    OAFilterState *pfs
);

Parameters

msTimeout
[in] Duration of the time-out, in milliseconds, or INFINITE to specify an infinite time-out.
pfs
[out] Pointer to a variable that receives a member of the FILTER_STATE enumeration.

Return Values

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
VFW_S_STATE_INTERMEDIATEThe filter graph is still in transition to the indicated state.
VFW_S_CANT_CUEThe filter graph is paused, but cannot cue data.
E_FAILFailure.

Remarks

Applications can use this method to determine whether playback has started after a call to IMediaControl::Run. Generally, applications should have their own mechanism for tracking which state they have put the filter graph into. Applications typically use the current state to determine which user interface controls are enabled or disabled. For example, once the graph goes into the running state, the application might disable a "Play" button and enable "Stop" and "Pause" buttons.

If the filter graph is in a transition to a new state, the returned state is the new state, not the previous state.

This method returns an error if there is a call on another thread to change the state while this method is blocked.

Avoid specifying a time-out of INFINITE, because threads cannot process messages while waiting in GetState. If you call GetState from the thread that processes Windows messages, specify small wait times on the call in order to remain responsive to user input. This is especially important when the source is streaming over a network or from the Internet because state transitions in these environments can take significantly more time to complete.

For more information about filter graph states, see Data Flow in the Filter Graph.

IMediaControl::Pause

IMediaControl Interface

Pauses all the filters in the filter graph.

Pausing the filter graph cues the graph for immediate rendering when the graph is next run. While the graph is paused, filters process data but do not render it. Data is pushed through the graph and processed by transform filters as far as buffering permits, but renderer filters do not render the data. However, video renderers display a static poster frame of the first sample.

Syntax

HRESULT Pause(void);

Return Values

Returns an HRESULT value. Possible values include the following.

S_FALSEThe graph paused successfully, but some filters have not completed the state transition.
S_OKAll filters in the graph completed the transition to a paused state.

Remarks

If the method returns S_FALSE, call the GetState method to wait for the state transition to complete, or to check if the transition has completed.

If the method fails, it stops the graph before returning.

IMediaControl::RenderFile

IMediaControl Interface

Used by Visual Basic applications to build a filter graph that renders the specified file.

Syntax

HRESULT RenderFile(
    BSTR strFilename
);

Parameters

strFilename
Name of the file to render.

Return Values

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
VFW_S_AUDIO_NOT_RENDEREDCannot play the audio stream: could not find a suitable renderer.
VFW_S_DUPLICATE_NAMEAn attempt to add a filter with a duplicate name succeeded with a modified name.
VFW_S_PARTIAL_RENDERSome streams in this movie are in an unsupported format.
VFW_S_VIDEO_NOT_RENDEREDCannot play the video stream: could not find a suitable renderer.
E_ABORT Operation aborted.
VFW_E_CANNOT_CONNECTNo combination of intermediate filters could be found to make the connection.
VFW_E_CANNOT_LOAD_SOURCE_FILTERThe source filter for this file could not be loaded.
VFW_E_CANNOT_RENDERNo combination of filters could be found to render the stream.
VFW_E_INVALID_FILE_FORMATThe file format is invalid.
VFW_E_NOT_FOUNDAn object or name was not found.
VFW_E_NOT_IN_GRAPHCannot perform the requested function on an object that is not in the filter graph.
VFW_E_UNKNOWN_FILE_TYPEThe media type of this file is not recognized.
VFW_E_UNSUPPORTED_STREAMCannot play the file: the format is not supported.

Remarks

This method allows an application to pass the name of a media file that it wants rendered to the filter graph manager. The filter graph manager will build a graph of the filters needed to play back this file. This method is Automation-compatible and is equivalent to the IGraphBuilder::RenderFile method, which should be used by C and C++ applications.

IMediaControl::Run

IMediaControl Interface

Runs all the filters in the filter graph. While the graph is running, data moves through the graph and is rendered.

Syntax

HRESULT Run(void);

Return Values

Returns an HRESULT value. Possible values include the following.

S_FALSEThe graph is preparing to run, but some filters have not completed the transition to a running state.
S_OKAll 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 IMediaControl::Pause or IMediaControl::Stop method is called. When playback reaches the end of the stream, the graph continues to run, although 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 IMediaEvent and EC_COMPLETE.

This method does not seek to the beginning of the stream. 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 reached end-of-stream, there is no effect. To seek the graph, use the IMediaSeeking interface.

If the return value is S_FALSE, you can wait for the transition to complete by calling the GetState method. If the method fails, some filters might be in a running state. In a multistream graph, entire streams might be playing successfully. The application must determine whether to stop the graph.

IMediaControl::Stop

IMediaControl Interface

Stops all the filters in the graph.

Syntax

HRESULT Stop(void);

Return Values

Returns S_OK if successful, or an HRESULT value that indicates the cause of the error.

Remarks

If the graph is running, this method pauses the graph before stopping it. While paused, video renderers can copy the current frame to display as a poster frame.

This method does not seek to the beginning of the stream. If you call this method and then call the IMediaControl::Run method, playback resumes from the stopped position. To seek, use the IMediaSeeking interface.

The filter graph manager pauses all the filters in the graph, and then calls the IMediaFilter::Stop method on all filters, without waiting for the pause operations to complete. Therefore, some filters might have their Stop method called before they complete their pause operation. If you develop a custom rendering filter, you might need to handle this case by pausing the filter if it receives a stop command while in a running state. However, most filters do not need to take any special action in this regard.

See Also

StopWhenReady

IMediaControl::StopWhenReady

IMediaControl Interface

Pauses the filter graph, allowing filters to queue data, and then stops the filter graph.

Syntax

HRESULT StopWhenReady(void);

Return Values

Returns S_OK if successful, or an HRESULT value that indicates the cause of the error.

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