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

Функция 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 (include Setupapi.h)
библиотеки	Setupapi.lib

См. также

SP_DEVINFO_DATA

SetupDiDeleteDeviceInfo

SetupDiEnumDeviceInfo

SetupDiOpenDeviceInfo