Функция SwDeviceCreate (swdevice.h)

Статья
08/26/2023

Инициирует перечисление программного устройства.

Синтаксис

HRESULT SwDeviceCreate(
  [in]           PCWSTR                      pszEnumeratorName,
  [in]           PCWSTR                      pszParentDeviceInstance,
  [in]           const SW_DEVICE_CREATE_INFO *pCreateInfo,
  [in]           ULONG                       cPropertyCount,
  [in, optional] const DEVPROPERTY           *pProperties,
  [in]           SW_DEVICE_CREATE_CALLBACK   pCallback,
  [in, optional] PVOID                       pContext,
  [out]          PHSWDEVICE                  phSwDevice
);

Параметры

[in] pszEnumeratorName

Строка, именующая перечислитель программного устройства. Выберите имя, представляющее компонент, перечисляющий устройства.

[in] pszParentDeviceInstance

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

Это может быть HTREE\ROOT\0, но рекомендуется свести к минимуму дочерние элементы корневого устройства. Рекомендуется также, чтобы предпочтительный родительский элемент программного устройства был реальным устройством, для которое программное устройство расширяет функциональные возможности. В ситуациях, когда у программного устройства нет такого естественного родительского элемента, создайте устройство в качестве дочернего элемента корня, которое может собирать все программные устройства, перечисляемые компонентом; Затем перечислите фактические программные устройства в качестве дочерних для этого узла группирования устройств. Это позволяет сохранить дочерние элементы корневого устройства до управляемого числа.

[in] pCreateInfo

Указатель на структуру SW_DEVICE_CREATE_INFO , описывающую сведения, которые PnP использует для создания устройства.

[in] cPropertyCount

Количество структур DEVPROPERTY в массиве pProperties .

[in, optional] pProperties

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

[in] pCallback

Функция обратного вызова SW_DEVICE_CREATE_CALLBACK , которую операционная система вызывает после перечисления устройства PnP.

[in, optional] pContext

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

[out] phSwDevice

Указатель на переменную, которая получает дескриптор HSWDEVICE , представляющий устройство. Вызовите SwDeviceClose , чтобы закрыть этот дескриптор после того, как клиентское приложение хочет удалить устройство с помощью PnP.


DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;

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

S_OK возвращается, если перечисление устройств было успешно инициировано. Это не означает, что устройство было успешно перечислено. Проверьте параметр CreateResult функции обратного вызова SW_DEVICE_CREATE_CALLBACK , чтобы определить, было ли устройство успешно перечислено.

PnP формирует идентификатор экземпляра программного устройства как "SWD< pszEnumeratorName>< pszInstanceId>", но эта строка может измениться или PnP может украшать имя. Всегда получайте идентификатор экземпляра устройства из функции обратного вызова.

Существует небольшое различие между свойствами, которые задаются в рамках вызова SwDeviceCreate , и свойствами, которые позже задаются путем вызова SwDevicePropertySet. Свойства, заданные в составе SwDeviceCreate , хранятся в памяти; Если устройство удалено или драйвер null очищает хранилища свойств, эти свойства снова записываются функцией API программного устройства при повторном перечислении устройств PnP. Все это прозрачно для клиента. Свойства, заданные с помощью SwDevicePropertySet после перечисления, не сохраняются в памяти. Но если задать свойство с помощью SwDeviceCreate, можно обновить значение с помощью SwDevicePropertySet, и это обновление будет применено к значению в памяти, а также к сохраненном хранилищу.

Рекомендуется указывать все свойства как часть вызова SwDeviceCreate , когда это возможно, и указывать эти свойства для каждого вызова SwDeviceCreate.

Примечание Операционная система может вызвать SW_DEVICE_CREATE_CALLBACK до возврата вызова SwDeviceCreate . По этой причине дескриптор программного устройства для устройства предоставляется в качестве параметра функции обратного вызова.

Вы можете создать программное устройство в качестве дочернего элемента родительского устройства, отсутствующего в данный момент. PnP перечислит программное устройство после того, как родительское устройство станет присутствовать.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8
Минимальная версия сервера	Windows Server 2012
Целевая платформа	Универсальное
Верхняя часть	swdevice.h
Библиотека	Swdevice.lib; OneCoreUAP.lib в Windows 10
DLL	Cfgmgr32.dll

См. также раздел

SW_DEVICE_CREATE_CALLBACK

Поделиться через