## CEnumPins Class

This 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

Name | Description
CEnumPins | Constructs a CEnumPins object.

Implemented IUnknown Methods

Name | Description
AddRef | Increments the reference count.
QueryInterface | Returns pointers to supported interfaces.
Release | Decrements the reference count.

Implemented IEnumPins Methods

Name | Description
Clone | Creates a duplicate CEnumPins object with the same initial state.
Next | Returns the next pin 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.

ULONG AddRef(void);

##### Return Values

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

Constructor for the CEnumPins class.

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 Values

No return value.

###

CEnumPins::Clone

CEnumPins Class

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

HRESULT Clone(
IEnumPins ** ppEnum
);

##### Parameters

ppEnum
  New enumerator that is a copy of this enumerator.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function implements the IEnumPins::Clone method.

###

CEnumPins::Next

CEnumPins Class

Places pointers to IPin interfaces into the specified array.

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

##### Parameters

cPins
  Number of pins to place.
ppPins
  Array in which to place the interface pointers.
pcFetched
  Actual number of pins placed in the array.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member 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.

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

##### Parameters

iid
  Specifies the IID of the interface being requested.
ppvObject
  Receives a pointer to an interface pointer to the object on return. If the interface specified in iid is not supported by the object, ppvObject is set to NULL.

##### Return Values

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.

ULONG Release(void);

##### Return Values

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.

HRESULT Reset(void);

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function implements the IEnumPins::Reset method.

###

CEnumPins::Skip

CEnumPins Class

Skips the next specified number of pins.

HRESULT Skip(
ULONG cPins
);

##### Parameters

cPins
  Number of pins to skip.

##### Return Values

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.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.