Share via

IKsPin::KsQueryMediums

  • Article
 
Microsoft DirectShow 9.0

IKsPin::KsQueryMediums

The KsQueryMediums method retrieves the mediums supported by a pin.

Syntax

  HRESULT KsQueryMediums(
  
  KSMULTIPLE_ITEM **
  ppmi
  
  );

Parameters

  ppmi

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

Return Values

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.

Example Code

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

Header: Include Ks.h, Ksproxy.h. You must include Ks.h before Ksproxy.h.

Library: Use Strmiids.lib.

See Also