Windows Dev Center

Collapse the table of content
Expand the table of content
Expand Minimize

PropVariantToStringWithDefault function

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

Syntax


PCWSTR PropVariantToStringWithDefault(
  _In_ REFPROPVARIANT propvarIn,
  _In_ LPCWSTR        pszDefault
);

Parameters

propvarIn [in]

Type: REFPROPVARIANT

Reference to a source PROPVARIANT structure.

pszDefault [in]

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

Minimum supported client

Windows XP with SP2, Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 with SP1 [desktop apps only]

Redistributable

Windows Desktop Search (WDS) 3.0

Header

Propvarutil.h

Library

Propsys.lib

DLL

Propsys.dll (version 6.0 or later)

See also

InitPropVariantFromString
PropVariantToString
PropVariantToStringAlloc
VariantToString
PropVariantChangeType

 

 

Community Additions

ADD
Show:
© 2015 Microsoft