This interface enumerates the current connections for a connectable object. Connectable objects support the following features:
To support connectable objects, you need to provide four related interfaces:
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.
Any individual connection point can support enumeration of its currently known connections through IConnectionPoint::EnumConnections. The enumerator created by this method implements the interface IEnumConnections which deals with the type CONNECTDATA. Each CONNECTDATA structure contains the IUnknown of a connected sink and the dwConnection that was returned by IConnectionPoint::Advise when that sink was connected. When enumerating connections through IEnumConnections, the enumerator is responsible for calling IUnknown::AddRef through the pointer in each enumerated structure, and the caller is responsible to later call IUnknown::Release when those pointers are no longer needed.
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 CONNECTDATA structures
// returned in rgpcd
CONNECTDATA **rgpcd, //[out]Array to receive enumerated
// CONNECTDATA structures
ULONG *pcFetched //[out]Pointer to actual number of
// CONNECTDATA structures
);
HRESULT Skip(
ULONG cConnections //[in]Number of elements to skip
);
HRESULT Reset(void);
HRESULT Clone(
IEnumConnections **ppEnum //[out]Address of output variable that
// receives the IEnumConnections interface
// pointer
);
The caller is responsible for calling CONNECTDATA.pUnk->Release
for each element in the array once this method returns successfully. If cConnections is greater than one, the caller must also pass a non-NULL pointer to pcFetched to get the number of pointers it has to release.
E_NOTIMPL is not allowed as a return value. If an error value is returned, no entries in the rgpcd array are valid on exit and require no release.
There is no guarantee that the same set of elements will be enumerated on each pass through the list. It depends on the collection being enumerated. It is too expensive for some collections, such as files in a directory, to maintain a specific state.
The caller must release this new enumerator separately from the first enumerator.
Windows NT: Use version 4.0 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in ocidl.h.
CONNECTDATA, IConnectionPoint, IConnectionPointContainer, IEnumConnectionPoints, IEnumXxxx