Export (0) Print
Expand All

Working with Pin Categories

To search on a filter the the for a pin with a given pin category, you can use the ICaptureGraphBuilder2::FindPin method. The following example searches for a video preview pin:

int i = 0;
hr = pBuild->FindPin(
    pFilter,               // Pointer to a filter to search.
    PINDIR_OUTPUT,         // Which pin direction?
    &PIN_CATEGORY_PREVIEW, // Which category? (NULL means "any category")
    &MEDIATYPE_Video,      // What media type? (NULL means "any type")
    FALSE,                 // Must be connected?
    i,                     // Get the i'th matching pin (0 = first match)
    &pPin                  // Receives a pointer to the pin.

The first parameter is a pointer to the filter's IBaseFilter interface. The next three parameters specify the direction, pin category, and media type. The value FALSE in the fifth parameter indicates that the pin can be either connected or unconnected. (For the exact definitions of these parameters, refer to the documentation for the method.) If the method finds a matching pin, it returns a pointer to the IPin interface in the pPin parameter.

Although the FindPin method is convenient, you can also write your own helper functions if you prefer. To determine a pin's category, call the IKsPropertySet::Get method as described in the topic Pin Property Set.

The following code shows a helper function that checks whether a pin matches a specified category:

// Returns TRUE if a pin matches the specified pin category.

BOOL PinMatchesCategory(IPin *pPin, REFGUID Category)
    BOOL bFound = FALSE;

    IKsPropertySet *pKs = NULL;
    HRESULT hr = pPin->QueryInterface(IID_PPV_ARGS(&pKs));
    if (SUCCEEDED(hr))
        GUID PinCategory;
        DWORD cbReturned;
            &PinCategory, sizeof(GUID), &cbReturned);
        if (SUCCEEDED(hr) && (cbReturned == sizeof(GUID)))
            bFound = (PinCategory == Category);
    return bFound;

The next example is a function that searches for a pin by category, similar to the FindPin method:

// Finds the first pin that matches a specified pin category and direction.

HRESULT FindPinByCategory(
    IBaseFilter *pFilter, // Pointer to the filter to search.
    PIN_DIRECTION PinDir, // Direction of the pin.
    REFGUID Category,     // Pin category.
    IPin **ppPin)         // Receives a pointer to the pin.
    *ppPin = 0;

    HRESULT hr = S_OK;
    BOOL bFound = FALSE;

    IEnumPins *pEnum = 0;
    IPin *pPin = 0;

    hr = pFilter->EnumPins(&pEnum);
    if (FAILED(hr))
        goto done;

    while (hr = pEnum->Next(1, &pPin, 0), hr == S_OK)
        PIN_DIRECTION ThisPinDir;
        hr = pPin->QueryDirection(&ThisPinDir);
        if (FAILED(hr))
            goto done;
        if ((ThisPinDir == PinDir) && 
            PinMatchesCategory(pPin, Category))
            *ppPin = pPin;
            (*ppPin)->AddRef();   // The caller must release the interface.
            bFound = TRUE;

    if (SUCCEEDED(hr) && !bFound)
        hr = E_FAIL;
    return hr;

The following code uses the previous function to search for a video port pin on a filter:

IPin *pVP; 
hr = FindPinByCategory(pFilter, PINDIR_OUTPUT, 
if (SUCCEEDED(hr))
    // Use pVP ... 
    // Release when you are done.

For more information about property sets, refer to the Windows Driver Kit (WDK) documentation.

Related topics

Advanced Capture Topics
Pin Property Set
DirectShow Video Capture Filters



Community Additions

© 2015 Microsoft