IOleDocument::CreateView

Creates a document view object in the caller’s process and returns a pointer to that object’s IOleDocumentView interface.

HRESULT CreateView(

IOleInPlaceSite * pIPSite,

// Pointer to container’s view-site object

IStream * pstm,

// Pointer to a stream object

DWORD dwReserved,

// Reserved for future use

IOleDocumentView * ppView

// Indirect pointer to the new document view object

);

Parameters

pIPSite: [in] Pointer to the view-site object to be associated with the new document view object. May be NULL, as when creating a new, uninitialized document object, in which case the caller must initialize the view with a subsequent call to IOleDocumentView::SetInPlaceSite.
pstm: [in] Pointer to a stream containing data from which the new document view object should initialize itself. Normally will be NULL when the specified view is for a new, uninitialized document object. If NULL, the document object initializes the new document view object with a default state.
dwReserved: [in] Reserved for future use. In the future this parameter could be used to specify the type of view that needs to be created. Currently there are no defined values for this argument.
ppView: [out] Indirect pointer to the new document view object. If CreateView succeeds, the caller is responsible for calling Release through this pointer when the view object is no longer needed.

Return Values

S_OK: The view was created successfully.
E_POINTER: The address in ppView is NULL.
E_OUTOFMEMORY: Out of memory.
E_UNEXPECTED: An unexpected error occurred.
E_FAIL: An unspecified error occurred.

Remarks

A document-object container’s document site calls IOleDocumentView::CreateView to instruct a document object to create a new view of itself in the container’s process, either from scratch or by using the contents of an existing stream.

Calling CreateView does not cause the new view to display itself. To do so, the view must wait for calls to either IOleDocumentView::Show or IOleDocumentView::UIActivate.

Notes to Callers

The call to CreateView normally occurs in the container’s implementation of IOleDocumentSite::ActivateMe. If a document object passes an IOleDocumentView pointer in its call to ActivateMe, the container has no need to call CreateView and instead can call IOleDocumentView::SetInPlaceSite, followed by AddRef. If a document object returns a NULL view pointer in its call to ActivateMe, then the container calls CreateView to retrieve a view pointer.

The container has the option of passing a pointer to a stream containing data to be used to initialize the requested view. If the container passes a NULL stream pointer, then the document object will initialize the new view using its default settings.

Notes to Implementers

This method must be completely implemented for any document object. Therefore E_NOTIMPL is not an acceptable return value.

If pIPSite is non-NULL, then the document object should pass the pointer to the new view through IOleDocumentView::SetInPlaceSite. If pIPSite is NULL, the caller is responsible for making this same call. In addition, if pstm is non-NULL, then the object should initialize the view object by passing pstm to IOleDocumentView::ApplyViewState.

As with all new interface pointers, CreateView should call AddRef on the pointer in *ppView before returning. The caller is responsible for calling Release through this pointer when it is no longer needed.

IOleInPlaceSite * pIPSite,	// Pointer to container’s view-site object
IStream * pstm,	// Pointer to a stream object
DWORD dwReserved,	// Reserved for future use
IOleDocumentView * ppView	// Indirect pointer to the new document view object
);