IStreamBuilder Interface

The IStreamBuilder interface enables an output pin to notify the graph builder that the pin itself will handle the responsibility of building the downstream graph stream. Output pins that have special connection needs can implement this interface to override the default pin connection process used by the filter graph.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IStreamBuilder methods Description

Render Completes rendering of the stream originating with this pin. This can involve adding filters to the filter graph and connecting them.
Backout Undoes steps taken in Render. This includes disconnecting and removing any filters that were added inside Render.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IStreamBuilder methods	Description
Render	Completes rendering of the stream originating with this pin. This can involve adding filters to the filter graph and connecting them.
Backout	Undoes steps taken in Render. This includes disconnecting and removing any filters that were added inside Render.

IStreamBuilder::Backout

IStreamBuilder Interface

Undoes steps taken in Render. This includes disconnecting and removing any filters that were added inside Render.

Syntax

HRESULT Backout(
   IPin *ppinOut
   IGraphBuilder *pGraph
)

Parameters

ppinOut
[in] Pointer to this pin's IPin interface.

pGraph
[in] Pointer to the filter graph manager's IGraphBuilder interface.

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 code illustrates how to implement this method on an output pin.

STDMETHODIMP CMyOutputPin::BackOut(IPin *pOutputPin, IGraphBuilder *pBuilder)
{
    HRESULT hr = S_OK;
    if (m_Connected != NULL) {
        FILTER_INFO fi;

        // Find the filter pointer for the pin connected to my pin.
        hr = m_Connected->QueryFilterInfo(&fi);
        if (SUCCEEDED(hr)) {
            if (fi.pFilter != NULL) {
                //  Disconnect
                pBuilder->Disconnect(m_Connected);
                pBuilder->Disconnect(pOutputPin);
                // Remove the filter we added from the graph.
                pBuilder->RemoveFilter(fi.pFilter);
                fi.pFilter->Release();
            } else {
                hr = E_UNEXPECTED;
            }
        }
    }
    return hr;
}

IStreamBuilder::Render

IStreamBuilder Interface

Completes rendering of the stream originating with this pin. This can involve adding filters to the filter graph and connecting them.

Syntax

HRESULT Render(
    IPin *ppinOut
    IGraphBuilder *pGraph
);

Parameters

ppinOut
[in] Pointer to this pin's IPin interface.

pGraph
[in] Pointer to the filter graph manager's IGraphBuilder interface.

Return Value

Returns an HRESULT value. A return code of S_OK indicates that the stream was successfully rendered.

Remarks

The following code illustrates how to implement this method on an output pin.

STDMETHODIMP CMyOutputPin::Render(IPin *pOutputPin, IGraphBuilder *pBuilder)
{
    // This filter needs my special renderer connected to it.
    IBaseFilter *pMyRenderer = NULL;
    IPin *pMyRendererInputPin = NULL;
    bool bAddedToGraph = false;

    // Create my renderer.
    HRESULT hr = CoCreateInstance(CLSID_MyRenderer, NULL, CLSCTX_INPROC, IID_IBaseFilter, (void **)&pMyRenderer);
    if (SUCCEEDED(hr)) {
        // Add my renderer to the filter graph.
        hr = pBuilder->AddFilter(pMyRenderer, L"My Renderer");
    }
    // Find my renderer's input pin.

    if (SUCCEEDED(hr)) {
            bAddedToGraph = true;
            IEnumPins *pEnumPins;
            hr = pMyRenderer->EnumPins(&pEnumPins);
            if (SUCCEEDED(hr)) {
                DWORD nPins;
                if (S_OK != pEnumPins->Next(1, &pMyRendererInputPin, &nPins)) {
                    hr = E_UNEXPECTED;
                }
            }
    }
    if (SUCCEEDED(hr)) {
        // Connect my renderer to my output pin.
        hr = pBuilder->ConnectDirect(pOutputPin, pMyRendererInputPin);
    }
    if (FAILED(hr)) {
        if (bAddedToGraph) {
            pBuilder->RemoveFilter(pMyRenderer);
        }
        pMyRenderer->Release();
    }
    if (NULL != pMyRendererOutputPin) {
        pMyRendererInputPin->Release();
    }
    return hr;
}