IOleObject::SetClientSite
Informs an
embedded object of its display location, called a client site, within its
container.
HRESULT SetClientSite(
|
IOleClientSite
*pClientSite |
//Pointer to an embedded object s client site |
|
); |
|
Parameter
pClientSite
[in] Pointer
to the IOleClientSite interface on the container application s
client-site.
Return Values
This method
supports the standard return value E_UNEXPECTED, as well as the following:
S_OK
Client site
successfully set.
Remarks
Within a
compound document, each embedded object has its own client site the place where
it is displayed and through which it receives information about its storage,
user interface, and other resources. IOleObject::SetClientSite is the
only method enabling an embedded object to obtain a pointer to its client site.
Notes to Callers
A container
can notify an object of its client site either at the time the object is
created or, subsequently, when the object is initialized.
When creating
or loading an object, a container may pass a client-site pointer (along with
other arguments) to one of the following helper functions: OleCreate, OleCreateFromFile, OleCreateFromData or OleLoad. These helper functions
load an object handler for the new object and call IOleObject::SetClientSite
on the container s behalf before returning a pointer to the new object.
Passing a
client-site pointer informs the object handler that the client site is ready to
process requests. If the client site is unlikely to be ready immediately after
the handler is loaded, you may want your container to pass a NULL client-site
pointer to the helper function. The NULL pointer says that that no client site
is available and thereby defers notifying the object handler of the client site
until the object is initialized. In response, the helper function returns a
pointer to the object, but upon receiving that pointer the container must call SetClientSite
as part of initializing the new object.
Notes to Implementers
Implementation
consists simply of incrementing the reference count on, and storing, the
pointer to the client site.
See Also