IGraphBuilder::AddSourceFilter method (strmif.h)

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The AddSourceFilter method adds a source filter for a specified file to the filter graph.

Syntax

HRESULT AddSourceFilter(
  [in]  LPCWSTR     lpcwstrFileName,
  [in]  LPCWSTR     lpcwstrFilterName,
  [out] IBaseFilter **ppFilter
);

Parameters

[in] lpcwstrFileName

Specifies the name of the file to load.

[in] lpcwstrFilterName

Specifies a name for the source filter.

[out] ppFilter

Receives a pointer to the filter's IBaseFilter interface. The caller must release the interface.

Return value

Returns an HRESULT. Possible values include the following.

Remarks

This method searches for an installed filter that can read the specified file. If it finds one, the method adds it to the filter graph and returns a pointer to the filter's IBaseFilter interface. To determine the media type and compression scheme of the file, the Filter Graph Manager reads the first few bytes of the file, looking for specific patterns of bytes, as documented in the article Registering a Custom File Type.

The application is responsible for building the rest of the filter graph. To do so, call IBaseFilter::EnumPins to enumerate the output pins on the source filter. Then use either the IGraphBuilder::Connect method or the IGraphBuilder::Render method.

If the method succeeds, the IBaseFilter interface has an outstanding reference count. The caller must release the interface.

To render a file for default playback, use the IGraphBuilder::RenderFile method.

The Filter Graph Manager holds a reference count on the filter until the filter is removed from the graph or the Filter Graph Manager is released.

Requirements

See also

Error and Success Codes

IGraphBuilder Interface