IOleObject::GetClientSite  5P...WJ

Obtains a pointer to an embedded object s client site.

HRESULT GetClientSite(

Parameter

ppClientSite

[out] Indirect pointer to an IOleClientSite interface on the object s client site. If an object does not yet know its client site, or an error has occurred, this parameter must be set to NULL. Each time an object receives a call to GetClientSite, it must increase the reference count on the pointer the method returns. It is the caller s responsibility to call Release when it is done with the pointer.

Return Value

S_OK

Client site pointer returned successfully.

Remarks

Link clients most commonly call the IOleObject::GetClientSite method in conjunction with the IOleClientSite::GetContainer method to traverse a hierarchy of nested objects. A link client calls IOleObject::GetClientSite to get a pointer to the link source s client site. The client then calls IOleClientSite::GetContainer to get a pointer to the link source s container. Finally, the client calls IOleContainer::QueryInterface to get IOleObject and IOleObject::GetClientSite to get the container s client site within its container. By repeating this sequence of calls, the caller can eventually retrieve a pointer to the master container in which all the other objects are nested.

Notes to Callers

The returned client-site pointer will be NULL if an embedded object has not yet been informed of its client site. This will be the case with a newly loaded or created object when a container has passed a NULL client-site pointer to one of the object-creation helper functions but has not yet called IOleObject::SetClientSite as part of initializing the object.

See Also

IOleObject::SetClientSite5OQXLV_