IPropertyStore::SetValue method

Article
12/01/2017

Sets a new property value, or replaces or removes an existing value.

Syntax

HRESULT SetValue(
  [in] REFPROPERTYKEY key,
  [in] REFPROPVARIANT propvar
);

Parameters

key [in]
Type: REFPROPERTYKEY

A reference to the PROPERTYKEY structure retrieved through IPropertyStore::GetAt. This structure contains a unique identifier for the property in question.
propvar [in]
Type: REFPROPVARIANT

A reference to a PROPVARIANT structure that contains the new property data.

Return value

Type: HRESULT

Returns S_OK or INPLACE_S_TRUNCATED if successful or an error value otherwise.

Return code	Description
INPLACE_S_TRUNCATED	The value was set but truncated in a string value or rounded if a numeric value.
STG_E_ACCESSDENIED	The property store was read-only.
STG_E_INVALIDARG	The property handler could not store any value for the PROPERTYKEY specified.

Remarks

Note When this method is implemented under IPropertyStoreCache, be aware that the interface is used only by the in-memory store. Many of the following remarks may not apply in that case.

SetValue affects the current property store instance only. A property handler implements SetValue by accumulating property changes in an in-memory data structure. Property changes are written to the stream only when IPropertyStore::Commit is called.

If Commit is called on a read-only property store, the property handler determines this and returns STG_E_ACCESSDENIED.

In general, errors should be detected and reported by SetValue. However, when processing is deferred until Commit is called, the same error semantics apply.

If a value was added or removed as a result of SetValue, subsequent enumerations by IPropertyStore::GetCount and IPropertyStore::GetAt reflect that change and subsequent calls to SetValue reflect the changed value.

Adding a New Property

If the property value pointed to by key does not exist in the store, SetValue adds the value to the store.

Replacing an Existing Property Value

If the property value pointed to by the key parameter already exists in the store, the stored value is replaced.

Removing an Existing Property

Removing a property values from a property store is not supported and could lead to unexpected results.

Support for Different Properties

A property handler must handle three types of properties in SetValue: new properties introduced by the handler author, pre-existing properties that are germane to the property handler, and other properties that do not fall in either of those categories.

New properties introduced by the property handler author must be described in a property description XML file. Clients consume a file property handler through a wrapping layer called the Windows Property Provider. This layer delegates calls to SetValue to the property handler after it enforces restrictions on the new property according to the property description XML. Therefore, a handler should not attempt to enforce restrictions itself and must store any values that satisfy the property description XML. If the property description does not provide the necessary information to restrict values for the new property, the handler must alter the value as necessary to store those values successfully. For example, in the property description XML there is no way to specify that an integer-valued property can never be an odd number. If an odd integer were provided to SetValue, the handler is still required to store a value successfully. It could accomplish this by perhaps adding one to the value. If data is lost, SetValue must succeed with the return value INPLACE_S_TRUNCATED.
Pre-existing properties that are germane to the handler are those that have a representation in the handler's property storage format. For example, Adobe Acrobat .pdf files have representations for PKEY_Author and PKEY_Comments. These properties are described in a property description XML file provided by Windows. It is likely that the restrictions provided by Windows do not exactly match how the equivalent property must be stored in the author's file format. For example, the author value may be restricted to fewer characters in Acrobat files than in the property description for PKEY_Author. In this case, the handler author must make a best-effort attempt to coerce the property value. If data is lost, SetValue must succeed with the return value INPLACE_S_TRUNCATED. In the unusual case that the value cannot be coerced, SetValue can return E_FAIL. If the author's file format is less restrictive than a property description provided by Windows, the Windows Property Provider layer described earlier will already have returned an error and therefore the property handler's SetValue will never be called to store the value.
Properties that are neither new nor pre-existing properties germane to the handler must still be stored by the property handler. The utility class CLSID_InMemoryPropertyStore, provided by Windows, can be used by handler authors to temporarily store such properties in memory and save those properties to a stream for storage in the file.

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

Partager via