IPropertyStorage::ReadPropertyNames method

The ReadPropertyNames method retrieves any existing string names for the specified property IDs.

Syntax

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

Parameters

cpropid [in]

The number of elements on input of the array rgpropid. The value of this parameter can be set to zero, however that defeats the purpose of this method as no property names are thereby read.

rgpropid [in]

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

rglpwstrName [in, out]

A caller-allocated array of size cpropid of LPWSTR members. On return, the implementation fills in this array. A given entry contains either the corresponding string name of a property ID or it can be empty if the property ID has no string names.

Each LPWSTR member of the array should be freed using the CoTaskMemFree function.

Return value

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

S_OK

One or more string names were retrieved and all members of rglpwstrName are valid (either NULL or a valid LPWSTR members).

S_FALSE

No string names were retrieved because none of the requested property identifiers have string names presently associated with them in this property storage object; this result does not address whether the given property identifiers presently exist in the set.

STG_E_INVALIDHEADER

The property name dictionary was not found.

STG_E_READFAULT

Error reading the storage.

STG_E_ACCESSDENIED

The requested access to the property storage object has been denied. No string names were retrieved.

STG_E_INSUFFICIENTMEMORY

There is not enough memory to perform this operation. No string names were retrieved. In Windows NT 4.0 or earlier, the limit is 256 KB. In Windows 2000, Windows XP, and Windows Server 2003, the limit is 1 MB.

STG_E_INVALIDPARAMETER

A parameter is not valid. No string names were retrieved.

HRESULT_FROM_WIN32(ERROR_NO_UNICODE_TRANSLATION)

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

Remarks

For each property ID in the list of property IDs supplied in the rgpropid array, ReadPropertyNames retrieves the corresponding string name, if there is one. String names are created either by specifying the names in calls to IPropertyStorage::WriteMultiple when creating the property, or through a call to IPropertyStorage::WritePropertyNames. In either case, the string name is optional, however all properties must have a property ID.

String names mapped to property IDs must be unique within the set.

Requirements

See also

IPropertyStorage::WriteMultiple

IPropertyStorage::WritePropertyNames