Using Attributes in Media Foundation

An attribute is a key/value pair, where the key is a GUID and the value is a PROPVARIANT. Attribute values are restricted to the following data types:

  • Unsigned 32-bit integer

  • Unsigned 64-bit integer

  • 64-bit floating-point number

  • GUID

  • Null-terminated wide-character string

  • Byte array

  • IUnknown pointer

These types are defined in the MF_ATTRIBUTE_TYPE enumeration. To set or retrieve attribute values, use the IMFAttributes interface. This interface contains type-safe methods to get and set values by data type. For example, to set a 32-bit integer, call IMFAttributes::SetUINT32. Attribute keys are unique within an object. If you set two different values with the same key, the second value overwrites the first.

Several Media Foundation interfaces inherit the IMFAttributes interface. Objects that expose this interface have optional or mandatory attributes that the application should set on the object, or have attributes that the application can retrieve.

Also, some methods and functions take an IMFAttributes pointer as a parameter, which enables the application to set configuration information. The application must create an attribute store to hold the configuration attributes. To create an empty attribute store, call MFCreateAttributes.

The following code shows two functions. The first creates a new attribute store and sets a hypothetical attribute named MY_ATTRIBUTE with a string value. The second function retrieves the value of this attribute.

extern const GUID MY_ATTRIBUTE;

HRESULT ShowCreateAttributeStore(IMFAttributes **ppAttributes)
{
    IMFAttributes *pAttributes = NULL;
    const UINT32 cElements = 10;  // Starting size.

    // Create the empty attribute store.
    HRESULT hr = MFCreateAttributes(&pAttributes, cElements);

    // Set the MY_ATTRIBUTE attribute with a string value.
    if (SUCCEEDED(hr))
    {
        hr = pAttributes->SetString(
            MY_ATTRIBUTE,
            L"This is a string value"
            );
    }

    // Return the IMFAttributes pointer to the caller.
    if (SUCCEEDED(hr))
    {
        *ppAttributes = pAttributes;
        (*ppAttributes)->AddRef();
    }

    SAFE_RELEASE(pAttributes);

    return hr;
}

HRESULT ShowGetAttributes()
{
    IMFAttributes *pAttributes = NULL;
    WCHAR *pwszValue = NULL;
    UINT32 cchLength = 0;

    // Create the attribute store.
    HRESULT hr = ShowCreateAttributeStore(&pAttributes);

    // Get the attribute.
    if (SUCCEEDED(hr))
    {
        hr = pAttributes->GetAllocatedString(
            MY_ATTRIBUTE,
            &pwszValue,
            &cchLength
            );
    }

    CoTaskMemFree(pwszValue);
    SAFE_RELEASE(pAttributes);

    return hr;
}

For a complete list of Media Foundation attributes, see Media Foundation Attributes. The expected data type for each attribute is documented there.

Serializing Attributes

Media Foundation has two functions for serializing attribute stores. One writes the attributes to a byte array, the other writes them to a stream that supports the IStream interface. Each function has a corresponding function that loads the data.

Operation Byte Array IStream
Save MFGetAttributesAsBlob MFSerializeAttributesToStream
Load MFInitAttributesFromBlob MFDeserializeAttributesFromStream

 

To write the contents of an attribute store into a byte array, call MFGetAttributesAsBlob. Attributes with IUnknown pointer values are ignored. To load the attributes back into an attribute store, call MFInitAttributesFromBlob.

To write an attribute store to a stream, call MFSerializeAttributesToStream. This function can marshal IUnknown pointer values. The caller must provide a stream object that implements the IStream interface. To load an attribute store from a stream, call MFDeserializeAttributesFromStream.

Attributes and Properties

 

 

Send comments about this topic to Microsoft

Build date: 9/21/2010