IEnumMediaTypes Interface

The IEnumMediaTypes interface enumerates the preferred formats for a pin.

This interface must be implemented and made available by the IPin::EnumMediaTypes method. The CBasePin::EnumMediaTypes member function automatically does this in the Microsoft® DirectShow® class library and uses the CEnumMediaTypes class to create the enumerator object.

This interface is typically used by a connecting pin to determine the media type when negotiating a connection. It can also be passed through to other pins, either upstream or downstream of the filter, when intervening filters do not have a list of preferred media types. For example, a transform-inplace filter might pass the IEnumMediaTypes interface of a downstream input pin to the connecting output pin of the upstream filter, instead of providing its own IEnumMediaTypes interface.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IEnumMediaTypes methods Description
Next Retrieves the specified number of items in the enumeration sequence.
Skip Skips a specified number of elements in the enumeration sequence.
Reset Resets the enumeration sequence to the beginning.
Clone Retrieves another enumerator containing the same enumeration state as the current one.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IEnumMediaTypes methods	Description
Next	Retrieves the specified number of items in the enumeration sequence.
Skip	Skips a specified number of elements in the enumeration sequence.
Reset	Resets the enumeration sequence to the beginning.
Clone	Retrieves another enumerator containing the same enumeration state as the current one.

IEnumMediaTypes::Clone

IEnumMediaTypes Interface

Retrieves another enumerator containing the same enumeration state as the current one.

Syntax

HRESULT Clone(
    IEnumMediaTypes **ppEnum
);

Parameters

ppEnum
[out] Address of a pointer to the new copy of the enumerator.

Return Value

Returns one of the following HRESULT values.

E_OUTOFMEMORY Insufficient memory.

E_POINTER Null pointer argument.

S_OK Success.

VFW_E_ENUM_OUT_OF_SYNC The enumerator has become invalid. For more information, see Remarks.

Remarks

If the list of available media types changes, it will no longer be consistent with the state of the enumerator, in which case this method will return VFW_E_ENUM_OUT_OF_SYNC. You should discard any data obtained from previous calls to the enumerator, because it might be invalid, and update the enumerator by calling the Reset method. You can then call the Clone method safely.

IEnumMediaTypes::Next

IEnumMediaTypes Interface

Retrieves the specified number of items in the enumeration sequence.

Syntax

HRESULT Next(
    ULONG cMediaTypes,
    AM_MEDIA_TYPE **ppMediaTypes,
    ULONG *pcFetched
);

Parameters

cMediaTypes
[in] Number of media types to place.
ppMediaTypes
[out] Address of a pointer to the array in which to place the pointers to the next media type.
pcFetched
[out] Pointer to the actual count passed.

Return Value

Returns one of the following HRESULT values.

E_INVALIDARG Invalid argument.

E_POINTER Null pointer argument.

S_FALSE Fewer media types were retrieved than requested.

S_OK Success.

VFW_E_ENUM_OUT_OF_SYNC The enumerator has become invalid. For more information, see Remarks.

Remarks

To use this method, pass an array of pointers to media types. (If you want only a single media type, you can pass a pointer to a media type pointer in place of an array of media type pointers.) The interface allocates the necessary AM_MEDIA_TYPE structures and initializes them with the variable format block. Free each media type by calling DeleteMediaType, which will free the format block and the media type itself.

If the list of available media types changes, it will no longer be consistent with the state of the enumerator, in which case this method will return VFW_E_ENUM_OUT_OF_SYNC. You should discard any data obtained from previous calls to the enumerator, because it might be invalid, and update the enumerator by calling the Reset method. You can then call the Next method safely.

IEnumMediaTypes::Reset

IEnumMediaTypes Interface

Resets the enumerator to the beginning so that the next call to the IEnumMediaTypes::Next method returns, at a minimum, the first media type (if any) in the enumeration.

Syntax

HRESULT Reset(void);

Return Value

Returns S_OK, which indicates success.

IEnumMediaTypes::Skip

IEnumMediaTypes Interface

Skips a specified number of elements in the enumeration sequence.

Syntax

HRESULT Skip(
    ULONG cMediaTypes);

Parameters

cMediaTypes
[in] Number of media type elements to skip.

Return Value

Returns one of the following HRESULT values.

E_INVALIDARG No additional media types remain in the enumeration list.

S_FALSE Fewer media types were skipped than requested, because not that many remained in the list.

S_OK Success.

VFW_E_ENUM_OUT_OF_SYNC The enumerator has become invalid. For more information, see Remarks.

Remarks

If the list of available media types changes, it will no longer be consistent with the state of the enumerator, in which case this method will return VFW_E_ENUM_OUT_OF_SYNC. You should discard any data obtained from previous calls to the enumerator, because it might be invalid, and update the enumerator by calling the Reset method. You can then call the Skip method safely.

E_OUTOFMEMORY	Insufficient memory.
E_POINTER	Null pointer argument.
S_OK	Success.
VFW_E_ENUM_OUT_OF_SYNC	The enumerator has become invalid. For more information, see Remarks.

E_INVALIDARG	Invalid argument.
E_POINTER	Null pointer argument.
S_FALSE	Fewer media types were retrieved than requested.
S_OK	Success.
VFW_E_ENUM_OUT_OF_SYNC	The enumerator has become invalid. For more information, see Remarks.

E_INVALIDARG	No additional media types remain in the enumeration list.
S_FALSE	Fewer media types were skipped than requested, because not that many remained in the list.
S_OK	Success.
VFW_E_ENUM_OUT_OF_SYNC	The enumerator has become invalid. For more information, see Remarks.