IEnumOleDocumentViews

The IEnumOleDocumentViews interface is used to enumerate the views supported by a document object. IEnumOleDocumentViews has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For general information on these methods, see IEnumXXXX.

When to Implement

Implement IEnumOleDocumentViews on enumerator objects associated with document objects that support more than one view of their data.

When to Use

Use the IEnumOleDocumentViews interface to enumerate all the views supported by a document object. The usual procedure is to first call IOleDocument::EnumViews. If the document object supports only one view, EnumViews will obtain a pointer to that view. If the document object supports two or more views, EnumViews will obtain a pointer to IEnumOleDocumentViews. Using this pointer, the container can then ask the document object to enumerate the views it supports.

The prototypes of the methods are as follows:

HRESULT Next(
  ULONG cViews,                 
  IOleDocumentView * rgpView,   
  [out]ULONG * pcFetched        
);
 
HRESULT Skip(
  [in]ULONG cViews  
);
 
HRESULT Reset(void)
 
HRESULT Clone(
  [out]IEnumOleDocumentViews ** ppenum  
);
 

Remarks

IEnumOleDocumentViews::Next

Enumerates the next cViews elements in the enumerator's list, returning them in rgpView, along with the actual number of enumerated elements in pcFetched. The enumerator object is responsible for calling IOleDocumentView::AddRef, and the caller is responsible for calling IOleDocumentView::Release, on each pointer returned in rgpView.

E_NOTIMPL is not allowed as a return value. If an error value is returned, no entries in the rgpView array are valid and no calls to Release are required.

cViews

[in] The number of IOleDocumentView pointers to be written to the array pointed to by rgpView. If pcFetched is NULL, this argument must be 1.

rgpView

[out, max_is(cViews)] Pointer to a caller-allocated IOleDocumentView * array of size cViews, to which the enumerated connection points are written. The caller is responsible for calling IOleDocumentView::Release through each pointer enumerated into the array once this method returns successfully. If cViews is greater than 1, the caller must also pass a non-NULL pointer passed to pcFetched to know how many pointers to release.

pcFetched

[out] Pointer to the actual number of views enumerated in rgpView. This argument can be NULL, in which case the cViews argument must be 1.

IEnumOleDocumentViews::Skip

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

cViews

[in] Number of elements to skip in the enumeration.

IEnumOleDocumentViews::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 this condition.

IEnumOleDocumentViews::Clone

Creates another view enumerator with the same state as the current enumerator, which iterates over the same list. This makes it possible to record a point in the enumeration sequence in order to return to that point at a later time.

ppEnum

[out] Pointer to the IEnumOleDocumentViews interface pointer on the newly created enumerator. The caller must release this enumerator separately from the one from which it was cloned.

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in docobj.h.