Функция PropVariantToStringWithDefault (propvarutil.h)

Статья
08/25/2023

Извлекает значение строкового свойства структуры PROPVARIANT . Если значение не существует, возвращается указанное значение по умолчанию.

Синтаксис

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

Параметры

[in] propvarIn

Тип: REFPROPVARIANT

Ссылка на исходную структуру PROPVARIANT .

[in] pszDefault

Тип: LPCWSTR

Указатель на строковое значение Юникода по умолчанию для использования там, где в настоящее время нет значения. Может иметь значение NULL.

Возвращаемое значение

Тип: PCWSTR

Возвращает строковое значение, значение по умолчанию или значение по умолчанию.

Эта вспомогающая функция используется в тех местах, где вызывающее приложение ожидает proPVARIANT для хранения строкового значения и хочет использовать значение по умолчанию, если это не так. Например, приложение, получающее значения из хранилища свойств, может использовать это для безопасного извлечения строкового значения для строковых свойств.

Если исходный PROPVARIANT имеет тип VT_LPWSTR или VT_BSTR, эта вспомогающая функция возвращает указатель на значение в исходном PROPVARIANT. Если исходный PROPVARIANT имеет тип VT_EMPTY или преобразование невозможно, то PropVariantToStringWithDefault вернет значение по умолчанию, предоставленное pszDefault.

Обратите внимание, что эта функция возвращает указатели на данные, указанные в параметрах . Таким образом, приложение должно гарантировать, что данные, предоставленные параметрам, остаются действительными, пока результат больше не будет использоваться.

Примеры

В следующем примере, который будет включен в состав более крупной программы, показано, как использовать PropVariantToStringWithDefault для доступа к строкового значения в 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);
}

Требования

Требование	Значение
Минимальная версия клиента	Windows XP с пакетом обновления 2 (SP2), Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2003 с пакетом обновления 1 (SP1) [только классические приложения]
Целевая платформа	Windows
Header	propvarutil.h
Библиотека	Propsys.lib
DLL	Propsys.dll (версия 6.0 или более поздняя)
Распространяемые компоненты	Windows Desktop Search (WDS) 3.0