PropVariantToStringWithDefault function (propvarutil.h)

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

See also

InitPropVariantFromString

PropVariantChangeType

PropVariantToString

PropVariantToStringAlloc

VariantToString