Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method asks the property bag to save the named property in a caller-initialized VARIANT.

Syntax 

HRESULT Write( 
  LPCOLESTR 
pszPropName, 
  VARIANT* 
pVar 
);

Parameters

pszPropName

[in] Address of a string containing the name of the property to write. This cannot be NULL.

pVar

[in] Address of the caller-initialized VARIANT that holds the property value to save. The caller owns this VARIANT and is responsible for all of its allocations. That is, the property bag itself does not attempt to free data in the VARIANT.

Return Value

The following table shows the return values.

Value Description

S_OK

The property bag successfully saved the requested property.

E_FAIL

There was a problem writing the property. It is possible that the property bag is unable to save a particular VARIANT type.

E_POINTER

The address in pszPropNameor pVaris not valid. The caller must supply both.

Remarks

The Writemethod asks the property bag to save the property named with pszPropNameby using the type and value in the caller-initialized VARIANT in pVar.

In some cases, the caller may be asking the property bag to save another object, such as when pVar-> vtis VT_UNKNOWN. In such cases, the property bag queries this object pointer for a persistence interface, such as IPersistStreamor IPersistPropertyBag, and has that object save its data as well.

Usually this results in the property bag having some byte array for this object, which can be saved as encoded text, such as a hexadecimal string. When the property bag is later used to reinitialize a control, the client that owns the property bag must re-create the object when the caller asks for it, and initialize that object with the previously saved bits.

This allows very efficient persistence operations for Binary Large Object (BLOB) properties, like a picture, where the owner of the property bag directly asks the picture object that is managed as a property in the control being saved, to save into a specific location. This avoids potential extra copy operations that would be involved with other property-based persistence mechanisms.

E_NOTIMPL is not a valid return code because any object implementing this interface must support the entire functionality of the interface.

Requirements

Header ocidl.h, ocidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also