IKsPin::KsQueryMediums method

Article
07/27/2023

[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 KsQueryMediums method retrieves the mediums supported by a pin.

Syntax

HRESULT KsQueryMediums(
  [out] KSMULTIPLE_ITEM **ppmi
);

Parameters

ppmi [out]: Address of a pointer to a KSMULTIPLE_ITEM structure.

Return value

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

This method returns a task-allocated KSMULTIPLE_ITEM structure, which is followed by zero or more REGPINMEDIUM structures. The Count member of the KSMULTIPLE_ITEM structure specifies the number of REGPINMEDIUM structures. Each REGPINMEDIUM structure defines a medium supported by the pin.

The caller must free the returned structures, using the CoTaskMemFree function.

You must include Ks.h before Ksproxy.h.

Examples

The following helper function attempts to match a pin against a specified medium.

HRESULT FindMatchingMedium(
    IPin *pPin, 
    REGPINMEDIUM *pMedium, 
    bool *pfMatch)
{
    IKsPin* pKsPin = NULL;
    KSMULTIPLE_ITEM *pmi;

    *pfMatch = false;
    HRESULT hr = pPin->QueryInterface(IID_IKsPin, (void **)&pKsPin);
    if (FAILED(hr)) 
        return hr;  // Pin does not support IKsPin.

    hr = pKsPin->KsQueryMediums(&pmi);
    pKsPin->Release();
    if (FAILED(hr))
        return hr;  // Pin does not support mediums.

    if (pmi->Count) 
    {
        // Use pointer arithmetic to reference the first medium structure.
        REGPINMEDIUM *pTemp = (REGPINMEDIUM*)(pmi + 1);
        for (ULONG i = 0; i < pmi->Count; i++, pTemp++) 
        {
            if (pMedium->clsMedium == pTemp->clsMedium) 
            {
                *pfMatch = true;
                break;
            }
        }
    }        
    CoTaskMemFree(pmi);
    return S_OK;
}

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	Ksproxy.h
Library	Strmiids.lib

Share via