IPropertyBag::Write
Called by the
control to write each property in turn to the storage provided by the
container.
HRESULT Write(
|
LPCOLESTR pszPropName, |
//Points to the property to be written |
|
VARIANT* pVar |
//Points to the VARIANT containing the
property value and type |
|
); |
|
Parameters
pszPropName
[in] Pointer
to the name of the property to write. Cannot be NULL.
pVar
[in] Pointer
to the caller-initialized VARIANT that holds the property value to save.
The caller owns this VARIANT and is responsible for all allocations
therein. That is, the property bag itself does not attempt to free data in the VARIANT.
Return Values
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 does not
understand how to save a particular VARIANT type.
E_POINTER
The address
in pszPropName or pVar is not valid (such as NULL). The caller
must supply both.
Remarks
This method
asks the property bag to save the property named with pszPropName 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,
that is, when pVar->vt is VT_UNKNOWN. In such cases, the property bag
queries this object pointer for some persistence interface, like IPersistStream
or even IPersistPropertyBag again 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 (hex string, MIME, etc.). When the
property bag is later used to reinitialize a control, the client that owns the
property bag must recreate the object when the caller asks for it, initializing
that object with the previously saved bits.
This allows
very efficient persistence operations for large BLOB properties like a picture,
where the owner of the property bag itself directly asks the picture object
(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 as any object implementing this interface must support
the entire functionality of the interface.
See Also