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

Статья
08/25/2023

Извлекает строку из структуры PROPVARIANT и помещает ее в структуру STRRET .

Синтаксис

PSSTDAPI PropVariantToStrRet(
  [in]  REFPROPVARIANT propvar,
  [out] STRRET         *pstrret
);

Параметры

[in] propvar

Тип: REFPROPVARIANT

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

[out] pstrret

Тип: STRRET*

Указывает на структуру STRRET . При возвращении этой функции структура инициализирована для хранения копии извлеченной строки.

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

Тип: HRESULT

Если эта функция выполняется успешно, она возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

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

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

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

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

Если извлечение выполнено успешно, функция инициализирует элемент uType структуры STRRET с STRRET_WSTR и задает элемент pOleStr этой структуры так, чтобы он указывал на выделенную копию строки. Вызывающее приложение отвечает за использование CoTaskMemFree или StrRetToStr для освобождения этой строки, когда она больше не нужна.

Примеры

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

// IPropertyStore *ppropstore;

// Assume variable ppropstore is initialized and valid

PROPVARIANT propvar = {0};

HRESULT hr = ppropstore->GetValue(PKEY_FileName, &propvar);

if (SUCCEEDED(hr))

{

    // PKEY_FileName is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToStrRet will convert VT_EMPTY to "".

    // If this were an implementation of IShellFolder::GetDisplayNameOf, strName would be a parameter and the caller would free the memory associated with the STRRET

    STRRET strName;

    hr = PropVariantToStrRet(propvar, &strName);

    if (SUCCEEDED(hr))

    {

        // strName is now valid

 

        if (strName.uType == STRRET_WSTR)

        {

            CoTaskMemFree(strName.pOleStr);

        }

    }

    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