IMediaControl Interface
The filter graph exposes the IMediaControl interface to enable 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.
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. The CMediaControl base class implements this interface and handles the IDispatch interface.
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 Retrieves 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.
IMediaControl::AddSourceFilter
Adds to the graph the source filter that can read the given file name, and returns an IDispatch interface pointer representing the filter.
Syntax
HRESULT AddSourceFilter(
BSTR strFilename,
IDispatch **ppUnk
);
Parameters
- strFilename
- [in] Name of the file containing the source video.
- ppUnk
- [out] Address of a pointer to the IFilterInfo interface on the filter.
Return Value
Returns an HRESULT value.
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
Retrieves a collection of IFilterInfo interfaces representing the filters in the graph and returns IDispatch for an object that supports the IAMCollection interface.
Syntax
HRESULT get_FilterCollection(
IDispatch **ppUnk
);
Parameters
- ppUnk
- [out, retval] Address of a pointer to the IAMCollection interface on a collection of IFilterInfo objects.
Return Value
Returns an HRESULT value.
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
Retrieves a collection of IRegFilterInfo interfaces representing the filters available in the registry.
Syntax
HRESULT get_RegFilterCollection(
IDispatch **ppUnk
);
Parameters
- ppUnk
- [out, retval] Address of a pointer to the IDispatch interface of the IAMCollection object.
Return Value
Returns an HRESULT value.
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
Retrieves the state of the filter graph.
Syntax
HRESULT GetState(
LONG msTimeout,
OAFilterState *pfs
);
Parameters
- msTimeout
- [in] Duration of the time-out, in milliseconds.
- pfs
- [out] Pointer to the returned state of the filter graph.
Return Value
Returns VFW_S_STATE_INTERMEDIATE if the state transition is not complete, or S_OK if it completed successfully. It can also return VFW_S_CANT_CUE if the state is paused, but the source filter does not push data during the paused state (only pushes during the run state). An example of this is a live video capture filter.
Remarks
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.
IMediaControl::Pause
Pauses all the filters in the filter graph.
Syntax
HRESULT Pause(void);
Return Value
Returns S_OK if the graph is actually paused.
Returns S_FALSE if the graph is in paused state but some filters have not completed the transition to pause. Call GetState to wait for the transition to the paused state to complete or to check if the transition has completed. If the method returns S_FALSE, subsequent calls to GetState will return a value of State_Paused when the graph is paused. If the transition to paused is not complete GetState can return a return code of VFW_S_STATE_INTERMEDIATE.
Returns an HRESULT error code if the graph could not transition to paused state and is now stopped.
Remarks
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.
IMediaControl::RenderFile
Adds and connects filters needed to play the specified file.
Syntax
HRESULT RenderFile(
BSTR strFilename
);
Parameters
- strFilename
- Name of the file to render.
Return Value
Returns an HRESULT value.
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 IGraphBuilder::RenderFile, which should be used by C and C++ applications.
IMediaControl::Run
Switches the entire filter graph into a running state.
Syntax
HRESULT Run(void);
Return Value
Returns S_OK if the graph is actually running.
Returns S_FALSE if the graph is preparing to run (the graph will run automatically when it's ready). Call GetState to wait for the transition to the running state to complete or to check if the transition has completed. If the method returns S_FALSE, subsequent calls to GetState will return a value of State_Running when the graph is actually running. If the transition to the running state is not complete GetState can return a return code of VFW_S_STATE_INTERMEDIATE.
Returns an HRESULT error code if the graph could not run and is now stopped.
Remarks
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.
IMediaControl::Stop
Switches all filters in the filter graph to a stopped state.
Syntax
HRESULT Stop(void);
Return Value
Returns an HRESULT value.
Remarks
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.
IMediaControl::StopWhenReady
Waits for an operation such as Pause to complete, allowing filters to queue up data, then stops the filter graph.
Syntax
HRESULT StopWhenReady(void);
Return Value
Returns an HRESULT value.
Remarks
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.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.