IEnumConnections

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:

• 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.

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(
  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
);
 

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.

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

CONNECTDATA, IConnectionPoint, IConnectionPointContainer, IEnumConnectionPoints, IEnumXxxx