IDataObject::EnumDAdvise

Creates an object that can be used to enumerate the current advisory connections.

HRESULT EnumDAdvise(

IEnumSTATDATA ** ppenumAdvise

//Indirect pointer

);

Parameter

ppenumAdvise: [out] Indirect pointer to the IEnumSTATDATA interface on the new enumerator object. If the supplied value is NULL, there are no connections to advise sinks at this time.

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK: The enumerator object is successfully instantiated or there are no connections.
OLE_E_ADVISENOTSUPPORTED: Advisory notifications are not supported by this object.

Remarks

The enumerator object created by this method implements the IEnumSTATDATA interface, one of the standard enumerator interfaces that contain the Next, Reset, Clone, and Skip methods. IEnumSTATDATA permits the enumeration of the data stored in an array of STATDATA structures. Each of these structures provides information on a single advisory connection, and includes FORMATETC and ADVF information, as well as the pointer to the advise sink and the token representing the connection.

Notes to Callers

After getting a pointer through this method, the data object can call the appropriate enumeration methods. While the enumeration is in progress, the effect of adding more advisory connections on the subsequent enumeration is undefined.

Notes to Implementers

It is recommended that you use the OLE data advise holder object to handle advisory connections. With the pointer obtained through a call to CreateDataAdviseHolder, implementing IDataObject::EnumDAdvise becomes a simple matter of delegating the call to IDataAdviseHolder::EnumAdvise. This creates the enumerator and supplies the pointer to the OLE implementation of IEnumSTATDATA. At that point, you can call its methods to enumerate the current advisory connections.