IObjectWithSite Interface

IID_IObjectWithSite

{FC4801A3-2BA9-11CF-A229-00AA003D7352}

The IObjectWithSite interface provides a simple way to support communication between an object and its site in the container.

Often an object needs to communicate directly with a container site object and, in effect, manage the site object itself. Outside of IOleObject::SetClientSite, there is no generic means through which an object becomes aware of its site. IObjectWithSite provides simple objects with a simple siting mechanism (lighter than IOleObject) This interface should only be used when IOleObject is not already in use.

Through IObjectWithSite, a container can pass the IUnknown pointer of its site to the object through IObjectWithSite::SetSite. Callers can also retrieve the latest site passed to IObjectWithSite::SetSite through IObjectWithSite::GetSite. This latter method is included as a hooking mechanism, allowing a third party to intercept calls from the object to the site.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IObjectWithSite Methods

Description

SetSite

Provides the site's IUnknown pointer to the object being managed.

GetSite

Retrieves the last site set with IObjectWithSite::SetSite.

QueryInterface

FUNCTION IObjectWithSite_QueryInterface ( _

  BYVAL pthis AS DWORD PTR _

, BYREF riid AS GUID _

, BYREF ppvObj AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[0] USING IObjectWithSite_QueryInterface (pthis, riid, ppvObj) TO HRESULT
  FUNCTION = HRESULT
 

END FUNCTION

AddRef

FUNCTION IObjectWithSite_AddRef ( _

  BYVAL pthis AS DWORD PTR _

  ) AS DWORD
 

  LOCAL DWRESULT AS LONG
  CALL DWORD @@pthis[1] USING IObjectWithSite_AddRef (pthis) TO DWRESULT
  FUNCTION = DWRESULT
 

END FUNCTION

Release

FUNCTION IObjectWithSite_Release ( _

  BYVAL pthis AS DWORD PTR _

  ) AS DWORD
 

  LOCAL DWRESULT AS DWORD
  CALL DWORD @@pthis[2] USING IObjectWithSite_Release (pthis) TO   DWRESULT
  FUNCTION = DWRESULT
 

END FUNCTION

SetSite

FUNCTION IObjectWithSite_SetSite ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pUnkSite AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[3] USING IObjectWithSite_SetSite (pthis, pUnkSite) TO HRESULT
  FUNCTION = HRESULT
 

END FUNCTION

Example

FUNCTION AtlSetChildSite ( _

  BYVAL punkChild AS DWORD _

, BYVAL pUnkParent AS DWORD _

) AS LONG
 

  LOCAL hr AS LONG

  LOCAL pChildSite AS DWORD

  LOCAL IID_IObjectWithSite AS GUID

  IID_IObjectWithSite = GUID$("{FC4801A3-2BA9-11CF-A229-00AA003D7352}")

  IF punkChild = %NULL THEN FUNCTION = %E_POINTER : EXIT FUNCTION

  hr = IObjectWithSite_QueryInterface(punkChild, IID_IObjectWithSite, pchildSite)

  IF SUCCEEDED(hr) THEN

     IF pChildSite <> %NULL THEN

        hr = IObjectWithSite_SetSite(pchildSite, punkParent)

        IObjectWithSite_Release pchildSite

     END IF

  END IF
  FUNCTION = hr
 

END FUNCTION

GetSite

FUNCTION IObjectWithSite_GetSite ( _

  BYVAL pthis AS DWORD PTR _

, BYREF riid AS GUID _

, BYREF ppvSite AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IObjectWithSite_GetSite (pthis, riid, ppvSite) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION