IOleDocument::CreateView

Creates a document view object in the caller's process and obtains 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
                     //Address of output variable that receives the 
                     // IOleDocumentView interface pointer
);

Parameters

pIPSite: [in] Pointer to the view site object to be associated with the new document view object. May be NULL, as when the view is contained in 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. If NULL, the document object initializes the new document view object with a default state.
dwReserved: [in] Reserved for future use. Must be zero.
ppView: [out] Address of IOleDocumentView* pointer variable that receives the interface pointer to the new document view object. When successful, the caller is responsible for calling Release on the *ppview pointer when the view object is no longer needed.

Return Values

This method supports the standard return values E_FAIL, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK: The view object was created successfully.
E_POINTER: The address in ppView is NULL.

Remarks

A document object container's document site calls IOleDocument::CreateView to instruct a document object to create a new view of itself in the container's process, either from default data or using the contents of an existing stream.

Calling CreateView does not cause the new view to display itself. To do so requires a call to either IOleDocumentView::Show or IOleDocumentView::UIActivate.

Notes to Callers

CreateView is normally called by 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 passes a NULL 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 used to initialize the requested view. If the container passes a NULL stream pointer, 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; E_NOTIMPL is not an acceptable return value.

If pIPSite is not NULL, then the document object should pass the pointer to the new view in a call to IOleDocumentView::SetInPlaceSite. If pIPSite is NULL, the caller is responsible for making this same call. In addition, if pstm is not NULL, then the document object should initialize the view object by passing pstm in a call 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 on this pointer when it is no longer needed.

QuickInfo

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