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

Статья
08/26/2023

Функция SetupDiCreateDeviceInfo создает новый элемент сведений об устройстве и добавляет его в качестве нового члена в указанный набор сведений об устройстве.

Синтаксис

WINSETUPAPI BOOL SetupDiCreateDeviceInfoA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCSTR            DeviceName,
  [in]            const GUID       *ClassGuid,
  [in, optional]  PCSTR            DeviceDescription,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            CreationFlags,
  [out, optional] PSP_DEVINFO_DATA DeviceInfoData
);

Параметры

[in] DeviceInfoSet

Дескриптор набора сведений об устройстве для локального компьютера.

[in] DeviceName

Указатель на строку, завершающуюся значением NULL, которая предоставляет полный идентификатор экземпляра устройства (например, "Root*PNP0500\0000") или идентификатор устройства с корнем без префикса перечислителя и суффикса идентификатора экземпляра (например, "*PNP0500"). Идентификатор устройства с корневым перечислением можно использовать только в том случае, если флаг DICD_GENERATE_ID указан в параметре CreationFlags .

[in] ClassGuid

Указатель на GUID класса установки устройства для устройства. Если класс настройки устройства устройства неизвестен, задайте для параметра *ClassGuid GUID_NULL структуру.

[in, optional] DeviceDescription

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

[in, optional] hwndParent

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

[in] CreationFlags

Переменная типа DWORD, которая управляет созданием элемента сведений об устройстве. Может быть сочетанием следующих значений:

DICD_GENERATE_ID

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

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

DICD_INHERIT_CLASSDRVS

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

[out, optional] DeviceInfoData

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

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

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

Если этот экземпляр устройства добавляется в набор, имеющий связанный класс, класс устройства должен быть таким же, иначе вызов завершается ошибкой. В этом случае вызов GetLastError возвращает ERROR_CLASS_MISMATCH.

Если указанный экземпляр устройства совпадает с существующим разделом экземпляра устройства в реестре, вызов завершается ошибкой. В этом случае вызов GetLastError возвращает ERROR_DEVINST_ALREADY_EXISTS. Это происходит, только если флаг DICD_GENERATE_ID не задан.

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

DeviceInfoSet должен содержать только элементы на локальном компьютере.

Примечание

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

Требования


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