Функция SetupDiOpenDeviceInterfaceA (setupapi.h)
Функция 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. Ошибка буфера вызывающего абонента не препятствует открытию интерфейса.
Если флаг DIODI_NO_ADD указан для параметра
Когда приложение завершит работу с данными, которые SetupDiOpenDeviceInterface извлечены, приложение должно вызывать SetupDiDeleteDeviceInterfaceData.
MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK атрибут можно передать в качестве значения аргумента DevicePath функции SetupDiOpenDeviceInterface.
Заметка
Заголовок setupapi.h определяет SetupDiOpenDeviceInterface как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Доступно в Microsoft Windows 2000 и более поздних версиях Windows. |
| целевая платформа | Настольный |
| заголовка | setupapi.h (include Setupapi.h) |
| библиотеки |
Setupapi.lib |