IPropertyBag Interface

IID_IPropertyBag

{55272A00-42CB-11CE-8135-00AA004BB851}

The IPropertyBag interface provides an object with a property bag in which the object can persistently save its properties.

Remarks

When the object wishes to read a property in IPersistPropertyBag::Load, it calls IPropertyBag::Read. When the object is saving properties in IPersistPropertyBag::Save, it calls IPropertyBag::Write. Each property is described with a name, whose value is stored in a VARIANT. This information allows a client to save the property values as text, for instance, which is the primary reason why a client might choose to support IPersistPropertyBag.

The client records errors that occur during Read into the supplied error log.
 

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IPropertyBag Members

Description

Read

Asks the property bag to read the named property into a caller-initialized VARIANT.

Write

Asks the property bag to save the named property in a caller-initialized VARIANT.

Read

FUNCTION IPropertyBag_Read ( _
  BYVAL pthis AS DWORD PTR _

, BYVAL strPropName AS STRING _

, BYREF pVar AS VARIANT _

, BYVAL pErrorLog AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG

  strPropName = UCODE$(strPropName & $NUL)
  CALL DWORD @@pthis[3] USING IPropertyBag_Read (pthis, strPropName, pVar, pErrorLog) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION
 

Write

FUNCTION IPropertyBag_Write ( _
  BYVAL pthis AS DWORD PTR _

, BYVAL strPropName AS STRING _

, BYREF pVar AS VARIANT _

  ) AS LONG

  LOCAL HRESULT AS LONG
  strPropName = UCODE$(strPropName & $NUL)
  CALL DWORD @@pthis[4] USING IPropertyBag_Write (pthis, strPropName, pVar) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION
 

IPropertyBag interface implementation

$IID_IPropertyBag = GUID$("{55272A00-42CB-11CE-8135-00AA004BB851}")

' ****************************************************************************************
' IPropertyBag interface
' ****************************************************************************************
TYPE IPropertyBagVtbl
   ' IUnknown methods
   pQueryInterface         AS DWORD          ' // QueryInterface method
   pAddRef                 AS DWORD          ' // AddRef method
   pRelease                AS DWORD          ' // Release method
   ' IPropertyBag members
   pRead                   AS DWORD          ' // Read method
   pWrite                  AS DWORD          ' // Write method
   ' Custom data
   pVtblAddr               AS DWORD          ' // Address of the virtual table
   cRef                    AS DWORD          ' // Reference count
END TYPE
' ****************************************************************************************

' ****************************************************************************************
' Builds the IPropertyBag Virtual Table
' Returns a cookie that is a pointer to a IPropertyBagVtbl structure.
' ****************************************************************************************
FUNCTION IPropertyBag_BuildVtbl () AS DWORD

   LOCAL pVtbl AS IPropertyBagVtbl PTR
   LOCAL pUnk AS IPropertyBagVtbl PTR

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

   @pVtbl.pQueryInterface         = CODEPTR(IPropertyBag_QueryInterface)
   @pVtbl.pAddRef                 = CODEPTR(IPropertyBag_AddRef)
   @pVtbl.pRelease                = CODEPTR(IPropertyBag_Release)

   @pVtbl.pRead                   = CODEPTR(IPropertyBag_Read)
   @pVtbl.pWrite                  = CODEPTR(IPropertyBag_Write)

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

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

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

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

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

' ****************************************************************************************
' IPropertyBag_Release method
' Releases our class if there is only a reference to him and decrements the reference counter.
' ****************************************************************************************
FUNCTION IPropertyBag_Release (BYVAL pCookie AS IPropertyBagVtbl 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
' ****************************************************************************************

' ****************************************************************************************
' Asks the property bag to read the named property into a caller-initialized VARIANT.
' ****************************************************************************************
FUNCTION IPropertyBag_Read (BYVAL pCookie AS IPropertyBagVtbl PTR, BYVAL pszPropName AS DWORD, BYREF pVar AS VARIANT, BYVAL pErrorLog AS DWORD) AS LONG
   ' Put your code here
   ' FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Asks the property bag to save the named property in a caller-initialized VARIANT.
' ****************************************************************************************
FUNCTION IPropertyBag_Write (BYVAL pCookie AS IPropertyBagVtbl PTR, BYVAL pszPropName AS DWORD, BYREF pVar AS VARIANT) AS LONG
   ' Put your code here
   ' FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************