IPropertyStorage::WritePropertyNames method

The WritePropertyNames method assigns string names to a specified array of property IDs in the current property set.

Syntax

HRESULT WritePropertyNames(
  [in] ULONG        cpropid,
  [in] const PROPID rgpropid[],
  [in] LPWSTR const rglpwstrName[]
);

Parameters

cpropid [in]

The size on input of the array rgpropid. Can be zero. However, making it zero causes this method to become non-operational.

rgpropid [in]

An array of the property IDs for which names are to be set.

rglpwstrName [in]

An array of new names to be assigned to the corresponding property IDs in the rgpropid array. These names may not exceed 255 characters (not including the NULL terminator).

Return value

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

S_OK

Success. All indicated string names were successfully set.

STG_E_INVALIDNAME

The name is too long, it has incorrect syntax, or it has illegal characters.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied. No property names have been changed in the storage.

STG_E_INSUFFICIENTMEMORY

There is not enough memory to perform this operation. For Windows NT 4.0 and earlier, the size limit is 256 KB. For 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. There is no possibility for memory leak or overrun. For more information, see the Remarks section.

STG_E_INVALIDPARAMETER

A parameter is invalid. Some names may not have been set.

HRESULT_FROM_WIN32(ERROR_NO_UNICODE_TRANSLATION)

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

Remarks

For more information about property sets and memory management, see Managing Property Sets.

IPropertyStorage::WritePropertyNames assigns string names to property IDs passed to the method in the rgpropid array. It associates each string name in the rglpwstrName array with the respective property ID in rgpropid. It is explicitly valid to define a name for a property ID that is not currently present in the property storage object.

It is also valid to change the mapping for an existing string name (determined by a case-insensitive match). That is, you can use the WritePropertyNames method to map an existing name to a new property ID, or to map a new name to a property ID that already has a name in the dictionary. In either case, the original mapping is deleted. Property names must be unique (as are property IDs) within the property set.

The storage of string property names preserves the case. Unless PROPSETFLAG_CASE_SENSITIVE is passed to IPropertySetStorage::Create, property set names are case insensitive by default. With case-insensitive property sets, the name strings passed by the caller are interpreted according to the locale of the property set, as specified by the PID_LOCALE property. If the property set has no locale property, the current user is assumed by default. String property names are limited in length to 128 characters. Property names that begin with the binary Unicode characters 0x0001 through 0x001F are reserved for future use.

If the value of an element in the rgpropid array parameter is set to 0xffffffff (PID_ILLEGAL), the corresponding name is ignored by IPropertyStorage::WritePropertyNames. For example, if this method is called with a cpropid parameter of 3, but the first element of the array, rgpropid[1], is set to PID_ILLEGAL, then only two property names are written. The rgpropid[1] element is ignored.

Requirements

See also

Samples

WriteRead Sample

IPropertyStorage::ReadMultiple

IPropertyStorage::ReadPropertyNames

IPropertyStorage::WriteMultiple