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