IEnumSTATDATA

The IEnumSTATDATA interface is used to enumerate through an array of STATDATA structures, which contain advisory connection information for a data object. IEnumSTATDATA has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

IEnumSTATDATA is implemented to enumerate advisory connections. Most applications will not implement this directly, but will use the OLE-provided implementation. Pointers to this implementation are available in two ways:

• In a data object, call CreateDataAdviseHolder to get a pointer to the OLE data advise holder object, and then, to implement IDataObject::EnumDAdvise, call IDataAdviseHolder::EnumAdvise, which creates the enumeration object and supplies a pointer to the implementation of IEnumSTATDATA.
• In a compound document object, call CreateOLEAdviseHolder to get a pointer to the OLE advise holder object, and then, to implement IOleObject::EnumAdvise, call IOleAdviseHolder::EnumAdvise, which creates the enumeration object and supplies a pointer to the implementation of IEnumSTATDATA.

When to Use

Containers usually call methods that return a pointer to IEnumSTATDATA so the container can use its methods to enumerate the existing advisory connections, and use this information to instruct an object to release each of its advisory connections prior to closing down. IDataObject::EnumDAdvise, IDataAdviseHolder::EnumAdvise, IOleAdviseHolder::EnumAdvise, and IOleCache::EnumCache methods all supply a pointer to IEnumSTATDATA.

The prototypes of the methods are as follows:

HRESULT Next(
  ULONG celt,           
  STATDATA * rgelt,     
  ULONG * pceltFetched  
);
 
HRESULT Skip(
  ULONG celt  
);
 
HRESULT Reset(void)
 
HRESULT Clone(
  IEnumSTATDATA ** ppenum  
);
 

QuickInfo

  Windows NT: Use version 3.1 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in objidl.h.

See Also

STATDATA, IEnumXXXX, IOleCache::EnumCache, IDataObject::EnumDAdvise, IDataAdviseHolder::EnumAdvise, IOleObject::EnumAdvise