IPersistFile::Save

Saves a copy of the object into the specified file.

HRESULT Save(
  LPCOLESTR pszFileName,   //Pointer to absolute path of the file 
                           //where the object is saved
  BOOL fRemember           //Specifies whether the file is to be the 
                           //current working file or not
);

Parameters

pszFileName: [in]Points to a zero-terminated string containing the absolute path of the file to which the object should be saved. If pszFileName is NULL, the object should save its data to the current file, if there is one.
fRemember: [in]Indicates whether the pszFileName parameter is to be used as the current working file. If TRUE, pszFileName becomes the current file and the object should clear its dirty flag after the save. If FALSE, this save operation is a "Save A Copy As ..." operation. In this case, the current file is unchanged and the object should not clear its dirty flag. If pszFileName is NULL, the implementation should ignore the fRemember flag.

Return Values

S_OK: The object was successfully saved.
E_FAIL: The file was not saved.
IPersistFile::Save STG_E_* errors.

Remarks

This method can be called to save an object to the specified file in one of three ways:

Save: Call IPersistFile::GetCurFile first to determine whether the object has an associated filename. If so, call IPersistFile::Save specifying NULL for the pszFileName parameter in this method to indicate that the object should be saved to its current file. Then call IPersistFile::SaveCompleted to indicate completion.
Save As: Call IPersistFile::Save specifying TRUE in the fRemember parameter and a non-NULL value, indicating the name of the new file the object is to be saved to, for the pszFileName parameter . Then call IPersistFile::SaveCompleted to indicate completion.
Save a Copy As: Call IPersistFile::Save specifying FALSE in the fRemember parameter and a non-NULL value, indicating the name of the new file the object is to be copied to, for the pszFileName parameter.

The implementer must detect which type of save operation the caller is requesting. If the pszFileName parameter is NULL, a "Save" is being requested. If the pszFileName parameter is not NULL, use the value of the fRemember parameter to distinguish between a "Save As" and a "Save a Copy As".

In "Save" or "Save As" operations, IPersistFile::Save clears the internal dirty flag after the save and sends IAdviseSink::OnSave notifications to any advisory connections (see also IOleAdviseHolder::SendOnSave). Also, in these operations, the object is in NoScribble mode until it receives an IPersistFile::SaveCompleted call. In NoScribble mode, the object must not write to the file.

In the "Save As" scenario, the implementation should also send IAdviseSink::OnRename notifications to any advisory connections (see also IOleAdviseHolder::SendOnRename).

In the "Save a Copy As" scenario, the implementation does not clear the internal dirty flag after the save.

Notes to Callers

OLE does not call IPersistFile::Save. Typically, applications would not call it unless they are saving an object to a file directly, which is generally left to the end-user.

QuickInfo

  Windows NT: Use version 3.1 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in objidl.h.