IOleObject::SetClientSite

Windows Mobile 6.5
A version of this page is also available for
4/8/2010

This method informs an embedded object of its display location, called a "client site," within its container.


HRESULT SetClientSite( 
  IOleClientSite* pClientSite
);

pClientSite

[in] Pointer to the IOleClientSite interface on the container application's client-site.

This method supports the standard return value E_UNEXPECTED, as well as S_OK, which indicates that the client site successfully set.

Within a compound document, each embedded object has its own client site, which is the place where it is displayed and through which it receives information about its storage, user interface, and other resources.

SetClientSite is the only method enabling an embedded object to obtain a pointer to its client site.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

A container can notify an object of its client site at the time the object is created or when the object is initialized.

When creating or loading an object, a container can pass a client-site pointer (along with other parameters) to OleCreate, a helper function. This helper function loads an object handler for the new object and calls 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 might want your container to pass a NULL client-site pointer to the helper function.

The NULL pointer says that no client site is available and 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.

Implementation consists simply of incrementing the reference count on, and storing, the pointer to the client site.

HeaderOleidl.h, oleidl.idl
Libraryoleaut32.lib, uuid.lib
Windows Embedded CEWindows CE 2.0 and later
Windows MobileWindows Mobile Version 5.0 and later

Community Additions

Show: