IAMovie Interface

The IAMovie interface is a plug-in distributor (PID) interface that you could use as a replacement for all other interfaces on the filter graph manager. It wraps the most commonly used methods of IGraphBuilder, IMediaControl, IMediaEvent, and IMediaPosition by providing the same methods as these interfaces and simply calling these interfaces on the filter graph manager for the implementation. It also adds several unique methods that simplify instantiating and running a filter graph.

This interface is implemented by the PID sample application included in this SDK. It is not expected that anything else will implement this interface.

Applications use plug-in distributors. If this interface is implemented through the PID sample application, you can use the methods on this interface rather than the methods on the IGraphBuilder, IMediaControl, IMediaEvent, and IMediaPosition interfaces. You can also use specialized methods on this interface to render a filter graph and play it in one command, to enumerate filters in the filter graph that contain a specified interface, to enumerate all pins in the filter graph, and to perform other tasks.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IFilterGraph methods Description

AddFilter Adds a filter to the graph and gives it a name.
RemoveFilter Removes a filter from the graph.
Reconnect Breaks the existing pin connection and reconnects it to the same pin.
EnumFilters Provides an enumerator for all filters in the graph.
FindFilterByName Finds a filter that was added with a specified name.
ConnectDirect Connects the two IPin objects directly (without intervening filters).
Reconnect Breaks the existing pin connection and reconnects it to the same pin.
Disconnect Disconnects the pin, if connected.
SetDefaultSyncSource Sets the default synchronization source (a clock).

IAMovie methods Description

Connect Connects two IPin objects. If they will not connect directly, this method connects them with intervening transforms.
Render Adds a chain of filters to this output pin so as to render it.
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.
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 interface pointer to the filter object.
GetEventHandle Retrieves a handle to a manual-reset event that will be signaled.
GetEvent Retrieves the next notification event.
WaitForCompletion Waits until the graph's operation has completed.
CancelDefaultHandling Cancels any default handling of the specified event by the filter graph.
RestoreDefaultHandling Restores default handling for this event.
get_Duration Retrieves the total duration of the media stream.
put_CurrentPosition Sets the time that the media stream begins.
get_CurrentPosition Retrieves the current position in terms of the total length of the media stream.
get_StopTime Retrieves the position within the media stream at which playback should stop.
put_StopTime Sets the position within the media stream at which playback should stop.
get_PrerollTime Retrieves the time prior to the start position that the filter graph begins any nonrandom access device rolling.
put_PrerollTime Sets the time prior to the start position that the filter graph begins any nonrandom access device rolling.
put_Rate Sets the playback rate, relative to normal playback of the media stream.
get_Rate Retrieves the playback rate, relative to normal playback of the media stream.
RemoveAllFilters Removes all filters from the filter graph.
Play Plays the media in the current filter graph.
PlayFile Plays the media in a given file.
EnumFiltersByInterface Retrieves a list of filters supporting a specified interface.
EnumPins Retrieves a list of pins in the filter graph.
EnumPinsIn Retrieves a list of input pins in the filter graph.
EnumPinsOut Retrieves a list of output pins in the filter graph.
RenderAll Renders all output pins in the filter graph.
RenderNewFile Renders a filter graph for a file name, possibly reusing existing filters.
FreeEventParams Frees the resources associated with an event's parameters.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IFilterGraph methods	Description
AddFilter	Adds a filter to the graph and gives it a name.
RemoveFilter	Removes a filter from the graph.
Reconnect	Breaks the existing pin connection and reconnects it to the same pin.
EnumFilters	Provides an enumerator for all filters in the graph.
FindFilterByName	Finds a filter that was added with a specified name.
ConnectDirect	Connects the two IPin objects directly (without intervening filters).
Reconnect	Breaks the existing pin connection and reconnects it to the same pin.
Disconnect	Disconnects the pin, if connected.
SetDefaultSyncSource	Sets the default synchronization source (a clock).
IAMovie methods	Description
Connect	Connects two IPin objects. If they will not connect directly, this method connects them with intervening transforms.
Render	Adds a chain of filters to this output pin so as to render it.
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.
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 interface pointer to the filter object.
GetEventHandle	Retrieves a handle to a manual-reset event that will be signaled.
GetEvent	Retrieves the next notification event.
WaitForCompletion	Waits until the graph's operation has completed.
CancelDefaultHandling	Cancels any default handling of the specified event by the filter graph.
RestoreDefaultHandling	Restores default handling for this event.
get_Duration	Retrieves the total duration of the media stream.
put_CurrentPosition	Sets the time that the media stream begins.
get_CurrentPosition	Retrieves the current position in terms of the total length of the media stream.
get_StopTime	Retrieves the position within the media stream at which playback should stop.
put_StopTime	Sets the position within the media stream at which playback should stop.
get_PrerollTime	Retrieves the time prior to the start position that the filter graph begins any nonrandom access device rolling.
put_PrerollTime	Sets the time prior to the start position that the filter graph begins any nonrandom access device rolling.
put_Rate	Sets the playback rate, relative to normal playback of the media stream.
get_Rate	Retrieves the playback rate, relative to normal playback of the media stream.
RemoveAllFilters	Removes all filters from the filter graph.
Play	Plays the media in the current filter graph.
PlayFile	Plays the media in a given file.
EnumFiltersByInterface	Retrieves a list of filters supporting a specified interface.
EnumPins	Retrieves a list of pins in the filter graph.
EnumPinsIn	Retrieves a list of input pins in the filter graph.
EnumPinsOut	Retrieves a list of output pins in the filter graph.
RenderAll	Renders all output pins in the filter graph.
RenderNewFile	Renders a filter graph for a file name, possibly reusing existing filters.
FreeEventParams	Frees the resources associated with an event's parameters.

IAMovie::AddSourceFilter

IAMovie Interface

Adds a source filter to the filter graph for this file. The IGraphBuilder::RenderFile method adds the same source filter.

Syntax

HRESULT AddSourceFilter(

  LPCWSTR lpwstrFileName,

  IBaseFilter **ppFilter

  );

Parameters

lpwstrFileName
[in] Pointer to the file.
ppFilter
[out] Address of a pointer to an IBaseFilter interface on the filter that was added.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IGraphBuilder::AddSourceFilter method. The lpwstrFileName file name is used as the filter name when IGraphBuilder::AddSourceFilter is called.

IAMovie::CancelDefaultHandling

IAMovie Interface

Cancels any default handling by the filter graph of the specified event and ensures that it is passed to the application.

Syntax

HRESULT CancelDefaultHandling(
  long lEvCode
  );

Parameters

lEvCode
Event code for which to cancel default handling.

Return Value

Returns S_OK if successful, or S_FALSE if the event does not have any default handling.

Remarks

This method simply calls the IMediaEvent::CancelDefaultHandling method.

IAMovie::Connect

IAMovie Interface

Connects the two pins, using intermediates if necessary.

Syntax

HRESULT Connect(

  IPin *ppinOut,

  IPin *ppinIn

  );

Parameters

ppinOut
[in] Pointer to the output pin.
ppinIn
[in] Pointer to the input pin.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IGraphBuilder::Connect method.

IAMovie::EnumFiltersByInterface

IAMovie Interface

Retrieves a list of filters supporting a specified interface.

Syntax

HRESULT EnumFiltersByInterface(

  REFIID riid,

  IEnumFilters **ppEnum

  );

Parameters

riid
[in] REFIID of the interface qualifying the search.
ppEnum
[out] Address of a pointer to the IEnumFilters enumerator containing the matching filters.

Return Value

Returns an HRESULT value.

Remarks

This method retrieves an IEnumFilters enumerator containing a list of pointers to filters in the filter graph that support a specified interface. Note that the pointers in the list (as returned by IEnumFilters::Next) actually point to the specified riid interface on each filter rather than to the IBaseFilter interface. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::EnumPins

IAMovie Interface

Retrieves a list of pins in the filter graph.

Syntax

HRESULT EnumPins(

  IEnumPins **ppEnum

  );

Parameters

ppEnum
[out] Address of a pointer to the enumerator containing the list of pins.

Return Value

Returns an HRESULT value.

Remarks

For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::EnumPinsIn

IAMovie Interface

Retrieves a list of input pins in the filter graph.

Syntax

HRESULT EnumPinsIn(

  IEnumPins **ppEnum

  );

Parameters

ppEnum
[out] Address of a pointer to the enumerator containing the list of input pins.

Return Value

Returns an HRESULT value.

Remarks

For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::EnumPinsOut

IAMovie Interface

Retrieves a list of output pins in the filter graph.

Syntax

HRESULT EnumPinsOut(

  IEnumPins **ppEnum

  );

Parameters

ppEnum
[out] Address of a pointer to the enumerator containing the list of output pins.

Return Value

Returns an HRESULT value.

Remarks

For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::FreeEventParams

IAMovie Interface

Frees the resources associated with an event's parameters.

Syntax

HRESULT FreeEventParams(

  long lEvCode,

  long lParam1,

  long lParam2

  );

Parameters

lEvCode
Event code.
lParam1
Event's first parameter.
lParam2
Event's second parameter.

Return Value

Returns an HRESULT.

Remarks

The lParam1 and lParam2 parameters must be LONG values, BSTR values, or IUnknown interface pointers. If an argument is a LONG value, FreeEventParams does nothing to it. If it is an IUnknown interface pointer, its reference count has been incremented. Call its Release method to decrement its reference count after calling FreeEventParams. If the argument is a BSTR value, free it by calling the task allocator after FreeEventParams.

IAMovie::get_CurrentPosition

IAMovie Interface

Retrieves the current position in terms of the total length of the media stream.

Syntax

HRESULT get_CurrentPosition(

  REFTIME *pllTime

  );

Parameters

pllTime
[out] Pointer to the reference time of the current position.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_CurrentPosition method.

IAMovie::get_Duration

IAMovie Interface

Retrieves the total duration of the media stream.

Syntax

HRESULT get_Duration(

  REFTIME *plength

  );

Parameters

plength
[out] Pointer to the length of the media stream.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_Duration method.

IAMovie::GetEvent

IAMovie Interface

Retrieves the next notification event.

Syntax

HRESULT GetEvent(

  long *lEventCode,

  long *lParam1,

  long *lParam2,

  long msTimeout

  );

Parameters

lEventCode
[out] Pointer to the next event notification.
lParam1
[out] Pointer to the first parameter of the event.
lParam2
[out] Pointer to the second parameter of the event.
msTimeout
[in] Time, in milliseconds, to wait before assuming that there are no events.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaEvent::GetEvent method.

IAMovie::GetEventHandle

IAMovie Interface

Retrieves a handle to a manual-reset event that will be signaled as long as there are event notifications to deliver.

Syntax

HRESULT GetEventHandle(

  OAEVENT *hEvent

  );

Parameters

hEvent
[out] Pointer to the handle for the event.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaEvent::GetEventHandle method.

IAMovie::get_PrerollTime

IAMovie Interface

Retrieves the time prior to the start position that devices should start rolling.

Syntax

HRESULT get_PrerollTime(

  REFTIME *pTime

  );

Parameters

pTime
[out] Pointer to the returned preroll time.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_PrerollTime method.

IAMovie::get_Rate

IAMovie Interface

Retrieves the rate of playback relative to normal playback speed.

Syntax

HRESULT get_Rate(

  double *pdRate

  );

Parameters

pdRate
[out] Pointer to the returned rate.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_Rate method.

IAMovie::GetState

IAMovie Interface

Determines the state of the filter.

Syntax

HRESULT GetState(

  DWORD dwMilliSecsTimeout,

  FILTER_STATE *State

  );

Parameters

dwMilliSecsTimeout
[in] Duration of the time-out, in milliseconds. To block indefinitely, pass INFINITE.
State
[out] Pointer to the returned state of the filter. States include stopped, paused, running, or intermediate (in the process of changing).

Return Value

Returns an HRESULT value, which will be VFW_S_STATE_INTERMEDIATE if the state transition is not complete, or S_OK if it has been successfully completed.

Remarks

This method simply calls the IMediaControl::GetState method. The state is returned in a FILTER_STATE structure rather than as an OAFilterState type.

IAMovie::get_StopTime

IAMovie Interface

Retrieves the time at which the media stream stops.

Syntax

HRESULT get_StopTime(

  REFTIME *pTime

  );

Parameters

pTime
[out] Pointer to the returned stop time.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_StopTime method.

IAMovie::Pause

IAMovie Interface

Pauses all the filters in the filter graph.

Syntax

HRESULT Pause(void);

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaControl::Pause method.

IAMovie::Play

IAMovie Interface

Plays the media in the current filter graph.

Syntax

HRESULT Play(void);

Return Value

Returns an HRESULT value.

Remarks

This method runs the filter graph to completion by calling IAMovie::Run, and waits for it to complete by calling IAMovie::WaitForCompletion. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::PlayFile

IAMovie Interface

Plays the media in a given file.

Syntax

HRESULT PlayFile(
  LPCWSTR strFilename
  );

Parameters

strFilename
[in] Name of the file to play.

Return Value

Returns an HRESULT value.

Remarks

This method calls the IAMovie::RenderNewFile method to build a filter graph capable of rendering the file passed in strFilename and then plays the file by calling IAMovie::Play. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::put_CurrentPosition

IAMovie Interface

Sets the time that the media stream begins.

Syntax

HRESULT put_CurrentPosition(
  REFTIME Time
  );

Parameters

Time
[in] Start time.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::put_CurrentPosition method.

IAMovie::put_PrerollTime

IAMovie Interface

Sets the time prior to the start position that devices should start rolling.

Syntax

HRESULT put_PrerollTime(
  REFTIME llTime
  );

Parameters

llTime
[in] Preroll time to be set.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::put_PrerollTime method.

IAMovie::put_Rate

IAMovie Interface

Sets the rate of playback relative to normal speed.

Syntax

HRESULT put_Rate(
  double dRate
  );

Parameters

dRate
[in] Rate to set.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::put_Rate method.

IAMovie::put_StopTime

IAMovie Interface

Sets the time at which the media stream will stop.

Syntax

HRESULT put_StopTime(
  REFTIME Time
  );

Parameters

Time
[in] Stop time.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::put_StopTime method.

IAMovie::RemoveAllFilters

IAMovie Interface

Removes all filters from the filter graph.

Syntax

HRESULT RemoveAllFilters(void);

Return Value

Returns an HRESULT value.

Remarks

This method enumerates all filters in the filter graph and then removes each of them by calling RemoveFilter. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::Render

IAMovie Interface

Builds a filter graph that renders the data from this output pin.

Syntax

HRESULT Render(

  IPin *ppinOut

  );

Parameters

ppinOut
[in] Pointer to the output pin.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IGraphBuilder::Render method.

IAMovie::RenderAll

IAMovie Interface

Renders all output pins in the filter graph.

Syntax

HRESULT RenderAll(void);

Return Value

Returns an HRESULT value.

Remarks

This member function enumerates all output pins in the filter graph and renders each of them (builds a filter graph capable of rendering the media type) by calling IAMovie::Render for each output pin. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::RenderFile

IAMovie Interface

Adds and connects filters needed to play the specified file.

Syntax

HRESULT RenderFile(
  LPCWSTR strFilename
  );

Parameters

strFilename
Name of the file to render.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IGraphBuilder::RenderFile method with the PlayList parameter of that method set to NULL.

IAMovie::RenderNewFile

IAMovie Interface

Renders a filter graph for a file name, possibly reusing existing filters.

Syntax

HRESULT RenderNewFile(
  LPCWSTR strFilename
  );

Parameters

strFilename
[in] Name of the file to be rendered.

Return Value

Returns an HRESULT value.

Remarks

This method disconnects all filters in the filter graph, then renders the file in the strFilename parameter by calling IAMovie::RenderFile. This will use the disconnected filters if they can be used to render the file. It then removes any unconnected filters left in the filter graph. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::RestoreDefaultHandling

IAMovie Interface

Reinstates the normal default handling by a filter graph for the specified event if there is one.

Syntax

HRESULT RestoreDefaultHandling(
  long lEvCode
  );

Parameters

lEvCode
[in] Event to restore.

Return Value

Returns S_OK if successful, or S_FALSE if there is no default handling for this event.

Remarks

This method simply calls the IMediaEvent::RestoreDefaultHandling method.

IAMovie::Run

IAMovie Interface

Switches the entire filter graph into a running state.

Syntax

HRESULT Run(void);

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaControl::Run method.

IAMovie::Stop

IAMovie Interface

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

Syntax

HRESULT Stop(void);

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaControl::Stop method.

IAMovie::WaitForCompletion

IAMovie Interface

Provides a simplified way for applications to wait until the filter graph's operation has completed. It is the equivalent of blocking until the event notification EC_COMPLETE, EC_ERRORABORT, or EC_USERABORT is received.

Syntax

HRESULT WaitForCompletion(

  long msTimeout,

  long *pEvCode

  );

Parameters

msTimeout
[in] Duration of the time-out, in milliseconds. To block indefinitely, pass INFINITE.
pEvCode
[out] Pointer to the event to wait for.

Return Value

Returns an HRESULT value.

Remarks

This method simply calls the IMediaEvent::WaitForCompletion method.