Associates a containerÆs document view site with a documentÆs document view object.

HRESULT SetInPlaceSite(

    IOleInPlaceSite

 * pIPSite        // Pointer to document view siteÆs IOleInPlaceSite interface           
                                                                                                            

   );                                                                                                       
                                                                                                            

pIPSite

[in] Pointer to the document view siteÆs IOleInPlaceSite interface. Can be NULL, in which case the document view object loses all asociation with the container.

Return Value

S_OK

A document view site was successfully associated (or disassociated if pIPSite is NULL) with a document view object.

E_FAIL

An unspecified error occurred.

Remarks

As part of activating a document object, a container must hand the object a pointer to the containerÆs implementation of IOleInPlaceSite. This pointer designates the document view site that is to be associated with the particular view of the document to be activated.

A container normally passes this pointer in response to a documentÆs request to be activated. A document makes such a request by calling IOleDocumentSite::ActivateMe and handing the container a pointer to the view to be activated. The container, in turn, uses this pointer to call IOleDocumentView::SetInPlaceSite.

Notes to Callers

If the container is requesting creation and activation of a new instance of a document object, rather than merely the activation of a loaded instance of a document object, the semantics of SetInPlaceSite are encompassed in the pIPSite argument of IOleDocument::CreateView. Therefore, an explicit call to SetInPlaceSite is unnecessary.

Notes to Implementers

If this method is called on a view that already has an associated view site, the view must do some housekeeping in preparation for activating itself in the new site. First, the view must deactivate itself in the current site. Second, the view must release its pointer to that site. Third, if the new IOleInPlaceSite pointer is not NULL, the view should both save the pointer and call AddRef on it. Having completed these steps, the view should then wait for the container to tell it when to activate itself in the new view site.

A document view must implement this method completely. Therefore E_NOTIMPL is not an acceptable return value.

See Also

IOleDocumentView::GetInPlaceSite