ICaptureGraphBuilder2::SetOutputFileName method (strmif.h)

Article
07/27/2023

[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 SetOutputFileName method creates the file writing section of the filter graph.

Syntax

HRESULT SetOutputFileName(
  [in]  const GUID      *pType,
  [in]  LPCOLESTR       lpstrFile,
  [out] IBaseFilter     **ppf,
  [out] IFileSinkFilter **ppSink
);

Parameters

[in] pType

Pointer to a GUID that represents either the media subtype of the output or the class identifier (CLSID) of a multiplexer filter or file writer filter. If you specify a media subtype, it must be one of the following:

Value	Description
MEDIASUBTYPE_Avi	Audio-Video Interleaved (AVI)
MEDIASUBTYPE_Asf	Advanced Systems Format (ASF)

[in] lpstrFile

Pointer to a wide-character string that contains the output file name.

[out] ppf

Address of a pointer that receives the multiplexer's IBaseFilter interface.

[out] ppSink

Address of a pointer that receives the file writer's IFileSinkFilter interface. Can be NULL.

Return value

Returns an HRESULT value. Possible values include the following.

Return code	Description
S_OK	Success.
E_FAIL	Failure.
E_POINTER	NULL pointer argument.

Remarks

This method creates a multiplexer filter based on the value of the pType parameter. For AVI, it creates the AVI Mux Filter. For ASF, it creates the WM ASF Writer. For other values, it creates the filter identified by the CLSID. It adds the multiplexer to the filter graph, and returns a pointer to its IBaseFilter interface in the ppf parameter.

If the multiplexer supports the IFileSinkFilter interface, the method calls IFileSinkFilter::SetFileName to set the output file name, using the value given in the lpwstrFile parameter. If the multiplexer does not support IFileSinkFilter interface, the method adds the File Writer Filter to the filter graph, connects the multiplexer to the file writer, and uses the file writer's IFileSinkFilter interface to call SetFileName. If the pSink parameter is not NULL, it receives a pointer to the IFileSinkFilter interface.

You can use the pointer to the multiplexer filter, returned in the ppf parameter, as the pSink parameter in the ICaptureGraphBuilder2::RenderStream method.

For custom multiplexer filters, the method fails if the filter does not support a connection on its output pin before its input pins are connected. For example, the WavDest Filter Sample included with the SDK has this limitation.

If the method succeeds, the IBaseFilter interface returned in the ppf parameter has an outstanding reference count. If the method succeeds and pSink is not NULL, the IFileSinkFilter interface also has an outstanding reference count. Be sure to release both interfaces when you are done using them.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	strmif.h (include Dshow.h)
Library	Strmiids.lib