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.

When to Implement

This interface is implemented by the IAMovie sample plug-in distributor included in this SDK. It is not expected that anything else will implement this interface.

When to Use

Applications use plug-in distributors. If this interface is implemented through the IAMovie 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	Returns 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.

HRESULT AddSourceFilter(
  LPCWSTR lpwstrFileName,
  IBaseFilter* * ppFilter
  );

Parameters

lpwstrFileName

[in] Pointer to the file.

ppFilter

[out] Pointer to an IBaseFilter interface on the filter that was added.

Return Values

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.

HRESULT CancelDefaultHandling(
  long lEvCode
  );

Parameters

lEvCode

Event code for which to cancel default handling.

Return Values

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.

HRESULT Connect(
  IPin * ppinOut,
  IPin * ppinIn
  );

Parameters

ppinOut

[in] Output pin.

ppinIn

[in] Input pin.

Return Values

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.

HRESULT EnumFiltersByInterface(
  REFIID riid,
  IEnumFilters ** ppEnum
  );

Parameters

riid

[in] REFIID of the interface qualifying the search.

ppEnum

[out] Retrieved IEnumFilters enumerator containing the matching filters.

Return Values

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.

HRESULT EnumPins(
  IEnumPins ** ppEnum
  );

Parameters

ppEnum

[out] Enumerator containing the list of pins.

Return Values

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.

HRESULT EnumPinsIn(
  IEnumPins ** ppEnum
  );

Parameters

ppEnum

[out] Enumerator containing the list of input pins.

Return Values

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.

HRESULT EnumPinsOut(
  IEnumPins ** ppEnum
  );

Parameters

ppEnum

[out] Enumerator containing the list of output pins.

Return Values

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.

HRESULT FreeEventParams(
  long lEvCode,
  long lParam1,
  long lParam2
  );

Parameters

lEvCode

Event code.

lParam1

Event's first parameter.

lParam2

Event's second parameter.

Return Values

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.

HRESULT get_CurrentPosition(
  REFTIME* pllTime
  );

Parameters

pllTime

[out] Reference time of the current position.

Return Values

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.

HRESULT get_Duration(
  REFTIME* plength
  );

Parameters

plength

[out] Returned length of the media stream.

Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_Duration method.

---

IAMovie::GetEvent

IAMovie Interface

Retrieves the next notification event.

HRESULT GetEvent(
  long * lEventCode,
  long * lParam1,
  long * lParam2,
  long msTimeout
  );

Parameters

lEventCode

[out] Next event notification.

lParam1

[out] First parameter of the event.

lParam2

[out] Second parameter of the event.

msTimeout

[in] Time, in milliseconds, to wait before assuming that there are no events.

Return Values

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.

HRESULT GetEventHandle(
  OAEVENT * hEvent
  );

Parameters

hEvent

[out] Handle for the event.

Return Values

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.

HRESULT get_PrerollTime(
  REFTIME* pTime
  );

Parameters

pTime

[out] Returned preroll time.

Return Values

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.

HRESULT get_Rate(
  double * pdRate
  );

Parameters

pdRate

[out] Returned rate.

Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_Rate method.

---

IAMovie::GetState

IAMovie Interface

Determines the state of the filter.

HRESULT GetState(
  DWORD dwMilliSecsTimeout,
  FILTER_STATE * State
  );

Parameters

dwMilliSecsTimeout

[in] Duration of the time-out, in milliseconds. To block indefinitely, pass INFINITE.

State

[out] Holder of the returned state of the filter. States include stopped, paused, running, or intermediate (in the process of changing).

Return Values

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. Note that 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.

HRESULT get_StopTime(
  REFTIME* pTime
  );

Parameters

pTime

[out] Returned stop time.

Return Values

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.

HRESULT Pause( );

Return Values

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.

HRESULT Play( );

Return Values

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.

HRESULT PlayFile(
  LPCWSTR strFilename
  );

Parameters

strFilename

[in] Name of the file to play.

Return Values

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.

HRESULT put_CurrentPosition(
  REFTIME Time
  );

Parameters

Time

[in] Start time.

Return Values

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.

HRESULT put_PrerollTime(
  REFTIME llTime
  );

Parameters

llTime

[in] Preroll time to be set.

Return Values

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.

HRESULT put_Rate(
  double dRate
  );

Parameters

dRate

[in] Rate to set.

Return Values

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.

HRESULT put_StopTime(
  REFTIME Time
  );

Parameters

Time

[in] Stop time.

Return Values

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.

HRESULT RemoveAllFilters( );

Return Values

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.

HRESULT Render(
  IPin * ppinOut
  );

Parameters

ppinOut

[in] Output pin.

Return Values

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.

HRESULT RenderAll( );

Return Values

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.

HRESULT RenderFile(
  LPCWSTR strFilename
  );

Parameters

strFilename

Name of the file to render.

Return Values

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.

HRESULT RenderNewFile(
  LPCWSTR strFilename
  );

Parameters

strFilename

[in] Name of the file to be rendered.

Return Values

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.

HRESULT RestoreDefaultHandling(
  long lEvCode
  );

Parameters

lEvCode

[in] Event to restore.

Return Values

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.

HRESULT Run( );

Return Values

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.

HRESULT Stop( );

Return Values

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.

HRESULT WaitForCompletion(
  long msTimeout,
  long * pEvCode
  );

Parameters

msTimeout

[in] Duration of the time-out, in milliseconds. To block indefinitely, pass INFINITE.

pEvCode

[out] Event to wait for.

Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaEvent::WaitForCompletion method.

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

Top of Page