IPersistStorage Interface

IID_IPersistStorage

{0000010A-0000-0000-C000-000000000046}

The IPersistStorage interface defines methods that enable a container application to pass a storage object to one of its contained objects and to load and save the storage object. This interface supports the structured storage model, in which each contained object has its own storage that is nested within the container's storage.

The IPersistStorage contract inherits its definition from IPersist, so all implementations must also include the GetClassID method of IPersist.

When an OLE container creates a new object, loads an existing object from storage, or inserts a new object in a clipboard or a drag-and-drop operation, the container uses the IPersistStorage interface to initialize the object and put it in the loaded or running state. When an object is loaded or running, an OLE container calls other IPersistStorage methods to instruct the object to perform various save operations or to release its storage.

Typically, applications use helper functions such as OleLoad or OleCreate, rather than calling the IPersistStorage::Load or IPersistStorage::InitNew methods directly. Similarly, applications typically call the OleSave helper function rather than calling IPersistStorage::Save directly.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IPersist Method

Description

GetClassID

Returns the class identifier (CLSID) for the component object.

IPersistStorage Methods

Description

IsDirty

Checks an object for changes since it was last saved to its current storage.

InitNew

Initializes a new storage object.

Load

Initializes an object from its existing storage.

Save

Saves an object, and any nested objects that it contains, into the specified storage object. The object enters NoScribble mode.

SaveCompleted

Notifies the object that it can revert from NoScribble or HandsOff mode, in which in must not write to its storage object, to Normal mode in which it can.

HandsOffStorage

Instructs the object to release all storage objects that have been passed to it by its container and to enter HandsOffAfterSave or HandsOffFromNormal mode.

IsDirty

FUNCTION IPersistStorage_IsDirty ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG
 

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

END FUNCTION

FUNCTION IPersistStorage_IsDirty ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG
 

  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+16]
  ! mov  FUNCTION, eax

END FUNCTION

InitNew

FUNCTION IPersistStorage_InitNew ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pStg AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[5] USING IPersistStorage_InitNew (pthis, pStg) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

FUNCTION IPersistStorage_InitNew ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pStg AS DWORD _

  ) AS LONG
 

  ! push pStg

  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+20]
  ! mov  FUNCTION, eax

END FUNCTION

Load

FUNCTION IPersistStorage_Load ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pStg AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[6] USING IPersistStorage_Load (pthis, pStg) TO HRESULT
  FUNCTION = HRESULT
 

END FUNCTION

FUNCTION IPersistStorage_Load ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pStg AS DWORD _

  ) AS LONG
 

  ! push pStg

  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+24]
  ! mov  FUNCTION, eax

END FUNCTION

Save

FUNCTION IPersistStorage_Save ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pStgSave AS DWORD _

, BYVAL fSameAsLoad AS LONG _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[7] USING IPersistStorage_Save(pthis, pStgSave, fSameAsLoad) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

FUNCTION IPersistStorage_Save ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pStgSave AS DWORD _

, BYVAL fSameAsLoad AS LONG _

  ) AS LONG
 

  ! push pSameAsLoad

  ! push pStgSave

  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+28]
  ! mov  FUNCTION, eax

END FUNCTION

SaveCompleted

FUNCTION IPersistStorage_SaveCompleted ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pStgNew AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[8] USING IPersistStorage_SaveCompleted (pthis, pStgNew) TO HRESULT
  FUNCTION = HRESULT
 

END FUNCTION

FUNCTION IPersistStorage_SaveCompleted ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pStgNew AS DWORD _

  ) AS LONG
 

  ! push pStgNew

  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+32]
  ! mov  FUNCTION, eax

END FUNCTION

HandsOffStorage

FUNCTION IPersistStorage_HandsOffStorage ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[9] USING IPersistStorage_HandsOffStorage (pthis) TO HRESULT
  FUNCTION = HRESULT
 

END FUNCTION

FUNCTION IPersistStorage_HandsOffStorage ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG
 

  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+36]
  ! mov  FUNCTION, eax

END FUNCTION