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

Статья
08/26/2023

Функция SetupDiCreateDeviceInterface регистрирует интерфейс устройства в локальной или удаленной системе.

Синтаксис

WINSETUPAPI BOOL SetupDiCreateDeviceInterfaceA(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA          DeviceInfoData,
  [in]            const GUID                *InterfaceClassGuid,
  [in, optional]  PCSTR                     ReferenceString,
  [in]            DWORD                     CreationFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Параметры

[in] DeviceInfoSet

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

[in] DeviceInfoData

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

[in] InterfaceClassGuid

Указатель на GUID класса, указывающий класс интерфейса для нового интерфейса.

[in, optional] ReferenceString

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

[in] CreationFlags

Зарезервировано. Должен равняться нулю.

[out, optional] DeviceInterfaceData

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

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

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

SetupDiCreateDeviceInterface регистрирует интерфейс для устройства. Если устройство имеет несколько интерфейсов, вызовите эту функцию один раз для каждого зарегистрированного интерфейса.

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

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

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

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

Примечание

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

Требования

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

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

SetupDiOpenDeviceInterfaceRegKey

SetupDiRemoveDeviceInterface