IPropertyStore::Commit method

Article
12/01/2017

Saves a property change.

Syntax

HRESULT Commit();

Parameters

This method has no parameters.

Return value

Type: HRESULT

Returns S_OK or INPLACE_S_TRUNCATED if successful, or an error value otherwise, including the following:

Return code	Description
S_OK	All of the property changes were successfully written to the stream or path. This includes the case where no changes were pending and nothing was written.
INPLACE_S_TRUNCATED	The value was set but truncated in a string value or rounded if a numeric value.
STG_E_ACCESSDENIED	The stream or file is read-only so the method was not able to set the value.
STG_E_INVALIDARG	The property handler could not store any value for the PROPERTYKEY specified.
E_FAIL	Some or all of the changes could not be written to the file. Another appropriate error code can be used in place of E_FAIL.

Remarks

Before it returns, Commit releases the file stream or path with which the handler was initialized. Therefore, no IPropertyStore methods succeed after Commit. At that point, they return E_FAIL.

Initializing Property Handlers must ensure that property changes result in a valid destination file, even if the Commit process terminates abnormally or otherwise encounters an error. Handlers initialized through IInitializeWithStream can do this easily because the stream pstream passed to Initialize implements copy-on-write behavior—explained below—by default.

Property handlers that use IInitializeWithStream and automatic safe-save.	When the handler implementation first calls pstream->Write, the modified source stream is copied to a destination stream. When the handler subsequently calls IStream::Commit, the source stream is automatically replaced with the destination, ensuring a valid file. This copy-on-write behavior is completely automatic from the point of view of the handler author for handlers that use IInitializeWithStream.
Property handlers that use IInitializeWithFile.	A handler initialized with IInitializeWithFile is responsible for ensuring that updates to the file as a result of writing property changes do not result in a corrupt file. Whenever property changes require the rewriting of a large part of the file, the handler should make changes to a new destination file and then automatically replace the source file through the ReplaceFile function.
Property handlers that use IInitializeWithStream and manual safe-save.	The default copy-on-write behavior provided by Initialize causes the entire source stream to be duplicated during a write operation. This can be costly for large streams, especially when a large portion of the stream is to be changed. An alternative for the property handler author is to manually ensure that property changes do not corrupt the stream in case of failure. To do this, the author marks the handler as ManualSafeSave in the handler's CoClass registry subkey and queries the stream for IDestinationStreamFactory.

  HKEY_CLASSES_ROOT
   CLSID
      {00000000-0000-0000-0000-000000000000}
         (Default) = Sample Property Handler
         ManualSafeSave [REG_DWORD] = 0x0001

A handler marked with ManualSafeSave can also opt to do a fast in-place save operation if writing the property changes does not require a change in the size of the stream. To do this, the handler writes to the source stream and then calls IStream::Commit. Do not attempt this if the property changes require a change in the size of the stream. This can result in a corrupt file stream if the process should terminate abnormally or if an unexpected error should occur.

Requirements

Minimum supported client	Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Header	Propsys.h
IDL	Propsys.idl

Share via