IFilterGraph2::ReconnectEx 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 ReconnectEx method breaks the existing pin connection and reconnects it to the same pin, using a specified media type.
Applications should not call this method. It is called by filters during the graph building process.
Syntax
HRESULT ReconnectEx(
[in] IPin *ppin,
[in] const AM_MEDIA_TYPE *pmt
);
Parameters
[in] ppin
Pointer to the pin to disconnect and reconnect.
[in] pmt
Pointer to the media type to reconnect with. Specify NULL to use the existing media type.
Return value
Returns an HRESULT value. Possible values include the following.
| Return code | Description |
|---|---|
|
Success. |
|
Pin was not connected. No error. |
|
Failure. |
|
NULL pointer argument. |
|
The filter is not stopped, but it does not support reconnection while in a running state. |
Remarks
Filters can call this method in order to renegotiate a pin connection. The method executes on a separate thread. Before calling this method, call IPin::QueryAccept on the other pin to ensure that the reconnection attempt will succeed. Do not call this method unless QueryAccept returns S_OK. Otherwise, because the reconnection is performed asynchronously, the reconnection might fail even though the ReconnectEx method succeeds, leaving the filter graph in an inconsistent state.
This method improves on the IFilterGraph::Reconnect method by specifying a media type. This makes the reconnection more likely to succeed.
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 |