CEnumMediaTypes Class

CEnumMediaTypes class hierarchy

The CEnumMediaTypes class provides the mechanism for enumerating the pin's preferred media types. Its constructor must be passed to an object from a class derived from CBasePin. It uses the virtual member function GetMediaType to retrieve each of the media types in turn. It also uses the pin's CBasePin::GetMediaTypeVersion member function to determine if the number or type of media types has changed.

The base pin class does not support dynamic media type changes. CBaseFilter::GetPinVersion always returns the same value, for example.

The media type enumerator must fill in a list of pointers to media type structures. The memory for those media type structures must be released by the callers when they have finished with it. However, the memory must not be allocated from any language-specific heap; otherwise, problems might occur between a filter written in C and another written in C++. For this reason, the base classes provide generic functions (not member functions of a class) to create and delete media types: CreateMediaType and DeleteMediaType. These manage memory allocation from the task allocator.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Member Functions

CEnumMediaTypes Constructs a CEnumMediaTypes object.

Implemented IUnknown Methods

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

Implemented IEnumMediaTypes Methods

Clone Creates a duplicate CEnumMediaTypes object with the same state.
Next Retrieves the next media type after the current position.
Reset Sets the current position back to the beginning.
Skip Skips over one or more entries in the enumerator.

CEnumMediaTypes::AddRef

CEnumMediaTypes Class

Increments the reference count for the calling interface on an object. This function should be called for every new copy of a pointer to an interface on a given object.

Syntax

ULONG AddRef(void);

Return Value

Returns an integer from 1 to n, the value of the new reference count. This information is meant to be used for diagnostic/testing purposes only, because in certain situations the value might be unstable.

Remarks

This member function implements the IUnknown::AddRef method.

CEnumMediaTypes::CEnumMediaTypes

CEnumMediaTypes Class

Constructs a CEnumMediaTypes object.

Syntax

CEnumMediaTypes(
    CBasePin *pPin,
    CEnumMediaTypes *pEnumMediaTypes
);

Parameters

pPin
Pointer to the pin on which the enumeration is to be performed.
pEnumMediaTypes
Pointer to the instantiated CEnumMediaTypes object.

Return Value

No return value.

Remarks

This is a standard class constructor.

CEnumMediaTypes::Clone

CEnumMediaTypes Class

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

Syntax

HRESULT Clone(
    IEnumMediaTypes **ppEnum
);

Parameters

ppEnum
Address of a pointer to the new copy of the enumerator.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IEnumMediaTypes::Clone method.

CEnumMediaTypes::Next

CEnumMediaTypes Class

Retrieves the specified number of items in the enumeration sequence.

Syntax

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

Parameters

cMediaTypes
Number of media types to place.
ppMediaTypes
Address of a pointer to an array in which to place the next media type or types.
pcFetched
Pointer to the actual count passed.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IEnumMediaTypes::Next method. To call this method, pass a pointer's address to a media type. The base class implementation relies on the existence of an overridden CBasePin::GetMediaType member function in the derived class that will provide the next media type.
Free each media type acquired by calling DeleteMediaType, which will free the format block and the media type itself.

CEnumMediaTypes::QueryInterface

CEnumMediaTypes Class

Retrieves a pointer to a specified interface on a component to which a client currently holds an interface pointer.

Syntax

HRESULT QueryInterface(
    REFIID iid,
    void **ppvObject
);

Parameters

iid
Interface identifier (IID) of the interface being requested.
ppvObject
Address of a pointer to the object on return. If the interface specified in iid is not supported by the object, ppvObject is set to NULL.

Return Value

Returns S_OK if the interface is supported, S_FALSE if not.

Remarks

This member function implements the IUnknown::QueryInterface method and passes out references to the IEnumMediaTypes interface. Override this class to return other interfaces on the object in the derived class.

CEnumMediaTypes::Release

CEnumMediaTypes Class

Decrements the reference count for the calling interface on an object. If the reference count on the object falls to zero, the object is freed from memory.

Syntax

ULONG Release(void);

Return Value

Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.

Remarks

This member function implements the IUnknown::Release method.

CEnumMediaTypes::Reset

CEnumMediaTypes Class

Resets the enumerator to the beginning so that the next call to the IEnumMediaTypes::Next method will return, at a minimum, the first media type in the enumeration.

Syntax

HRESULT Reset(void);

Return Value

Returns S_OK if successful; otherwise, returns S_FALSE.

Remarks

This member function implements the IEnumMediaTypes::Reset method.

CEnumMediaTypes::Skip

CEnumMediaTypes Class

Skips a specified number of elements in the enumeration sequence.

Syntax

HRESULT Skip(
    ULONG cMediaTypes
);

Parameters

cMediaTypes
Number of media type elements to skip.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IEnumMediaTypes::Skip method.

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

Clone	Creates a duplicate CEnumMediaTypes object with the same state.
Next	Retrieves the next media type after the current position.
Reset	Sets the current position back to the beginning.
Skip	Skips over one or more entries in the enumerator.