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

The resulting enumerator returned by this mtehod implements the interface IEnumOleDocumentViews through which a client can access all the individual document view objects supported by the document object itself, where each view implements IOleDocumentView.

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 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, it will return a pointer to that view. If the document object supports two or more views, it will return 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 caller is responsible for calling IOleDocumentView::Release through 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 on exit and require no release.

cViews

[in] Specifies the number of IOleDocumentView pointers to return in the array pointed to by rgpView. This argument must be 1 if pcFetched is NULL.

rgpView

[out, max_is(cViews)] A pointer to a caller-allocated IOleDocumentView * array of size cViews in which to return the enumerated connection points. 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] A Indirect 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 such that the next call to IEnumOleDocumentViews::Next will not return those elements.

cViews

[in] Specifies the 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] A Indirect pointer to the IEnumOleDocumentViews interface for the newly created enumerator. The caller must release this enumerator separately from the one from which it was cloned.