IEnumConnections  1MGN1NJ

This interface enumerates the current connections for a connectable object. 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:

    IConnectionPointContainer1CDHQR

    IEnumConnectionPoints2MCWRR5

    IConnectionPointG5BBH

    IEnumConnections73UI6N

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.

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(

HRESULT Skip(

HRESULT Reset(void);

HRESULT Clone(

Remarks

IEnumConnections::Next

Enumerates the next cConnections elements (i.e., CONNECTDATA structures) in the enumerator s list, returning them in rgpcd along with the actual number of enumerated elements in pcFetched.

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.

IEnumConnections::Skip

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

IEnumConnections::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. 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.

IEnumConnections::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.

See Also