Поделиться через


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

Извлекает строковое значение из структуры PROPVARIANT .

Синтаксис

PSSTDAPI PropVariantToString(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          psz,
  [in]  UINT           cch
);

Параметры

[in] propvar

Тип: REFPROPVARIANT

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

[out] psz

Тип: PWSTR

Указывает на буфер строк. При возвращении этой функцией буфер инициализируется строковым значением Юникода, завершающееся null .

[in] cch

Тип: UINT

Размер буфера, на который указывает psz, в символах.

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

Тип: HRESULT

Эта функция может возвращать одно из этих значений.

Код возврата Описание
S_OK
Значение было извлечено, а буфер результата завершился со значением NULL .
STRSAFE_E_INSUFFICIENT_BUFFER
Операция копирования завершилась сбоем из-за недостаточного пространства в буфере. Целевой буфер содержит усеченную версию предполагаемого результата, завершаемую null. В ситуациях, когда усечение приемлемо, это не обязательно может рассматриваться как условие сбоя.
Другое значение ошибки
Извлечение не удалось по какой-либо другой причине.

Комментарии

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

Если исходный PROPVARIANT имеет тип VT_LPWSTR или VT_BSTR, эта функция извлекает строку и помещает ее в предоставленный буфер. В противном случае он пытается преобразовать значение в структуре PROPVARIANT в строку. Если преобразование невозможно, PropVariantToString вернет код сбоя и присвоит psz значение \0. Список возможных преобразований см. в разделе PropVariantChangeType . Обратите внимание, что VT_EMPTY успешно преобразуется в "".

В дополнение к завершающем значению NULL в буфер, на который указывает psz, записывается не более символов cch-1. Если значение в исходном PROPVARIANT больше, чем помещается в буфер, то усеченная копия строки с завершением NULL записывается в буфер, и эта функция возвращает STRSAFE_E_INSUFFICIENT_BUFFER. Результирующая строка всегда будет иметь значение NULL .

В дополнение к преобразованиям, предоставляемым PropVariantChangeType, следующие особые случаи применяются к PropVariantToString.

  • ProPVARIANTс векторным значением преобразуются в строки путем разделения каждого элемента с помощью "; ". Например, PropVariantToString преобразует вектор из трех целых чисел {3, 1, 4} в строку "3; 1; 4". Точка с запятой не зависит от текущего языкового стандарта.
  • VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT и VT_UNKNOWN значения преобразуются в строки с использованием неподдерживаемой кодировки. Невозможно декодировать строки, созданные таким образом, и формат может измениться в будущем.

Примеры

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

    // PropVariantToString will convert VT_EMPTY to "".

    // The application decided that it only needs the first 127 characters of the title, so the buffer 

    // has size 128 to account for the terminating NULL.

    WCHAR szTitle[128];

    hr = PropVariantToString(propvar, szTitle, ARRAYSIZE(szTitle));

    if (SUCCEEDED(hr) || hr == STRSAFE_E_INSUFFICIENT_BUFFER)

    {

        // szTitle is now valid and contains up to 127 characters from propvar and a terminating NULL

    }

    else

    {

        // the extraction failed

    }

    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

См. также раздел

InitPropVariantFromString

PropVariantChangeType

PropVariantGetStringElem

PropVariantToBSTR

PropVariantToStringAlloc

PropVariantToStringVector

VariantToString