## IMediaControl Interface

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. The CMediaControl base class implements this interface and handles the IDispatch interface.

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.

###

IMediaControl::AddSourceFilter

IMediaControl Interface

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
);

##### Parameters

strFilename
  [in] Name of the file containing the source video.
ppUnk
  [out] Pointer to the IFilterInfo interface on the filter.

##### Return Values

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

IMediaControl Interface

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
);

##### Parameters

ppUnk
  [out, retval] The IAMCollection interface on a collection of IFilterInfo objects.

##### Return Values

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

IMediaControl Interface

Retrieves a collection of IRegFilterInfo interfaces representing the filters available in the registry.

HRESULT get_RegFilterCollection(
IDispatch **ppUnk
);

##### Parameters

ppUnk
  [out, retval] IDispatch interface of the IAMCollection object.

##### Return Values

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

IMediaControl Interface

Retrieves the state of the filter graph.

HRESULT GetState(
LONG msTimeout,
OAFilterState* pfs
);

##### Parameters

msTimeout
  [in] Duration of the time-out, in milliseconds.
pfs
  [out] Holds the returned state of the filter graph.

##### Return Values

Returns VFW_S_STATE_INTERMEDIATE if the state transition is not complete, or S_OK if it completed successfully.

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

IMediaControl Interface

Pauses all the filters in the filter graph.

HRESULT Pause( );

##### Return Values

Returns an HRESULT value.

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

IMediaControl Interface

Adds and connects filters needed to play the specified file.

HRESULT RenderFile(
BSTR strFilename
);

##### Parameters

strFilename
  Name of the file to render.

##### Return Values

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

IMediaControl Interface

Switches the entire filter graph into a running state.

HRESULT Run( );

##### Return Values

Returns an HRESULT value.

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

IMediaControl Interface

Switches all filters in the filter graph to a stopped state.

HRESULT Stop( );

##### Return Values

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

IMediaControl Interface

Waits for an operation such as Pause to complete, allowing filters to queue up data, then stops the filter graph.

HRESULT StopWhenReady( );

##### Return Values

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.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.