The filter graph exposes the IMediaControl interface to allow applications to control the streaming of media through the filters in the graph. The interface provides methods for running, pausing, and stopping the streaming of data. It also provides applications with a simple method of building graphs to play back media files.
When to Implement
This interface is implemented by the filter graph manager. Implement this only if you are writing a plug-in distributor that needs to export the control methods.
When to Use
Use this interface from any application that wants to control the playing of media through Microsoft® DirectShow™ filter graphs. Applications can also use it to enumerate the filters in the filter graph and all the filters in the registry, to add a source filter to the filter graph, and to instruct the filter graph manager to build a filter graph capable of rendering the media type in a file.
Methods in Vtable Order
| IUnknown methods | Description |
| QueryInterface | Returns pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| IDispatch methods | Description |
| GetTypeInfoCount | Determines whether there is type information available for this dispinterface. |
| GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully. |
| GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs. |
| Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters. |
| IMediaControl methods | Description |
| Run | Switches the entire filter graph into running mode. |
| Pause | Pauses all filters in the filter graph. |
| Stop | Switches all filters in the filter graph to a stopped state. |
| StopWhenReady | Waits for an operation such as Pause to complete, allowing filters to queue up data, then stops the filter graph. |
| GetState | Retrieves the state of the filter graph. |
| RenderFile | Adds and connects filters needed to play the specified file. |
| AddSourceFilter | Adds to the graph the source filter that can read the given file name, and returns an IDispatch interface pointer representing the filter object. |
| get_FilterCollection | Retrieves a collection of IFilterInfo interfaces representing the filters in the graph. |
| get_RegFilterCollection | Retrieves a collection of IRegFilterInfo interfaces representing the filters available in the registry. |
Adds to the graph the source filter that can read the given file name, and returns an IDispatch interface pointer representing the filter.
HRESULT AddSourceFilter(
BSTR strFilename,
IDispatch **ppUnk
);
Returns an HRESULT value.
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.
Retrieves a collection of IFilterInfo interfaces representing the filters in the graph and returns IDispatch for an object that supports the IAMCollection interface.
HRESULT get_FilterCollection(
IDispatch **ppUnk
);
Returns an HRESULT value.
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.
Retrieves a collection of IRegFilterInfo interfaces representing the filters available in the registry.
HRESULT get_RegFilterCollection(
IDispatch **ppUnk
);
Returns an HRESULT value.
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.
Retrieves the state of the filter graph.
HRESULT GetState(
LONG msTimeout,
OAFilterState* pfs
);
Returns VFW_S_STATE_INTERMEDIATE if the state transition is not complete, or S_OK if it completed successfully.
Not all state transitions are synchronous. For example, even though the IMediaControl::Pause method returns immediately, the filter graph typically does not complete the transition into paused mode until data is ready at the renderer. This method will not return S_OK until the state transition has been completed.
If you specify a nonzero time-out, the method waits up to that number of milliseconds for the filter graph to leave the intermediate state. If the time-out expires before the state transition is complete, the return code will be VFW_S_STATE_INTERMEDIATE, and the returned state will be the state into which the graph is transitioning (either the State_Stopped, State_Paused, or State_Running members of the FILTER_STATE structure).
This method will return 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. Threads cannot process messages while waiting in GetState. If you call GetState from the thread that processes Windows® messages, specify only small wait times on the call in order to remain responsive to user input. This is most important when streaming data from a source such as the Internet, because state transitions can take significantly more time to complete.
If you want to pause a filter graph completely before stopping it, call IMediaControl::Pause, and then IMediaControl::StopWhenReady (instead of calling GetState with an INFINITE time-out, and then IMediaControl::Stop).
Although pfs is declared as a pointer to an OAFilterState value in IMediaControl::GetState, DirectShow implements it as a pointer to a FILTER_STATE value in CBaseFilter::GetState and its derivatives. Since both OAFilterState and FILTER_STATE resolve to LONG values, this does not cause an error.
Pauses all the filters in the filter graph.
HRESULT Pause( );
Returns an HRESULT value.
In the paused state, filters process data but do not render it. Data is pushed down the filter graph and is processed by transform filters as far as buffering permits. No data is rendered (except that media types capable of being rendered statically, such as video, have a static, poster frame rendered in paused mode). Therefore, putting a filter graph into a paused state cues the graph for immediate rendering when put into a running state.
Adds and connects filters needed to play the specified file.
HRESULT RenderFile(
BSTR strFilename
);
Returns an HRESULT value.
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 IGraphBuilder::RenderFile, which should be used by C and C++ applications.
Switches the entire filter graph into a running state.
HRESULT Run( );
Returns an HRESULT value.
In a running state, data is pushed down the filter graph and rendered. The graph remains in a running state until it is stopped by the IMediaControl::Pause or IMediaControl::Stop method. The graph remains in a running state even after notifying the application of completion (that is, the EC_COMPLETE notification is sent to the application). This allows the application to determine whether to pause or stop after completion.
If the filter graph is in the stopped state, this method first pauses the graph before running.
If an error value is returned, some filters within the graph might have successfully entered the running state. In a multistream graph, entire streams might be playing successfully. The application must determine whether to stop running or not.
Switches all filters in the filter graph to a stopped state.
HRESULT Stop( );
Returns an HRESULT value.
In this mode, filters release resources and no data is processed. If the filters are in a running state, this method pauses them before stopping them. This allows video renderers to make a copy of the current frame for poster frame display while stopped.
Waits for an operation such as Pause to complete, allowing filters to queue up data, then stops the filter graph.
HRESULT StopWhenReady( );
Returns an HRESULT value.
Changing the current position when stopped will not normally repaint the video window with the new position. Applications will need to enter Pause mode to do this. Calling StopWhenReady instead of simply calling Stop after this pause ensures that the graph is fully paused, and that data has arrived at the video renderer and has been displayed before the graph is stopped.
This method is run asynchronously so that the application regains control immediately and can respond to user input. Use this method rather than calling IMediaControl::GetState with an INFINITE time-out, followed by IMediaControl::Stop.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.