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

Статья
08/26/2023

Функция SetupDiOpenDeviceInterface извлекает сведения об интерфейсе устройства и добавляет этот интерфейс в указанный набор сведений об устройстве для локальной или удаленной системы.

Синтаксис

WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceA(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PCSTR                     DevicePath,
  [in]            DWORD                     OpenFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Параметры

[in] DeviceInfoSet

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

[in] DevicePath

Указатель на строку, завершающуюся значением NULL, которая предоставляет имя открываемого интерфейса устройства. Это имя представляет собой путь к устройству Win32, который обычно получается в структуре уведомлений PnP или получается при предыдущем вызове SetupDiEnumDeviceInterfaces и связанных с ним функций.

[in] OpenFlags

Флаги, определяющие способ открытия элемента интерфейса устройства. Единственный допустимый флаг:

DIODI_NO_ADD

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

[out, optional] DeviceInterfaceData

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

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

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

Если элемент интерфейса устройства для интерфейса уже существует в DeviceInfoSet, SetupDiOpenDeviceInterface обновляет флаги. Поэтому эту функцию можно использовать для обновления флагов интерфейса устройства. Например, интерфейс мог быть неактивным при первом открытии, но впоследствии стал активным. Если элемент сведений об устройстве для базового устройства еще не присутствует в DeviceInfoSet, эта функция создает его и добавляет его в DeviceInfoSet.

Если функция успешно открывает новый интерфейс устройства, но вызывающий объект не указал допустимую структуру в параметре DeviceInterfaceData , функция вернет значение FALSE , а последующий вызов GetLastError вернет ERROR_INVALID_USER_BUFFER. Однако в этом случае SetupDiOpenDeviceInterface добавляет запрошенный интерфейс в набор сведений об устройстве.

Если новый интерфейс устройства успешно открыт, но предоставленный вызывающим объектом буфер DeviceInterfaceData недопустим, эта функция возвращает значение FALSE , а GetLastError — ERROR_INVALID_USER_BUFFER. Ошибка буфера вызывающего объекта не препятствует открытию интерфейса.

Если для параметра OpenFlags указан флаг DIODI_NO_ADD, а элемент сведений об устройстве для базового устройства еще не присутствует в указанном наборе сведений об устройстве, эта функция возвращает значение FALSE , а GetLastError — ERROR_NO_SUCH_DEVICE_INTERFACE.

После завершения работы приложения с информацией, полученной командой SetupDiOpenDeviceInterface, приложение должно вызвать SetupDiDeleteDeviceInterfaceData.

MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK атрибут можно передать в качестве значения аргумента DevicePath функции SetupDiOpenDeviceInterface .

Примечание

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

Требования

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

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

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces

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