IAdviseSink Interface

IID_IAdviseSink

{00000110-0000-0000-C000-000000000046}

The IAdviseSink interface enables containers and other objects to receive notifications of data changes, view changes, and compound-document changes occurring in objects of interest. Container applications, for example, require such notifications to keep cached presentations of their linked and embedded objects up-to-date. Calls to IAdviseSink methods are asynchronous, so the call is sent and then the next instruction is executed without waiting for the call's return.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IAdviseSink Methods

Description

OnDataChange

Advises that data has changed.

OnViewChange

Advises that view of object has changed.

OnRename

Advises that name of object has changed.

OnSave

Advises that object has been saved to disk.

OnClose

Advises that object has been closed.

IAdviseSink interface implementation

$IID_IAdviseSink = GUID$("{0000010f-0000-0000-c000-000000000046}")

UNION STGMEDIUMDATA
   hBitmap AS DWORD
   hMetaFilePict AS DWORD
   hEnhMetaFile AS DWORD
   hGlobal AS DWORD
   lpszFileName AS DWORD
   pstm AS DWORD
   pstg AS DWORD
END UNION

TYPE STGMEDIUM
   tymed AS DWORD
   tsmd AS STGMEDIUMDATA
   pUnkForRelease AS DWORD
END TYPE
 
TYPE DVTARGETDEVICE
   tdSize AS DWORD
   tdDriverNameOffset AS WORD
   tdDeviceNameOffset AS WORD
   tdPortNameOffset AS WORD
   tdExtDevmodeOffset AS WORD
   tdData(0) AS BYTE
END TYPE

TYPE FORMATETC
   cfFormat AS DWORD
   ptd AS DVTARGETDEVICE PTR
   dwAspect AS DWORD
   lindex AS LONG
   tymed AS DWORD
END TYPE

' ****************************************************************************************
' IAdviseSink interface
' ****************************************************************************************
TYPE IAdviseSinkVtbl
   ' IUnknown methods
   pQueryInterface         AS DWORD          ' // QueryInterface method
   pAddRef                 AS DWORD          ' // AddRef method
   pRelease                AS DWORD          ' // Release method
   ' IAdviseSink methods
   pOnDataChange           AS DWORD          ' // OnDataChange method
   pOnViewChange           AS DWORD          ' // OnViewChange method
   pOnRename               AS DWORD          ' // OnRename method
   pOnsave                 AS DWORD          ' // OnSave method
   pOnClose                AS DWORD          ' // OnClose method
   ' Custom data
   pVtblAddr               AS DWORD          ' // Address of the virtual table
   cRef                    AS DWORD          ' // Reference count
END TYPE
' ****************************************************************************************

' ****************************************************************************************
' Builds the IAdviseSink Virtual Table
' Returns a cookie that is a pointer to a IAdviseSinkVtbl structure.
' ****************************************************************************************
FUNCTION IAdviseSink_BuildVtbl () AS DWORD

   LOCAL pVtbl AS IAdviseSinkVtbl PTR
   LOCAL pUnk AS IAdviseSinkVtbl PTR

   pVtbl = HeapAlloc(GetProcessHeap(), %HEAP_ZERO_MEMORY, SIZEOF(@pVtbl))
   IF pVtbl = 0 THEN EXIT FUNCTION

   @pVtbl.pQueryInterface         = CODEPTR(IAdviseSink_QueryInterface)
   @pVtbl.pAddRef                 = CODEPTR(IAdviseSink_AddRef)
   @pVtbl.pRelease                = CODEPTR(IAdviseSink_Release)

   @pVtbl.pOnDataChange           = CODEPTR(IAdviseSink_OnDataChange)
   @pVtbl.pOnViewChange           = CODEPTR(IAdviseSink_OnViewChange)
   @pVtbl.pOnRename               = CODEPTR(IAdviseSink_OnRename)
   @pVtbl.pOnSave                 = CODEPTR(IAdviseSink_OnSave)
   @pVtbl.pOnClose                = CODEPTR(IAdviseSink_OnClose)

   @pVtbl.pVtblAddr               = pVtbl
   @pVtbl.cRef                    = 1

   pUnk = VARPTR(@pVtbl.pVtblAddr)
   FUNCTION = pUnk

END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' IAdviseSink_QueryInterface method
' Returns the IUnknown of our class and increments the reference counter.
' ****************************************************************************************
FUNCTION IAdviseSink_QueryInterface (BYVAL pCookie AS IAdviseSinkVtbl PTR, BYREF riid AS GUID, BYREF ppvObj AS DWORD) AS LONG
   IF riid = $IID_IAdviseSink THEN
      ppvObj = pCookie
      INCR @@pCookie.cRef
      FUNCTION = %S_OK
   ELSE
      FUNCTION = %E_NOINTERFACE
   END IF
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' IAdviseSink_IUnknown_AddRef method
' Increments the reference counter.
' ****************************************************************************************
FUNCTION IAdviseSink_AddRef (BYVAL pCookie AS IAdviseSinkVtbl PTR) AS DWORD
   INCR @@pCookie.cRef
   FUNCTION = @@pCookie.cRef
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' IAdviseSink_IUnknown_Release method
' Releases our class if there is only a reference to him and decrements the reference counter.
' ****************************************************************************************
FUNCTION IAdviseSink_Release (BYVAL pCookie AS IAdviseSinkVtbl PTR) AS DWORD
   DECR @@pCookie.cRef
   FUNCTION = @@pCookie.cRef
   IF @@pCookie.cRef = 0 THEN
      IF ISTRUE @@pCookie.pVtblAddr THEN
         HeapFree(GetProcessHeap(), 0, BYVAL @@pCookie.pVtblAddr)
      END IF
   END IF
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Advises that data has changed.
' ****************************************************************************************
SUB  IAdviseSink_OnDataChange (BYVAL pCookie AS IAdviseSinkVtbl PTR, BYREF pformatetc AS FORMATETC,  BYREF pStgmed AS STGMEDIUM)
   ' Put your code here
END SUB
' ****************************************************************************************

' ****************************************************************************************
' Advises that view of object has changed.
' ****************************************************************************************
SUB  IAdviseSink_OnViewChange (BYVAL pCookie AS IAdviseSinkVtbl PTR, BYVAL dwAspect AS DWORD, BYVAL lindex AS LONG)
   ' Put your code here
END SUB
' ****************************************************************************************

' ****************************************************************************************
' Advises that name of object has changed.
' ****************************************************************************************
SUB  IAdviseSink_OnRename (BYVAL pCookie AS IAdviseSinkVtbl PTR, BYVAL pmk AS DWORD)
   ' Put your code here
END SUB
' ****************************************************************************************

' ****************************************************************************************
' Advises that object has been saved to disk.
' ****************************************************************************************
SUB  IAdviseSink_OnSave (BYVAL pCookie AS IAdviseSinkVtbl PTR)
   ' Put your code here
END SUB
' ****************************************************************************************

' ****************************************************************************************
' Advises that object has been closed.
' ****************************************************************************************
SUB  IAdviseSink_OnClose (BYVAL pCookie AS IAdviseSinkVtbl PTR)
   ' Put your code here
END SUB
' ****************************************************************************************