Функция SetupDiGetDeviceInterfaceDetailA (setupapi.h)

Статья
11/20/2024

Функция SetupDiGetDeviceInterfaceDetail возвращает сведения об интерфейсе устройства.

Синтаксис

WINSETUPAPI BOOL SetupDiGetDeviceInterfaceDetailA(
  [in]            HDEVINFO                           DeviceInfoSet,
  [in]            PSP_DEVICE_INTERFACE_DATA          DeviceInterfaceData,
  [out, optional] PSP_DEVICE_INTERFACE_DETAIL_DATA_A DeviceInterfaceDetailData,
  [in]            DWORD                              DeviceInterfaceDetailDataSize,
  [out, optional] PDWORD                             RequiredSize,
  [out, optional] PSP_DEVINFO_DATA                   DeviceInfoData
);

Параметры

[in] DeviceInfoSet

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

[in] DeviceInterfaceData

Указатель на структуру SP_DEVICE_INTERFACE_DATA, указывающую интерфейс в DeviceInfoSet для получения сведений. Указатель этого типа обычно возвращается SetupDiEnumDeviceInterfaces.

[out, optional] DeviceInterfaceDetailData

Указатель на структуру SP_DEVICE_INTERFACE_DETAIL_DATA для получения сведений об указанном интерфейсе. Этот параметр является необязательным и может быть null. Этот параметр должен быть null, если DeviceInterfaceDetailSize равно нулю. Если этот параметр указан, вызывающий объект должен задать DeviceInterfaceDetailData.cbSize значением sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA) перед вызовом этой функции. Элемент cbSize всегда содержит размер фиксированной части структуры данных, а не размер, отражающий строку переменной длины в конце.

[in] DeviceInterfaceDetailDataSize

Размер буфера deviceInterfaceDetailData DeviceInterfaceDetailData. Буфер должен быть по крайней мере (смещение(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + размер(TCHAR)), чтобы содержать фиксированную часть структуры и одну NULL, чтобы завершить пустую строку MULTI_SZ.

Этот параметр должен быть равен нулю, если DeviceInterfaceDetailDataNULL.

[out, optional] RequiredSize

Указатель на переменную типа DWORD, которая получает требуемый размер буфера DeviceInterfaceDetailData. Этот размер включает размер фиксированной части структуры и количество байтов, необходимых для строки пути устройства переменной длины. Этот параметр является необязательным и может быть null.

[out, optional] DeviceInfoData

Указатель на буфер, который получает сведения об устройстве, поддерживающем запрошенный интерфейс. Вызывающий объект должен задать DeviceInfoData.cbSize значение sizeof(SP_DEVINFO_DATA). Этот параметр является необязательным и может быть null.

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

SetupDiGetDeviceInterfaceDetail возвращает TRUE, если функция завершена без ошибок. Если функция завершена с ошибкой, возвращается FALSE, а код ошибки для сбоя можно получить путем вызова GetLastError.

Замечания

Использование этой функции для получения сведений об интерфейсе обычно представляет собой двухэтапный процесс:

Получите требуемый размер буфера. Вызов SetupDiGetDeviceInterfaceDetail с NULLуказателем DeviceInterfaceDetailData, DeviceInterfaceDetailDataSize и допустимой переменной RequiredSize. В ответ на такой вызов эта функция возвращает требуемый размер буфера в RequiredSize и завершается ошибкой GetLastError возврата ERROR_INSUFFICIENT_BUFFER.
Выделите буфер соответствующего размера и снова вызовите функцию, чтобы получить сведения об интерфейсе.

Сведения об интерфейсе, возвращаемые этой функцией, состоят из пути устройства, который можно передать в функции Win32, такие как CreateFile. Не пытайтесь проанализировать символическое имя пути устройства. Путь к устройству можно повторно использовать во всех запусках системы.

SetupDiGetDeviceInterfaceDetail можно использовать для получения только DeviceInfoData. Если интерфейс существует, но DeviceInterfaceDetailData NULL, эта функция завершается ошибкой, GetLastError возвращает ERROR_INSUFFICIENT_BUFFER, а структура DeviceInfoData заполняется информацией об устройстве, предоставляющего интерфейс.

Заметка

Заголовок setupapi.h определяет SetupDiGetDeviceInterfaceDetail как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно в Microsoft Windows 2000 и более поздних версиях Windows.
целевая платформа	Настольный
заголовка	setupapi.h (include Setupapi.h)
библиотеки	Setupapi.lib

См. также

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs

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