SHPropertyBag_ReadBSTR

This function asks a property bag to read a named property as a string by reference.

Declaration

HRESULT
SHPropertyBag_ReadBSTR (
    IPropertyBag *ppb,
    LPCWSTR pszPropName,
    BSTR *ppszValue);

Parameters

The ppb argument provides the address of an IPropertyBag interface.

The pszPropName argument provides the address of a null-terminated Unicode string that names the property.

The ppszValue argument provides the address of a variable that is to receive the property value as a pointer to a null-terminated Unicode string.

Return Value

The function returns zero for success, else an error code.

Behaviour

If any of the ppb, pszPropName and ppszValue arguments are NULL, the function fails, with E_INVALIDARG as the error code. If the function cannot read the named property as a VT_BSTR type (using SHPropertyBag_ReadType), it fails.

The function produces the value as a pointer to a null-terminated string. Memory for this string will have been obtained when the property bag’s Read method filled a VARIANT. It may therefore be returned through SysFreeString when the caller is done with it.

Availability

The SHPropertyBag_ReadBSTR function is exported from SHLWAPI as ordinal 520 in version 6.00.

Though this function dates from 2001, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.