Функция SetupDiCreateDeviceInfoW (setupapi.h)
Функция SetupDiCreateDeviceInfo создает новый элемент сведений об устройстве и добавляет его в качестве нового члена в указанный набор сведений об устройстве.
Синтаксис
WINSETUPAPI BOOL SetupDiCreateDeviceInfoW(
[in] HDEVINFO DeviceInfoSet,
[in] PCWSTR DeviceName,
[in] const GUID *ClassGuid,
[in, optional] PCWSTR 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 |