Функция SetupDiRegisterDeviceInfo (setupapi.h)
Функция SetupDiRegisterDeviceInfo является обработчиком по умолчанию для запроса DIF_REGISTERDEVICE .
Синтаксис
WINSETUPAPI BOOL SetupDiRegisterDeviceInfo(
[in] HDEVINFO DeviceInfoSet,
[in, out] PSP_DEVINFO_DATA DeviceInfoData,
[in] DWORD Flags,
[in, optional] PSP_DETSIG_CMPPROC CompareProc,
[in, optional] PVOID CompareContext,
[out, optional] PSP_DEVINFO_DATA DupDeviceInfoData
);
Параметры
[in] DeviceInfoSet
Дескриптор набора сведений об устройстве , содержащего элемент сведений об устройстве, представляющий регистрируемое устройство. Набор сведений об устройстве не должен содержать удаленных элементов.
[in, out] DeviceInfoData
Указатель на структуру SP_DEVINFO_DATA , указывающую элемент сведений об устройстве в DeviceInfoSet. Это параметр IN-OUT, так как DeviceInfoData.При возврате devInst может быть обновлено новое значение дескриптора.
[in] Flags
Значение флага, определяющее способ регистрации устройства, которое может быть равно нулю или следующему значению:
SPRDI_FIND_DUPS
Найдите ранее существующий экземпляр устройства , соответствующий устройству, представленному DeviceInfoData. Если этот флаг не указан, экземпляр устройства регистрируется независимо от того, существует ли для него экземпляр устройства.
Если вызывающий объект предоставляет CompareProc, вызывающий объект также должен установить этот флаг.
[in, optional] CompareProc
Указатель на функцию обратного вызова сравнения, используемую при обнаружении дубликатов. Этот параметр является необязательным и может иметь значение NULL. Если указан этот параметр, функция обратного вызова вызывается для каждого экземпляра устройства, который имеет тот же класс, что и регистрируемого экземпляра устройства. Прототип функции обратного вызова выглядит следующим образом:
typedef DWORD (CALLBACK* PSP_DETSIG_CMPPROC) (
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA NewDeviceData,
IN PSP_DEVINFO_DATA ExistingDeviceData,
IN PVOID CompareContextOPTIONAL
);
Функция сравнения должна возвращать ERROR_DUPLICATE_FOUND, если обнаруживает, что два устройства являются дубликатами. В противном случае он должен вернуть NO_ERROR. При обнаружении другой ошибки функция обратного вызова должна вернуть соответствующий код ERROR_*, указывающий на сбой.
Если параметр CompareProc не указан и запрашивается обнаружение дублирования, используется поведение сравнения по умолчанию. По умолчанию выполняется сравнение сигнатуры обнаружения нового устройства с сигнатурой обнаружения всех других устройств в классе . Сигнатура обнаружения содержится в дескрипторе ресурса класса конфигурации журнала загрузки устройства.
[in, optional] CompareContext
Указатель на буфер контекста, предоставленный вызывающим объектом, который передается в функцию обратного вызова. Если параметр CompareProc не указан, этот параметр игнорируется.
[out, optional] DupDeviceInfoData
Указатель на SP_DEVINFO_DATA структуру для получения сведений об экземпляре повторяющегося устройства, если таковой имеется, обнаруженном в результате попытки регистрации этого устройства. Этот параметр является необязательным и может иметь значение NULL. Если этот параметр указан, вызывающий объект должен задать DupDeviceInfoData.cbSize to sizeof(SP_DEVINFO_DATA). Это значение будет заполнено, если функция возвращает значение FALSE, а GetLastError возвращает ERROR_DUPLICATE_FOUND. Этот элемент сведений об устройстве добавляется как член указанного DeviceInfoSet, если он еще не является элементом. Если параметр DupDeviceInfoData не указан, дубликат не добавляется в набор сведений об устройстве.
При вызове этой функции при обработке запроса DIF_REGISTERDEVICE параметр DupDeviceInfoData должен иметь значение NULL.
Возвращаемое значение
Функция возвращает значение TRUE в случае успешного выполнения. В противном случае возвращается значение FALSE , а зарегистрированная ошибка может быть получена с помощью вызова Метода GetLastError.
Комментарии
SetupDiRegisterDeviceInfo в основном предназначен для регистрации устройства, отличного от PnP, в диспетчере Plug and Play (PnP) на локальном компьютере. Хотя SetupDiRegisterDeviceInfo не завершится ошибкой, если набор сведений об устройстве предназначен для удаленного компьютера, этот результат используется ограниченно, так как набор сведений об устройстве впоследствии не может использоваться с запросами на установку DIF_Xxx или функциями SetupDiXxx , которые не поддерживают операции на удаленном компьютере. Например, вызов SetupDiCreateDevRegKey для выполнения раздела INF для нового зарегистрированного устройства на удаленном компьютере завершится ошибкой.
Не вызывайте эту функцию напрямую для экземпляров устройств PnP. Экземпляры устройств PnP автоматически регистрируются операционной системой. Однако необходимо зарегистрировать экземпляры устройств, отличных от PnP, одним из следующих способов:
- Если приложение установки использует запрос DIF_DETECT для успешного обнаружения устройства, оно также должно использовать запрос DIF_REGISTERDEVICE для регистрации экземпляра устройства. Запрос должен обрабатываться по умолчанию. (По умолчанию SetupDiCallClassInstaller сначала вызывает установщик класса и со-установщики класса для обнаружения дубликатов и регистрации экземпляра устройства. Если эти установщики не регистрируют экземпляр устройства, SetupDiCallClassInstaller вызывает SetupDiRegisterDeviceInfo для обнаружения дубликатов и регистрации экземпляра устройства.)
- Если приложение установки создает экземпляр устройства (например, путем вызова SetupDiCreateDeviceInfo), но не выполняет обнаружение дубликатов, приложение установки должно использовать запрос DIF_REGISTERDEVICE для регистрации экземпляра устройства. Запрос должен обрабатываться по умолчанию, как описано выше.
-
Если приложение установки создает новое устройство и выполняет обнаружение дубликатов, приложение установки должно использовать запрос DIF_REGISTERDEVICE, но не позволить SetupDiCallClassInstaller вызывать SetupDiRegisterDeviceInfo. Чтобы запретить setupDiCallClassInstaller вызывать SetupDiRegisterDeviceInfo, установите флаг DI_NODI_DEFAULTACTION в элементе Flags структуры SP_DEVINSTALL_PARAMS для экземпляра устройства.
Если SetupDiCallClassInstaller возвращает значение TRUE для запроса DIF_REGISTERDEVICE, установщик класса или совместное установщики класса зарегистрировали экземпляр устройства. В этом случае приложение установки может продолжить установку устройства.
Если SetupDiCallClassInstaller возвращает значение FALSE для запроса DIF_REGISTERDEVICE, установщик класса или совместное установщики класса не зарегистрировали экземпляр устройства. В этом случае приложение установки должно выполнить одно из следующих действий в зависимости от последней ошибки, возвращаемой Командой GetLastError для запроса:
- Если последняя ошибка ERROR_DI_DO_DEFAULT, приложение установки может напрямую вызвать SetupDiRegisterDeviceInfo и предоставить CompareProc для обнаружения дубликатов. Если этот вызов выполнен успешно и дубликаты не найдены, установка устройства может быть продолжена. При обнаружении дубликата SetupDiRegisterDeviceInfo возвращает значение FALSE, и приложение установки должно завершить установку устройства.
- Если последняя ошибка не ERROR_DI_DO_DEFAULT, приложение установки должно завершить установку устройства.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Доступно в Microsoft Windows 2000 и более поздних версиях Windows. |
| Целевая платформа | Персональный компьютер |
| Верхняя часть | setupapi.h (включая Setupapi.h) |
| Библиотека | Setupapi.lib |
| DLL | Setupapi.dll |