Utilisation des catégories de broches

[La fonctionnalité associée à cette page, DirectShow, est une fonctionnalité héritée. Il a été remplacé par MediaPlayer, IMFMediaEngine et Audio/Video Capture dans Media Foundation. Ces fonctionnalités ont été optimisées pour Windows 10 et Windows 11. Microsoft recommande vivement au nouveau code d’utiliser MediaPlayer, IMFMediaEngine et La capture audio/vidéo dans Media Foundation au lieu de DirectShow, lorsque cela est possible. Microsoft suggère que le code existant qui utilise les API héritées soit réécrit pour utiliser les nouvelles API si possible.]

Pour rechercher sur un filtre une broche avec une catégorie de broche donnée, vous pouvez utiliser la méthode ICaptureGraphBuilder2::FindPin . L’exemple suivant recherche une broche d’aperçu vidéo :

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.
);

Le premier paramètre est un pointeur vers l’interface IBaseFilter du filtre. Les trois paramètres suivants spécifient la direction, la catégorie de broche et le type de média. La valeur FALSE dans le cinquième paramètre indique que la broche peut être connectée ou non connectée. (Pour obtenir les définitions exactes de ces paramètres, reportez-vous à la documentation de la méthode.) Si la méthode trouve une broche correspondante, elle retourne un pointeur vers l’interface IPin dans le paramètre pPin .

Bien que la méthode FindPin soit pratique, vous pouvez également écrire vos propres fonctions d’assistance si vous préférez. Pour déterminer la catégorie d’une broche, appelez la méthode IKsPropertySet::Get comme décrit dans la rubrique Pin Property Set.

Le code suivant montre une fonction d’assistance qui vérifie si une broche correspond à une catégorie spécifiée :

// 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;
        hr = pKs->Get(AMPROPSETID_Pin, AMPROPERTY_PIN_CATEGORY, NULL, 0, 
            &PinCategory, sizeof(GUID), &cbReturned);
        if (SUCCEEDED(hr) && (cbReturned == sizeof(GUID)))
        {
            bFound = (PinCategory == Category);
        }
        pKs->Release();
    }
    return bFound;
}

L’exemple suivant est une fonction qui recherche une broche par catégorie, comme la méthode FindPin :

// 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;
            break;
        }
        SafeRelease(&pPin);
    }

done:
    SafeRelease(&pPin);
    SafeRelease(&pEnum);
    if (SUCCEEDED(hr) && !bFound)
    {
        hr = E_FAIL;
    }
    return hr;
}

Le code suivant utilise la fonction précédente pour rechercher une broche de port vidéo sur un filtre :

IPin *pVP; 
hr = FindPinByCategory(pFilter, PINDIR_OUTPUT, 
    PIN_CATEGORY_VIDEOPORT, &pVP);
if (SUCCEEDED(hr))
{
    // Use pVP ... 
    // Release when you are done.
    pVP->Release();
}

Pour plus d’informations sur les jeux de propriétés, reportez-vous à la documentation du Kit de pilotes Windows (WDK).

Rubriques connexes

Rubriques de capture avancée

Pin Property Set

Filtres de capture vidéo DirectShow