PropVariantToStringWithDefault function (propvarutil.h)

Article
02/22/2024

Extracts the string property value of a PROPVARIANT structure. If no value exists, then the specified default value is returned.

Syntax

PSSTDAPI_(PCWSTR) PropVariantToStringWithDefault(
  [in] REFPROPVARIANT propvarIn,
  [in] LPCWSTR        pszDefault
);

Parameters

[in] propvarIn

Type: REFPROPVARIANT

Reference to a source PROPVARIANT structure.

[in] pszDefault

Type: LPCWSTR

Pointer to a default Unicode string value, for use where no value currently exists. May be NULL.

Return value

Type: PCWSTR

Returns string value or default, or the default.

Remarks

This helper function is used in places where the calling application expects a PROPVARIANT to hold a string value and would like to use a default value if it does not. For instance, an application obtaining values from a property store can use this to safely extract the string value for string properties.

If the source PROPVARIANT has type VT_LPWSTR or VT_BSTR, this helper function returns a pointer to the value in the source PROPVARIANT. If the source PROPVARIANT has type VT_EMPTY or a conversion is not possible, then PropVariantToStringWithDefault will return the default provided by pszDefault.

Note that this function will return pointers to data supplied in the parameters. Thus the application must ensure that the data supplied to the parameters remains valid until the result is no longer in use.

Examples

The following example, to be included as part of a larger program, demonstrates how to use PropVariantToStringWithDefault to access a string value in a PROPVARIANT.

// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Title, &propvar);
if (SUCCEEDED(hr))
{
     // PKEY_Title is expected to produce a VT_LPWSTR or VT_EMPTY value.
     // The application developer decided to treat VT_EMPTY or invalid values as ""
     PCWSTR pszTitle = PropVariantToStringWithDefault(propvar, L"");
     // pszTitle is now valid.
     PropVariantClear(&propvar);
}
// ... later in the program ...
hr = ppropstore->GetValue(PKEY_Comment, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Comment is expected to produce a VT_LPWSTR or VT_EMPTY value.
         // The application developer decided to treat VT_EMPTY as NULL
         PCWSTR pszComment = PropVariantToStringWithDefault(propvar, NULL);
         if (pszComment)
         {
                 // pszComment is valid
         }
         PropVariantClear(&propvar);
}

Requirements

Requirement	Value
Minimum supported client	Windows XP with SP2, Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 with SP1 [desktop apps only]
Target Platform	Windows
Header	propvarutil.h
Library	Propsys.lib
DLL	Propsys.dll (version 6.0 or later)
Redistributable	Windows Desktop Search (WDS) 3.0

Share via