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

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

  • Статья

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

Синтаксис

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 , чтобы определить, было ли устройство успешно перечислено.

Комментарии

SwDeviceCreate возвращает дескриптор, представляющий устройство. После закрытия этого дескриптора PnP удалит устройство.

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

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