IOleObject::GetClientSite

Obtains a pointer to an embedded object's client site.

HRESULT GetClientSite(
  IOleClientSite **ppClientSite  //Address of output variable that 
                                 // receives the IOleClientSite 
                                 // interface pointer
);

Parameter

ppClientSite: [out] Address of IOleClientSite* pointer variable that receives the interface pointer to the object's client site. If an object does not yet know its client site, or if an error has occurred, *ppClientSite must be set to NULL. Each time an object receives a call to GetClientSite, it must increase the reference count on *ppClientSite. It is the caller's responsibility to call Release when it is done with *ppClientSite.

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.

QuickInfo

  Windows NT: Use version 3.1 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in oleidl.h.