## IMediaControl Object

The filter graph exposes the IMediaControl object 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 that builds graphs to play back media files.

Properties

Name | Description
FilterCollection | Retrieves a collection of IFilterInfo objects representing the current filters in the graph.
RegFilterCollection | Retrieves a collection of IRegFilterInfo objects representing the filters available in the registry.

Methods

Name | Description
AddSourceFilter | Adds to the graph the source filter that can read the given file name.
GetState | Retrieves the state of the filter graph.
Pause | Pauses all filters in the filter graph.
RenderFile | Adds and connects all filters needed to play the specified file.
Run | Switches the entire filter graph into run mode.
Stop | Switches all filters in the filter graph to a stopped state.

###

AddSourceFilter Method (IMediaControl Object)

IMediaControl Object

Adds the source filter that can read the given file name to the graph and returns the created IFilterInfo object.

objMediaControl.AddSourceFilter string, objFilterInfo

##### Parts

objMediaControl
  Object expression that evaluates to an IMediaControl object.
string
  Name of the file containing the source media.
objFilterInfo
  IFilterInfo object; the source filter created for the specified source file.

###

FilterCollection Property (IMediaControl Object)

IMediaControl Object

Retrieves a collection of IFilterInfo objects representing the filters in the graph. Returns an IAMCollection object.

Set objCollection = objMediaControl.FilterCollection

##### Parts

objCollection
  IAMCollection object that represents the collection of filters currently present in the filter graph.
objMediaControl
  Object expression that evaluates to an IMediaControl object.

###

GetState Method (IMediaControl Object)

IMediaControl Object

Returns a Long integer indicating the current state value.

objMediaControl.GetState msTimeout, State

##### Parts

objMediaControl
  Object expression that evaluates to an IMediaControl object.
msTimeout
  Duration of the time-out, in milliseconds.
State
  Long value that will contain the current state. This argument will be one of the following:

  Value | Description
  State_Paused | The media source is paused.
  State_Running | The media source is running.
  State_Stopped | The media source is stopped.

##### Return Values

Returns run-time error 567 if the state transition is not complete, or 0 if it completed successfully.

##### Remarks

Not all state transitions are synchronous. For example, even though the Pause method returns immediately, the graph typically does not complete the transition into paused mode until data is ready at the renderer. This method will not return zero 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 graph to leave the intermediate state. If the time-out expires before the state transition is complete, the return code will be 567, and the returned state will be the state into which the graph is transitioning (either State_Stopped, State_Paused, or State_Running).

###

RegFilterCollection Property (IMediaControl Object)

IMediaControl Object

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

Set objCollection = objMediaControl.RegFilterCollection

##### Parts

objCollection
  IAMCollection object that contains IRegFilterInfo objects.
objMediaControl
  Object expression that evaluates to an IMediaControl object.

##### Return Values

Returns an IAMCollection object.

###

Pause Method (IMediaControl Object)

IMediaControl Object

Pauses all the filters in the filter graph.

objMediaControl.Pause

##### Parts

objMediaControl
  Object expression that evaluates to an IMediaControl object.

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

###

RenderFile Method (IMediaControl Object)

IMediaControl Object

Adds and connects filters needed to play the specified file.

objMediaControl.RenderFile string

##### Parts

objMediaControl
  Object expression that evaluates to an IMediaControl object.
string
  Name of the file to render.

##### 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 that are needed to play back this file.

###

Run Method (IMediaControl Object)

IMediaControl Object

Switches the entire filter graph into a running state.

objMediaControl.Run

##### Parts

objMediaControl
  Object expression that evaluates to an IMediaControl object.

##### Remarks

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 execution or not.

###

Stop Method (IMediaControl Object)

IMediaControl Object

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

objMediaControl.Stop

##### Parts

objMediaControl
  Object expression that evaluates to an IMediaControl object.

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

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