IPersistFile Interface

IID_IPersistFile

{0000010B-0000-0000-C000-000000000046}

The IPersistFile interface provides methods that permit an object to be loaded from or saved to a disk file, rather than a storage object or stream. Because the information needed to open a file varies greatly from one application to another, the implementation of IPersistFile::Load on the object must also open its disk file.

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

Call methods in the IPersistFile interface to load or save a linked object in a specified file.

When IPersistFile is implemented on an object that supports linking through a file moniker and the application for the linked object is run, OLE calls IPersistFile::Load. Once the file is loaded, OLE calls IPersistFile::QueryInterface to get another interface pointer to the loaded object. The IPersistFile interface is typically part of an aggregate object that offers other interfaces.

In this case, the only IPersistFile method that OLE calls is the Load method to load a file linked to a container, running the application associated with the file. It would also be unusual for applications to call other methods in this case, which support saving an object to a file. Generally, it is left to the end user and the application for the linked object to decide when to save the object. This differs from the situation for an embedded object, in which the container application uses the IPersistStorage interface to provide the storage and to tell the object when to save itself.

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.

IPersistFile Methods

Description

IsDirty

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

Load

Opens the specified file and initializes an object from the file contents.

Save

Saves the object into the specified file.

SaveCompleted

Notifies the object that it can revert from NoScribble mode to Normal mode.

GetCurFile

Gets the current name of the file associated with the object.

IsDirty

FUNCTION IPersistFile_IsDirty ( _

  BYVAL pthis AS DWORD PTR _

  ) AS LONG
 

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

END FUNCTION

Load

FUNCTION IPersistFile_Load ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL strFileName AS STRING _

, BYVAL dwMode AS DWORD _

  ) AS LONG
 

  LOCAL HRESULT AS LONG

  strFileName = UCODE$(strFileName) & $NUL
  CALL DWORD @@pthis[5] USING IPersistFile_Load (pthis, strFileName, dwMode) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Save

DECLARE FUNCTION Proto_IPersistFile_Save ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pszFileName AS DWORD _

, BYVAL fRemember AS LONG _

  ) AS LONG

FUNCTION IPersistFile_Save ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL strFileName AS STRING _

, BYVAL fRemember AS LONG _

  ) AS LONG
 

  LOCAL HRESULT AS LONG

  LOCAL pszFileName AS DWORD
  IF LEN(strFileName) THEN

     strFileName = UCODE$(strFileName) & $NUL

     pszFileName = STRPTR(strFileName)

  END IF
  CALL DWORD @@pthis[6] USING Proto_IPersistFile_Save (pthis, pszFileName, fRemember) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SaveCompleted

FUNCTION IPersistFile_SaveCompleted ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL strFileName AS STRING _

  ) AS LONG
 

  LOCAL HRESULT AS LONG
  strFileName = UCODE$(strFileName) & $NUL
  CALL DWORD @@pthis[7] USING IPersistFile_SaveCompleted (pthis, strFileName) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetCurFile

DECLARE FUNCTION Proto_IPersistFile_GetCurFile ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppszFileName AS DWORD _

  ) AS LONG
 

FUNCTION IPersistFile_GetCurFile ( _

  BYVAL pthis AS DWORD PTR _

, BYREF strFileName AS STRING _

  ) AS LONG
 

   strFileName = ""

  LOCAL HRESULT AS LONG
  LOCAL bstrlen AS LONG

  LOCAL ppszFileName AS DWORD

  CALL DWORD @@pthis[8] USING Proto_IPersistFile_GetCurFile (pthis, ppszFileName) TO HRESULT
  IF ISTRUE ppszFileName THEN
     bstrlen = lstrlenW(BYVAL ppszFileName)
     IF ISTRUE bstrlen THEN strFileName = ACODE$(PEEK$(ppszFileName, bstrlen * 2))
     CoTaskMemFree ppszFileName
  END IF
  FUNCTION = HRESULT

END FUNCTION