IEnumConnectionPoints

This interface enumerates connection points. Connectable objects support the following features:

• Outgoing interfaces, such as event sets
• The ability to enumerate the IIDs of the outgoing interfaces
• The ability to connect and disconnect sinks to the object for those outgoing IIDs
• The ability to enumerate the connections that exist to a particular outgoing interface

When to Implement

To support connectable objects, you need to provide four related interfaces:

• IConnectionPointContainer
• IEnumConnectionPoints
• IConnectionPoint
• IEnumConnections

The IConnectionPointContainer interface indicates the existence of the outgoing interfaces. It provides access to an enumerator sub-object with the IEnumConnectionPoints interface. It also provides a connection point sub-object with the IConnectionPoint interface. The IConnectionPoint interface provides access to an enumerator sub-object with the IEnumConnections interface.

The connection point is a separate sub-object to avoid circular reference counting problems.

A connectable object can be asked to enumerate its supported connection points through IConnectionPointContainer::EnumConnectionPoints. The resulting enumerator returned from this method implements the interface IEnumConnectionPoints, through which a client can access all the individual connection point sub-objects supported within the connectable object itself, where each connection point implements IConnectionPoint.

When enumerating connections through IEnumConnectionPoints, the enumerator is responsible for calling IUnknown::AddRef, and the caller is responsible for later calling IUnknown::Release when those pointers are no longer needed.

When to Use

Use the IEnumConnectionPoints interface to enumerate all the supported connection points for each outgoing IID.

The prototypes of the methods are as follows:

HRESULT Next(
  ULONG cConnections,  //[in]Number of IConnectionPoint values 
                       // returned in rgpcn array
  IConnectionPoint **rgpcn,
                       //[out]Array to receive enumerated connection 
                       // points
  ULONG *pcFetched     //[out]Pointer to the actual number of 
                       // connection points returned in rgpcn array
);
 
HRESULT Skip(
  ULONG cConnections  //[in]Number of elements to skip
);
 
HRESULT Reset(void);
 
HRESULT Clone(
  IEnumConnectionPoints **ppEnum  //[out]Address of output variable 
                                  // that receives the 
                                  // IEnumConnectionPoints interface 
                                  // pointer
);
 

Remarks

IEnumConnectionPoints::Next

Enumerates the next cConnections elements (IConnectionPoint pointers) in the enumerator's list, returning them in rgpcn along with the actual number of enumerated elements in pcFetched. The enumerator calls IConnectionPoint::AddRef for each returned pointer in rgpcn, and the caller is responsible for calling IConnectionPoint::Release through each pointer when those pointers are no longer needed.

E_NOTIMPL is not allowed as a return value. If an error value is returned, no entries in the rgpcn array are valid on exit and require no release.

IEnumConnectionPoints::Skip

Instructs the enumerator to skip the next cConnections elements in the enumeration so that the next call to IEnumConnectionPoints::Next will not return those elements.

IEnumConnectionPoints::Reset

Instructs the enumerator to position itself at the beginning of the list of elements.

There is no guarantee that the same set of elements will be enumerated on each pass through the list, nor will the elements necessarily be enumerated in the same order. The exact behavior depends on the collection being enumerated. It is too expensive for some collections, such as files in a directory, to maintain a specific state.

IEnumConnectionPoints::Clone

Creates another connection point enumerator with the same state as the current enumerator to iterate over the same list. This method makes it possible to record a point in the enumeration sequence in order to return to that point at a later time.

The caller must release this new enumerator separately from the first enumerator.

QuickInfo

  Windows NT: Use version 4.0 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in ocidl.h.

See Also

IConnectionPoint, IConnectionPointContainer, IEnumConnections, IEnumXxxx