IPropertyBag2 Interface

IID_IPropertyBag2

{22F55882-280B-11d0-A8A9-00A0C90C2004}

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

Remarks

When a client wants to have exact control over how individually named properties of an object are saved, it uses an object's IPersistPropertyBag2 interface as a persistence mechanism. In that case, the client supplies a property bag to the object in the form of an IPropertyBag2 interface.

IPropertyBag2 is an enhancement of the IPropertyBag interface. IPropertyBag2 allows the object to obtain type information for each property through the use of the CountProperties and GetPropertyInfo methods. A property bag that implements IPropertyBag2 must also support IPropertyBag so that objects that only support IPropertyBag can access their properties. Also, an object that supports IPropertyBag2 must also support IPropertyBag so that the object can communicate with property bags that only support IPropertyBag.
 

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

Causes one or more properties to be read from the property bag.

Write

Causes one or more properties to be saved into the property bag.

CountProperties

Retrieves the number of properties in the property bag.

GetPropertyInfo

Retrieves information for properties in a property bag without actually retrieving the properties themselves.

LoadObject

Causes the property bag to instruct a previously created and initialized property object to read its persistent properties.

Read

FUNCTION IPropertyBag2_Read ( _
  BYVAL pthis AS DWORD PTR _

, BYVAL cProperties AS DWORD _

, BYREF pPropBag AS PROPBAG2 _

, BYVAL pErrorLog AS DWORD _

, BYREF pvarValue AS VARIANT _

, BYREF phrError AS LONG _

) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[3] USING IPropertyBag2_Read (pthis, cProperties, pPropBag, pErrorLog, pvarValue, phrError) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION
 

Write

FUNCTION IPropertyBag2_Write ( _
  BYVAL pthis AS DWORD PTR _

, BYVAL cProperties AS DWORD _

, BYREF pPropBag AS PROPBAG2 _

, BYVAL pvarValue AS VARIANT _

) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IPropertyBag2_Write (pthis, cProperties, pPropBag, pvarValue) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION
 

CountProperties

FUNCTION IPropertyBag2_CountProperties ( _
  BYVAL pthis AS DWORD PTR _

, BYREF pcProperties AS DWORD _

) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IPropertyBag2_CountProperties (pthis, pcProperties) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION
 

GetPropertyInfo

FUNCTION IPropertyBag2_GetPropertyInfo ( _
  BYVAL pthis AS DWORD PTR _

, BYVAL iProperty AS DWORD _

, BYVAL cProperties AS DWORD _

, BYREF pPropBag AS PROPBAG2 _

, BYREF pcProperties AS DWORD _

) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[5] USING IPropertyBag2_GetPropertyInfo (pthis, iProperty, cProperties, pPropBag, pcProperties) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION
 

LoadObject

FUNCTION IPropertyBag2_LoadObject ( _
  BYVAL pthis AS DWORD PTR _

, BYVAL pstrName AS DWORD _

, BYVAL dwHint AS DWORD _

, BYVAL pUnkObject AS DWORD _

, BYVAL pErrLog AS DWORD _

) AS LONG

  LOCAL HRESULT AS LONG

  CALL DWORD @@pthis[5] USING IPropertyBag2_LoadObject (pthis, pstrName, dwHint, pUnkObject, pErrLog) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION
 

IPropertyBag2 interface implementation

$IID_IPropertyBag2 = GUID$("{22F55882-280B-11d0-A8A9-00A0C90C2004}")

' ****************************************************************************************
' IPropertyBag2 interface
' ****************************************************************************************
TYPE IPropertyBag2Vtbl
   ' IUnknown methods
   pQueryInterface         AS DWORD          ' // QueryInterface method
   pAddRef                 AS DWORD          ' // AddRef method
   pRelease                AS DWORD          ' // Release method
   ' IPropertyBag2 members
   pRead                   AS DWORD          ' // Read method
   pWrite                  AS DWORD          ' // Write method
   pCountProperties        AS DWORD          ' // CountProperties method
   pGetPropertyInfo        AS DWORD          ' // GetPropertyInfo method
   pLoadObject             AS DWORD          ' // LoadObject method
   ' Custom data
   pVtblAddr               AS DWORD          ' // Address of the virtual table
   cRef                    AS DWORD          ' // Reference count
END TYPE
' ****************************************************************************************

' ****************************************************************************************
' Builds the IPropertyBag2 Virtual Table
' Returns a cookie that is a pointer to a IPropertyBag2Vtbl structure.
' ****************************************************************************************
FUNCTION IPropertyBag2_BuildVtbl () AS DWORD

   LOCAL pVtbl AS IPropertyBag2Vtbl PTR
   LOCAL pUnk AS IPropertyBag2Vtbl PTR

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

   @pVtbl.pQueryInterface         = CODEPTR(IPropertyBag2_QueryInterface)
   @pVtbl.pAddRef                 = CODEPTR(IPropertyBag2_AddRef)
   @pVtbl.pRelease                = CODEPTR(IPropertyBag2_Release)

   @pVtbl.pRead                   = CODEPTR(IPropertyBag2_Read)
   @pVtbl.pWrite                  = CODEPTR(IPropertyBag2_Write)
   @pVtbl.pCountProperties        = CODEPTR(IPropertyBag2_CountProperties)
   @pVtbl.pGetPropertyInfo        = CODEPTR(IPropertyBag2_GetPropertyInfo)
   @pVtbl.pLoadObject             = CODEPTR(IPropertyBag2_LoadObject)

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

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

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

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

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

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

' ****************************************************************************************
' Causes one or more properties to be read from the property bag.
' ****************************************************************************************
FUNCTION IPropertyBag2_Read (BYVAL pCookie AS IPropertyBag2Vtbl PTR, BYVAL cProperties AS DWORD, BYREF pPropBag AS PROPBAG2, BYVAL pErrorLog AS DWORD, BYREF pvarValue AS VARIANT, BYREF phrError AS LONG) AS LONG
   ' Put your code here
   ' FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Causes one or more properties to be saved into the property bag.
' ****************************************************************************************
FUNCTION IPropertyBag2_Write (BYVAL pCookie AS IPropertyBag2Vtbl PTR, BYVAL cProperties AS DWORD, BYREF pPropBag AS PROPBAG2, BYVAL pvarValue AS VARIANT) AS LONG
   ' Put your code here
   ' FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Retrieves the number of properties in the property bag.
' ****************************************************************************************
FUNCTION IPropertyBag2_CountProperties (BYVAL pCookie AS IPropertyBag2Vtbl PTR, BYREF pcProperties AS DWORD) AS LONG
   ' Put your code here
   ' FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Retrieves information for properties in a property bag without actually retrieving the
' properties themselves.
' ****************************************************************************************
FUNCTION IPropertyBag2_GetPropertyInfo (BYVAL pCookie AS IPropertyBag2Vtbl PTR, BYVAL iProperty AS DWORD, BYVAL cProperties AS DWORD, BYREF pPropBag AS PROPBAG2, BYREF pcProperties AS DWORD) AS LONG
   ' Put your code here
   ' FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************

' ****************************************************************************************
' Causes the property bag to instruct a previously created and initialized property object
' to read its persistent properties.
' ****************************************************************************************
FUNCTION IPropertyBag2_LoadObject (BYVAL pCookie AS IPropertyBag2Vtbl PTR, BYVAL pstrName AS DWORD, BYVAL dwHint AS DWORD, BYVAL pUnkObject AS DWORD, BYVAL pErrLog AS DWORD) AS LONG
   ' Put your code here
   ' FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************