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. |
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
);
Returns an HRESULT value.
This method simply calls the IGraphBuilder::AddSourceFilter method. The lpwstrFileName file name is used as the filter name when IGraphBuilder::AddSourceFilter is called.
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
);
Returns S_OK if successful, or S_FALSE if the event does not have any default handling.
This method simply calls the IMediaEvent::CancelDefaultHandling method.
Connects the two pins, using intermediates if necessary.
HRESULT Connect(
IPin * ppinOut,
IPin * ppinIn
);
Returns an HRESULT value.
This method simply calls the IGraphBuilder::Connect method.
Retrieves a list of filters supporting a specified interface.
HRESULT EnumFiltersByInterface(
REFIID riid,
IEnumFilters ** ppEnum
);
Returns an HRESULT value.
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.
Retrieves a list of pins in the filter graph.
HRESULT EnumPins(
IEnumPins ** ppEnum
);
Returns an HRESULT value.
For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.
Retrieves a list of input pins in the filter graph.
HRESULT EnumPinsIn(
IEnumPins ** ppEnum
);
Returns an HRESULT value.
For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.
Retrieves a list of output pins in the filter graph.
HRESULT EnumPinsOut(
IEnumPins ** ppEnum
);
Returns an HRESULT value.
For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.
Frees the resources associated with an event's parameters.
HRESULT FreeEventParams(
long lEvCode,
long lParam1,
long lParam2
);
Returns an HRESULT.
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.
Retrieves the current position in terms of the total length of the media stream.
HRESULT get_CurrentPosition(
REFTIME* pllTime
);
Returns an HRESULT value.
This method simply calls the IMediaPosition::get_CurrentPosition method.
Retrieves the total duration of the media stream.
HRESULT get_Duration(
REFTIME* plength
);
Returns an HRESULT value.
This method simply calls the IMediaPosition::get_Duration method.
Retrieves the time prior to the start position that devices should start rolling.
HRESULT get_PrerollTime(
REFTIME* pTime
);
Returns an HRESULT value.
This method simply calls the IMediaPosition::get_PrerollTime method.
Retrieves the rate of playback relative to normal playback speed.
HRESULT get_Rate(
double * pdRate
);
Returns an HRESULT value.
This method simply calls the IMediaPosition::get_Rate method.
Retrieves the time at which the media stream stops.
HRESULT get_StopTime(
REFTIME* pTime
);
Returns an HRESULT value.
This method simply calls the IMediaPosition::get_StopTime method.
Retrieves the next notification event.
HRESULT GetEvent(
long * lEventCode,
long * lParam1,
long * lParam2,
long msTimeout
);
Returns an HRESULT value.
This method simply calls the IMediaEvent::GetEvent method.
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
);
Returns an HRESULT value.
This method simply calls the IMediaEvent::GetEventHandle method.
Determines the state of the filter.
HRESULT GetState(
DWORD dwMilliSecsTimeout,
FILTER_STATE * State
);
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.
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.
Pauses all the filters in the filter graph.
HRESULT Pause( );
Returns an HRESULT value.
This method simply calls the IMediaControl::Pause method.
Plays the media in the current filter graph.
HRESULT Play( );
Returns an HRESULT value.
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.
Plays the media in a given file.
HRESULT PlayFile(
LPCWSTR strFilename
);
Returns an HRESULT value.
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.
Sets the time that the media stream begins.
HRESULT put_CurrentPosition(
REFTIME Time
);
Returns an HRESULT value.
This method simply calls the IMediaPosition::put_CurrentPosition method.
Sets the time prior to the start position that devices should start rolling.
HRESULT put_PrerollTime(
REFTIME llTime
);
Returns an HRESULT value.
This method simply calls the IMediaPosition::put_PrerollTime method.
Sets the rate of playback relative to normal speed.
HRESULT put_Rate(
double dRate
);
Returns an HRESULT value.
This method simply calls the IMediaPosition::put_Rate method.
Sets the time at which the media stream will stop.
HRESULT put_StopTime(
REFTIME Time
);
Returns an HRESULT value.
This method simply calls the IMediaPosition::put_StopTime method.
Removes all filters from the filter graph.
HRESULT RemoveAllFilters( );
Returns an HRESULT value.
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.
Builds a filter graph that renders the data from this output pin.
HRESULT Render(
IPin * ppinOut
);
Returns an HRESULT value.
This method simply calls the IGraphBuilder::Render method.
Renders all output pins in the filter graph.
HRESULT RenderAll( );
Returns an HRESULT value.
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.
Adds and connects filters needed to play the specified file.
HRESULT RenderFile(
LPCWSTR strFilename
);
Returns an HRESULT value.
This method simply calls the IGraphBuilder::RenderFile method with the PlayList parameter of that method set to NULL.
Renders a filter graph for a file name, possibly reusing existing filters.
HRESULT RenderNewFile(
LPCWSTR strFilename
);
Returns an HRESULT value.
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.
Reinstates the normal default handling by a filter graph for the specified event if there is one.
HRESULT RestoreDefaultHandling(
long lEvCode
);
Returns S_OK if successful, or S_FALSE if there is no default handling for this event.
This method simply calls the IMediaEvent::RestoreDefaultHandling method.
Switches the entire filter graph into a running state.
HRESULT Run( );
Returns an HRESULT value.
This method simply calls the IMediaControl::Run method.
Switches all filters in the filter graph to the stopped state.
HRESULT Stop( );
Returns an HRESULT value.
This method simply calls the IMediaControl::Stop method.
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
);
Returns an HRESULT value.
This method simply calls the IMediaEvent::WaitForCompletion method.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.