IStreamBuilder::Backout method (strmif.h)

Article
02/22/2024

[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 Backout method undoes steps taken in the IStreamBuilder::Render method. This includes disconnecting and removing any filters that were added inside Render.

Syntax

HRESULT Backout(
  [in] IPin          *ppinOut,
  [in] IGraphBuilder *pGraph
);

Parameters

[in] ppinOut

Pointer to the IPin interface of this pin.

[in] pGraph

Pointer to the IGraphBuilder interface of the Filter Graph Manager.

Return value

Returns an HRESULT value. A return code of S_OK indicates to the graph builder that the disconnect was successful.

Remarks

The following example shows how a filter would reverse the steps that are shown in the code example for the IStreamBuilder::Render method:

C++

C++
STDMETHODIMP CMyOutputPin::BackOut(IPin pPin, IGraphBuilder pGraph) { CheckPointer(pPin, E_POINTER); CheckPointer(pGraph, E_POINTER); HRESULT hr = S_OK; if (m_Connected != NULL) // Pointer to the pin we're connected to. { // Find the filter that owns the pin connected to us. FILTER_INFO fi; hr = m_Connected->QueryFilterInfo(&fi); if (SUCCEEDED(hr)) { if (fi.pFilter != NULL) { // Disconnect the pins. pGraph->Disconnect(m_Connected); pGraph->Disconnect(pPin); // Remove the filter from the graph. pGraph->RemoveFilter(fi.pFilter); fi.pFilter->Release(); } else { hr = E_UNEXPECTED; } } } return hr; }

STDMETHODIMP CMyOutputPin::BackOut(IPin *pPin, IGraphBuilder *pGraph)
{
    CheckPointer(pPin, E_POINTER);
    CheckPointer(pGraph, E_POINTER);

    HRESULT hr = S_OK;
    if (m_Connected != NULL) // Pointer to the pin we're connected to.
    {
        // Find the filter that owns the pin connected to us.
        FILTER_INFO fi;
        hr = m_Connected-&gt;QueryFilterInfo(&amp;fi);
        if (SUCCEEDED(hr)) 
        {
            if (fi.pFilter != NULL) 
            {
                //  Disconnect the pins.
                pGraph-&gt;Disconnect(m_Connected);
                pGraph-&gt;Disconnect(pPin);
                // Remove the filter from the graph.
                pGraph-&gt;RemoveFilter(fi.pFilter);
                fi.pFilter-&gt;Release();
            } 
            else 
            {
                hr = E_UNEXPECTED;
            }
        }
    }
    return hr;
}

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