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

Статья
03/05/2024

Извлекает значение буфера из структуры PROPVARIANT типа VT_VECTOR | VT_UI1 или VT_ARRRAY | VT_UI1.

Синтаксис

PSSTDAPI PropVariantToBuffer(
  [in]  REFPROPVARIANT propvar,
  [out] void           *pv,
  [in]  UINT           cb
);

Параметры

[in] propvar

Тип: REFPROPVARIANT

Исходная структура PROPVARIANT .

[out] pv

Тип: VOID*

Указатель на буфер длиной cb байт. При возврате этой функции содержит первые cb-байты извлеченного значения буфера.

[in] cb

Тип: UINT

Длина буфера в байтах.

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

Тип: HRESULT

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

Код возврата	Описание
S_OK	В противном случае — значение ошибки.
E_INVALIDARG	PROPVARIANT был неправильного типа.
E_FAIL	ЗначениеPROPVARIANT было меньше cb байт.

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

Если исходный PROPVARIANT имеет тип VT_VECTOR | VT_UI1 или VT_ARRAY | VT_UI1 эта функция извлекает первые кб-байты из значения и помещает их в буфер, на который указывает pv. Если значение содержит меньше cb байт, то PropVariantToBuffer завершается сбоем и буфер не изменяется. Если значение содержит более кб байтов, то PropVariantToBuffer выполняется успешно и усекает значение.

Примеры

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

// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_FindData, &propvar);

if (SUCCEEDED(hr))
{
    // PKEY_FindData is expected to produce a VT_VECTOR | VT_UI1 with sizeof(WIN32_FIND_DATAW) bytes
    // We need to verify that the value length is acceptable before calling PropVariantToBuffer
    hr = E_UNEXPECTED;
    
    if (PropVariantGetElementCount(propvar) == sizeof(WIN32_FIND_DATAW))
    {
        WIN32_FIND_DATAW wfd;
        hr = PropVariantToBuffer(propvar, &wfd, sizeof(wfd));
        
        if (SUCCEEDED(hr))
        {
            // wfd is now initialized
        }
    }
    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

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

InitPropVariantFromBuffer

VariantToBuffer

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