IPropertySetStorage-NTFS File System Implementation
NTFS version 5.0 provides an implementation of IPropertySetStorage for files on an NTFS volume when the files themselves are not compound files. The NTFS implementation is equivalent to the compound file implementation. For more information about exceptions, see Remarks.
To get a pointer to the NTFS implementation of IPropertySetStorage
- Call StgCreateStorageEx and specify STGFMT_FILE in the grfFlags parameter to create a new file.
- Call StgOpenStorageEx and specify either the STGFMT_FILE or STGFMT_ANY enumeration value in the grfFlags parameter to open an existing file.
However, you cannot obtain the NTFS implementation of IPropertySetStorage for a compound file. When opening a compound file with StgOpenStorage, specifying the STGFMT_FILE enumeration value results in an error.
Also, simple property sets cannot be transacted. That is, you cannot specify STGM_TRANSACTED in the grfmode parameter of the Create and Open methods unless you also specify PROPSETFLAG_NONSIMPLE in the grfFlags parameter. The property set storage object itself does not support transaction processing.
When to Use
Call the IPropertySetStorage methods to create, open, or delete property sets in the current NTFS property set storage. There is also a method, IPropertySetStorage::Enum, that supplies a pointer to an enumerator that can be used to enumerate the property sets in the storage.
The NTFS implementation stores property sets in alternate streams of an NTFS file. The alternate streams must be copied when the main file is copied.
Not all file systems support such streams. If an NTFS file with property sets is copied to a FAT volume, only the data in the file is copied; the property set is lost. The CopyFile function does not return an error in this case.
If the computer performing the file copy is not a computer running on Windows 2000 or later, the property sets may be lost. For example, if a computer running on Windows 95 operating system copies an NTFS file, the property set is lost even if the destination file is also on an NTFS volume.
The NTFS file system implementation of IPropertySetStorage supports the following methods.
Creates a new property set in the current NTFS file storage and, on return, supplies an interface pointer to the IPropertyStorage NTFS file implementation. The sharing mode specified in the grfmode parameter must be STGM_SHARE_EXCLUSIVE.
Opens an existing property set in the current property storage. On return, it supplies an interface pointer to the NTFS file implementation of IPropertyStorage. The sharing mode specified in the grfmode parameter must be STGM_SHARE_EXCLUSIVE.
Deletes a property set in the current property storage.
Creates an object used to enumerate STATPROPSETSTG structures. Each STATPROPSETSTG structure provides data about a single property set.
The NTFS implementations of IPropertySetStorage and IPropertyStorage store property sets in a file without affecting the contents of that file. For example, if you create a property set in an HTML file named Default.htm, that file still displays properly in a Web browser. That is, changes to a file using these two interfaces are undetectable when accessing a file with the CreateFile function.
The NTFS implementation of IPropertySetStorage provides a safe implementation when used to write property sets to a file on an NTFS version 5.0 volume. Such property sets cannot be corrupted by the implementation even in the event of a system failure. For example, if the power to a system fails during a call to IPropertyStorage::Commit while the property set is flushed to the disk, the property set is never left in an intermediate state. Either the previous version of the property set remains or all of the updates are saved.
The NTFS implementation of IPropertySetStorage differs from the compound file implementation in the following ways:
A STATPROPSETSTG structure obtained from the IEnumSTATPROPSETSTG interface contains a clsid member whose value is always zero (CLSID_NULL). With the compound file implementation, the correct clsid member is returned for non-simple (see Storage and Stream Objects for a Property Set) property sets.
When obtaining an NTFS implementation of IPropertySetStorage interface pointer using the StgCreateStorageEx or StgOpenStorageEx function, the grfmode parameter must follow the same rules as for the compound file implementation.
In addition, the following flags may not be used:
STGM_SIMPLE, STGM_TRANSACTED, STGM_CONVERT, STGM_PRIORITY, and STGM_DELETEONRELEASE.
When an NTFS IPropertySetStorage interface is obtained by the StgCreateStorageEx or StgOpenStorageEx functions, the sharing modes primarily apply to other instances of that interface, and not to instances of opening the file itself. For example, if an NTFS IPropertySetStorage interface is opened by calling the StgOpenStorageEx function, with the grfmode parameter set to STGM_READWRITE|STGM_SHARE_EXCLUSIVE, it is possible to open the file with the CreateFile function.
Such simultaneous instances of opening this interface are subject to the following constraints: the dwShareMode parameter in the CreateFile function must specify the FILE_SHARE_READ flag, and the dwAccess parameter must not specify the DELETE flag. Also, the DeleteFile and MoveFile functions must not be called on a file for which these property set interfaces are open, as these functions require DELETE access to the file.
If an NTFS IPropertySetStorage method is opened as read-only, and the file currently has no property sets, the object returned will not actually hold open the file. Consequently, other openings of that file will succeed, even if the sharing mode of the original open operation would otherwise reject it.
Example; if an NTFS IPropertySetStorage is opened in the mode STGM_READ|STGM_SHARE_EXCLUSIVE, and the file has no property sets, it will be possible to simultaneously open the file STGM_READWRITE|STGM_SHARE_EXCLUSIVE.