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.

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

Top of Page