CEnumPins Class

CEnumPins class hierarchy

The CEnumPins class supports the IEnumPins enumeration interface by calling CBaseFilter methods. The CBaseFilter class supports the IBaseFilter::EnumPins method. Each time one of this interface's methods is called, the CBaseFilter class checks to see if the pins that it enumerates have changed; it does this by calling CBaseFilter::GetPinVersion and matching the version the filter is keeping with the version that it stores during construction.

If a pin enumerator becomes stale, there is no mechanism for resynchronizing it with the filter. The user must release the interface and retrieve another one.

Because the enumeration operation is likely to fail if the pin version changes (indicating that the filter might have added or removed pins), all member functions in this class check the version by calling a private member function, which calls the owning filter's CBaseFilter::GetPinVersion member function. These member functions then return VFW_E_ENUM_OUT_OF_SYNC if the version has changed. This should always work unless the filter has overridden CBaseFilter::GetPinVersion to do something unexpected.

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

CEnumPins Constructs a CEnumPins object.

Implemented IUnknown Methods

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

Implemented IEnumPins Methods

Clone Makes a copy of the enumerator.
Next Retrieves the next set of pins after the current position.
Reset Sets the current position back to the beginning.
Skip Skips over one or more entries in the enumerator.

CEnumPins::AddRef

CEnumPins Class

Increments the reference count for the calling interface on an object.

Syntax

ULONG AddRef(void);

Return Value

Returns an integer from 1 to n, the value of the new reference count.

Remarks

This member function implements the IUnknown::AddRef method.

CEnumPins::CEnumPins

CEnumPins Class

Constructs a CEnumPins object.

Syntax

CEnumPins(
    CBaseFilter *pFilter,
    CEnumPins *pEnumPins
);

Parameters

pFilter
Pointer to the filter on which to enumerate the pins.
pEnumPins
Returned pointer to an IEnumPins interface object.

Return Value

No return value.

CEnumPins::Clone

CEnumPins Class

Makes a copy of the enumerator. This enables the calling application to retain two positions in the list of pins.

Syntax

HRESULT Clone(
    IEnumPins **ppEnum
);

Parameters

ppEnum
Address of a pointer to the new enumerator that is a copy of this enumerator.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IEnumPins::Clone method.

CEnumPins::Next

CEnumPins Class

Retrieves the next set of pins after the current position.

Syntax

HRESULT Next(
    ULONG cPins,
    IPin **ppPins,
    ULONG *pcFetched
);

Parameters

cPins
Number of pins to place.
ppPins
Address of a pointer to the array in which to place the interface pointers.
pcFetched
Pointer to the actual number of pins placed in the array.

Return Value

Returns an HRESULT value.

Remarks

This member function retrieves the specified number of IPin interfaces, starting at the current position in the enumeration, and places pointers to them in the specified array. The function implements the IEnumPins::Next method. The derived class is responsible for implementing CBaseFilter::GetPin, which this member function calls to retrieve the next pin.
Because this member function returns one or more interfaces that have had their reference counts incremented, the caller of this member function must be sure to release the interfaces by calling IUnknown::Release on the interfaces when done with them.

CEnumPins::QueryInterface

CEnumPins Class

Retrieves a pointer to a specified interface on a component to which a client currently holds an interface pointer. This method must call IUnknown::AddRef on the pointer it returns.

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 object doesn't support the interface specified in iid, 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 IEnumPins interface.

CEnumPins::Release

CEnumPins 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.

CEnumPins::Reset

CEnumPins Class

Resets the enumerator to the beginning so that the next call to the IEnumPins::Next method will return, at a minimum, the first pin of the filter.

Syntax

HRESULT Reset(void);

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IEnumPins::Reset method.

CEnumPins::Skip

CEnumPins Class

Skips the next specified number of pins.

Syntax

HRESULT Skip(
    ULONG cPins
);

Parameters

cPins
Number of pins to skip.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IEnumPins::Skip method. This member function affects the next call to the IEnumPins::Next method.

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

Clone	Makes a copy of the enumerator.
Next	Retrieves the next set of pins after the current position.
Reset	Sets the current position back to the beginning.
Skip	Skips over one or more entries in the enumerator.