IGraphConfig::Reconfigure 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 Reconfigure method locks the filter graph and calls a callback function in the application or filter to perform a dynamic reconfiguration.

Syntax

HRESULT Reconfigure(
  [in] IGraphConfigCallback *pCallback,
  [in] PVOID                pvContext,
  [in] DWORD                dwFlags,
  [in] HANDLE               hAbortEvent
);

Parameters

[in] pCallback

Pointer to the IGraphConfigCallback callback interface on the application or filter.

[in] pvContext

Pointer to a variable of type PVOID that is passed to the callback routine.

[in] dwFlags

Application-defined flags that are passed to the callback routine.

[in] hAbortEvent

Handle to an event. If the caller is a filter calling on one of its data processing threads, this parameter should be a handle to an event that will be signaled when the filter is put into a stopped state. Otherwise, this parameter can be NULL. For more information, see Remarks.

Return value

Returns S_OK if successful, or an error code otherwise. Possible errors include VFW_E_WRONG_STATE, if the method could not obtain a lock on the filter graph; whatever HRESULT was returned by the callback routine; or an error code indicating that the graph could not put the filters into a running state.

Remarks

This method is provided so that an application or filter can implement specialized dynamic graph building. In most cases, however, the IGraphConfig::Reconnect method is adequate, and should be preferred because it handles most of the implementation details.

Before calling this method, block any streams as needed and push the data through the graph (see IPinFlowControl::Block and IGraphConfig::PushThroughData). If the callback method succeeds, IGraphConfig::Reconfigure attempts to put all the filters into a running state. (The caller must then unblock the data flow.) Otherwise, it returns whatever error code the callback method returned.

If a filter calls this method on one of its own data processing threads, it creates the potential for a deadlock. The method obtains a lock on the filter graph, which can block the filter from stopping on receiving a call to IMediaFilter::Stop. To prevent this situation, the method takes a handle to an event object provided by filter. The filter should signal the event if it receives a call to its Stop method.

Requirements

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