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

Статья
03/15/2023

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

Синтаксис

PSSTDAPI PropVariantToStringVectorAlloc(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          **pprgsz,
  [out] ULONG          *pcElem
);

Параметры

[in] propvar

Тип: REFPROPVARIANT

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

[out] pprgsz

Тип: PWSTR**

При возврате этой функции содержит указатель на вектор строк, извлеченных из исходной структуры PROPVARIANT .

[out] pcElem

Тип: ULONG*

При возврате этой функции содержит количество строковых элементов, извлеченных из исходной структуры PROPVARIANT .

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

Тип: HRESULT

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

Код возврата	Описание
S_OK	Возвращает S_OK в случае успешного выполнения или значение ошибки в противном случае.
E_INVALIDARG	PROPVARIANT не был соответствующего типа.

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

Если BSTR в исходном PROPVARIANT имеет значение NULL, эта функция поместит новую выделенную строку, содержащую "", в выходной вектор.

Примеры

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

// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Keywords, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Keywords is expected to produce a VT_VECTOR | VT_LPWSTR, or VT_EMPTY
         // PropVariantToStringVectorAlloc will return an error for VT_EMPTY
         LPWSTR *prgKeywords;
         ULONG cElem;
         hr = PropVariantToStringVectorAlloc (propvar, &prgKeywords, &cElem);
         if (SUCCEEDED(hr))
         {
                 // prgKeywords contains cElem strings
                 for (ULONG i = 0; i < cElem; i++)
                 {
                          CoTaskMemFree(prgKeywords[i]);
                 }
                 CoTaskMemFree(prgKeywords);
         }
         else
         {
                 // propvar either is VT_EMPTY, or contains something other than a vector of  strings
         }
         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