IPropertyBag::WriteIPropertyBag::Write*
*Contents  *Index  *Topic Contents

*Previous Topic: IPropertyBag::Read
*Next Topic: The IPersistPropertyBag2 Interface

IPropertyBag::Write

HRESULT Write([in] LPCOLESTR pszPropName, 
		[in] VARIANT *pVar);

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, and so on). 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.

pszPropName
[in] The name of the property to write. Cannot be NULL.
pVar
[in] The address of 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.

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

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.