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

  • Статья

Функция 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 . Буфер должен быть не менее (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR)) байтов, чтобы содержать фиксированную часть структуры, и один null для завершения пустой строки MULTI_SZ.

Этот параметр должен иметь нулевое значение, если DeviceInterfaceDetailData имеет значение NULL.

[out, optional] RequiredSize

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

[out, optional] DeviceInfoData

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

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

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

Комментарии

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

  1. Получение требуемого размера буфера. Вызовите SetupDiGetDeviceInterfaceDetail с указателем Null DeviceInterfaceDetailData, deviceInterfaceDetailDataSize с нулевым значением и допустимой переменной RequiredSize. В ответ на такой вызов эта функция возвращает требуемый размер буфера в RequiredSize и завершается сбоем с getLastError , возвращающим ERROR_INSUFFICIENT_BUFFER.
  2. Выделите буфер соответствующего размера и вызовите функцию еще раз, чтобы получить сведения об интерфейсе.
Сведения об интерфейсе, возвращаемые этой функцией, состоят из пути к устройству, который можно передать в функции Win32, такие как CreateFile. Не пытайтесь проанализировать символическое имя пути устройства. Путь к устройству можно повторно использовать при запуске системы.

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

Примечание

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

Требования

   
Минимальная версия клиента Доступно в Microsoft Windows 2000 и более поздних версиях Windows.
Целевая платформа Персональный компьютер
Верхняя часть setupapi.h (включая Setupapi.h)
Библиотека Setupapi.lib

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

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs