IPropertyBag::Read

Called by the control to read a property from the storage provided by the container.

HRESULT Read(
  LPCOLESTR pszPropName,  //Pointer to the property to be read
  VARIANT* pVar,          //Pointer to the VARIANT to receive the 
                          //property value
  IErrorLog* pErrorLog    //Pointer to the caller's error log
);

Parameters

pszPropName: [in] Pointer to the name of the property to read. Cannot be NULL.
pVar: [in, out] Pointer to the caller-initialized VARIANT that is to receive the property value on output. The method must set both type and value fields in the VARIANT before returning. If the caller initialized the pVar->vt field on entry, the property bag should attempt to coerce the value it knows into this type. If the caller sets pVar->vt to VT_EMPTY, the property bag can use a convenient type that is consistent with the data. For example, if the property is a string, the property bag cannot use VT_I4.
pErrorLog: [in] Pointer to the caller's IErrorLog interface in which the property bag stores any errors that occur during reads. Can be NULL in which case the caller is not interested in errors.

Return Values

S_OK: The property was read successfully. The caller becomes responsible for any allocations that are contained in the VARIANT in pVar.
E_POINTER: The address in pszPropName is not valid (such as NULL).
E_INVALIDARG: The property named with pszPropName does not exist in the property bag.
E_FAIL: The property bag was unable to read the specified property, such as if the caller specified a data type to which the property bag could not coerce the known value. If the caller supplied an error log, a more descriptive error was sent there.

Remarks

This method asks the property bag to read the property named with pszPropName into the caller-initialized VARIANT in pVar. Errors that occur are logged in the error log pointed to by pErrorLog.

When pVar->vt specifies another object pointer (VT_UNKNOWN or VT_DISPATCH) then the property bag is responsible for creating and initializing the object described by pszPropName. The action taken by the property bag depends on the value of pvar->punkVal or pvar->vdispVal. For example, if pvar->punkVal is non-NULL, the property bag initializes the existing object using the value of the pointer, usually querying for a persistence interface and calling the Load method. However, if pVar->punkVal is NULL, then the property bag creates a new object and loads it as appropriate.

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

QuickInfo

  Windows NT: Use version 4.0 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in ocidl.h.