IPropertyStorage::WriteMultiple method

The WriteMultiple method writes a specified group of properties to the current property set. If a property with a specified name or property identifier already exists, it is replaced, even when the old and new types for the property value are different. If a property of a given name or property ID does not exist, it is created.


HRESULT WriteMultiple(
  [in] ULONG             cpspec,
  [inconst PROPSPEC    rgpspec[],
  [inconst PROPVARIANT rgpropvar[],
  [in] PROPID            propidNameFirst


cpspec [in]

The number of properties set. The value of this parameter can be set to zero; however, this defeats the purpose of the method as no properties are then written.

rgpspec [in]

An array of the property IDs (PROPSPEC) to which properties are set. These need not be in any particular order, and may contain duplicates, however the last specified property ID is the one that takes effect. A mixture of property IDs and string names is permitted.

rgpropvar [in]

An array (of size cpspec) of PROPVARIANT structures that contain the property values to be written. The array must be the size specified by cpspec.

propidNameFirst [in]

The minimum value for the property IDs that the method must assign if the rgpspec parameter specifies string-named properties for which no property IDs currently exist. If all string-named properties specified already exist in this set, and thus already have property IDs, this value is ignored. When not ignored, this value must be greater than, or equal to, two and less than 0x80000000. Property IDs 0 and 1 and greater than 0x80000000 are reserved for special use.

Return value

This method supports the standard return value E_UNEXPECTED, in addition to the following:


All of the indicated properties were written successfully.


The requested access to the property storage object has been denied. No properties have been written. The property set was opened in STGM_READ mode.


There is not enough memory to perform this operation. Some properties may, or may not, have been written. For computers running on Windows NT 4.0 and earlier operating systems, the size limit is 256 KB. For computers running on Windows 2000, Windows XP, and Windows Server 2003, the size limit is 1 MB for OLE property sets. If these limits are exceeded, the operation fails and the caller receives an error message. A memory leak or overrun cannot occur.


One of the property types specified in the rgvar array is not a supported type by this IPropertyStorage implementation.


At least one of the parameters are invalid. Some properties may not have been written. This error would be returned in several situations, for example: 1) rgvar may be NULL; 2) a stream- or storage-valued property is present in rgpspec, but the property set was created without PROPSETFLAG_NONSIMPLE; 3) one of the PROPSPEC structures contains an illegal value of the ulKind member, such as a string name instead of a property ID value.


May be returned when at least one of the pointers passed is invalid. Some properties may or may not have been written. Frequently, an invalid pointer results in an access violation.


An error occurred when writing the storage.


The property set was reverted. For example, if the property set is deleted while open, by using IPropertySetStorage::Delete, this status would be returned.


The disk is full or the property-set size limit of 256 KB has been exceeded. Some properties may or may not have been written. For more information, see the Remarks section.


An attempt was made to write a nonsimple (stream- or storage-valued) property to a simple property set.


There was a failed attempt to translate a Unicode string to or from ANSI.

This function can also return any file system errors or Win32 errors wrapped in an HRESULT data type. For more information, see Error Handling Strategies.


If a specified property already exists, its value is replaced with the one specified in rgpspec, even when the old and new types for the property value are different. If the specified property does not already exist, that property is created. The changes are not persisted to the underlying storage until IPropertyStorage::Commit has been called.

Property names are stored in a special dictionary section of the property set, which maps such names to property IDs. All properties have an ID, but names are optional. A string name is supplied by specifying PRSPEC_LPWSTR in the ulKind member of the PROPSPEC structure. If a string name is supplied for a property, and the name does not already exist in the dictionary, the method will allocate a property ID, and add the property ID and the name to the dictionary. The property ID is allocated in such a way that it does not conflict with other IDs in the property set. The value of the property ID also is no less than the value specified by the propidNameFirst parameter. If the rgpspec parameter specifies string-named properties for which no property IDs currently exist, the propidNameFirst parameter specifies the minimum value for the property IDs that the WriteMultiple method must assign.

When a new property set is created, the special codepage (Property ID 1) and Locale ID (Property ID 0x80000000) properties are written to the property set automatically. These properties can subsequently be read, using the IPropertyStorage::ReadMultiple method, by specifying property IDs with the header-defined PID_CODEPAGE and PID_LOCALE values, respectively. If a property set is non-empty — has one or more properties in addition to the codepage and Locale ID properties or has one or more names in its dictionary — the special codepage and Locale ID properties cannot be modified by calling IPropertyStorage::WriteMultiple. However, if the property set is empty, one or both of these special properties can be modified.

If an element in the rgspec array is set with a PRSPEC_PROPID value of 0xffffffff (PID_ILLEGAL), the corresponding value in the rgvar array is ignored by IPropertyStorage::WriteMultiple. For example, if this method is called with the cspec parameter set to 3, but rgpspec[1].prspec is set to PRSPEC_PROPID and rgpspec[1].propid is set to PID_ILLEGAL, only two properties will be written. The rgpropvar[1] element is silently ignored.

Use the PropVariantInit macro to initialize PROPVARIANT structures.

Property sets, not including the data for nonsimple properties, are limited to 256 KB in size for Windows NT 4.0 and earlier. For Windows 2000, Windows XP and Windows Server 2003, OLE property sets are limited to 1 MB. If these limits are exceeded, the operation fails and the caller receives an error message. There is no possibility of a memory leak or overrun. For more information, see Managing Property Sets.

Unless PROPSETFLAG_CASE_SENSITIVE is passed to IPropertySetStorage::Create, property set names are case insensitive. Specifying a property by its name in IPropertyStorage::WriteMultiple will result in a case-insensitive search of the names in the property set. To compare case-insensitive strings, the locale of the strings must be known. For more information, see IPropertyStorage::WritePropertyNames.

For more information, see Property Storage Considerations.


Minimum supported client

Windows 2000 Professional [desktop apps | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]


Propidl.h (include Objbase.h)






IID_IPropertyStorage is defined as 00000138-0000-0000-C000-000000000046

See also

Managing Property Sets
StgCreatePropSetStg Sample
WriteRead Sample



Community Additions