Fonction SwDeviceCreate (swdevice.h)

Article
03/02/2024

Lance l’énumération d’un appareil logiciel.

Syntaxe

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
);

Paramètres

[in] pszEnumeratorName

Chaîne qui nomme l’énumérateur de l’appareil logiciel. Choisissez un nom qui représente le composant qui énumère les appareils.

[in] pszParentDeviceInstance

Chaîne qui spécifie l’id de instance de l’appareil qui est le parent de l’appareil logiciel.

Il peut s’agir de HTREE\ROOT\0, mais nous vous recommandons de limiter au minimum les enfants de l’appareil racine. Nous recommandons également que le parent préféré d’un appareil logiciel soit un appareil réel pour lequel l’appareil logiciel étend la fonctionnalité. Dans les situations où un appareil logiciel n’a pas de parent naturel, créez un appareil en tant qu’enfant de la racine qui peut collecter tous les appareils logiciels qu’un composant énumérera ; ensuite, énumérez les appareils logiciels réels en tant qu’enfants de ce nœud de regroupement d’appareils. Cela maintient les enfants de l’appareil racine à un nombre gérable.

[in] pCreateInfo

Pointeur vers une structure de SW_DEVICE_CREATE_INFO qui décrit les informations que PnP utilise pour créer l’appareil.

[in] cPropertyCount

Nombre de structures DEVPROPERTY dans le tableau pProperties .

[in, optional] pProperties

Tableau facultatif de structures DEVPROPERTY . Ces propriétés sont définies sur l’appareil après sa création, mais avant l’envoi d’une notification indiquant que l’appareil a été créé. Pour plus d’informations, consultez Remarques. Ce pointeur peut avoir la valeur NULL.

[in] pCallback

La fonction de rappel SW_DEVICE_CREATE_CALLBACK que le système d’exploitation appelle après PnP énumère l’appareil.

[in, optional] pContext

Contexte client facultatif que le système d’exploitation transmet à la fonction de rappel. Ce pointeur peut avoir la valeur NULL.

[out] phSwDevice

Pointeur vers une variable qui reçoit le handle HSWDEVICE qui représente l’appareil. Appelez SwDeviceClose pour fermer ce handle une fois que l’application cliente souhaite que PnP supprime l’appareil.


DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;

Valeur retournée

S_OK est retourné si l’énumération de l’appareil a été lancée avec succès. Cela ne signifie pas que l’appareil a été correctement énuméré. Vérifiez le paramètre CreateResult de la fonction de rappel SW_DEVICE_CREATE_CALLBACK pour déterminer si l’appareil a été correctement énuméré.

Remarques

SwDeviceCreate retourne un handle qui représente l’appareil. Une fois ce handle fermé, PnP supprime l’appareil.

Le processus d’appel doit disposer d’un accès administrateur pour lancer l’énumération d’un appareil logiciel.

PnP forme l’ID de instance d’appareil d’un appareil logiciel en tant que « SWD< ; pszEnumeratorName>< ; pszInstanceId> », mais cette chaîne peut changer ou PnP peut décorer le nom. Obtenez toujours l’ID de instance de l’appareil à partir de la fonction de rappel.

Il existe une différence subtile entre les propriétés qui sont définies dans le cadre d’un appel SwDeviceCreate et les propriétés qui sont définies ultérieurement en appelant SwDevicePropertySet. Les propriétés définies dans le cadre de SwDeviceCreate sont stockées en mémoire ; si l’appareil est désinstallé ou si un pilote null efface les magasins de propriétés, ces propriétés sont réécrites par la fonctionnalité d’API d’appareil logiciel lorsque PnP réinscrit les appareils. Tout cela est transparent pour le client. Les propriétés définies à l’aide de SwDevicePropertySet après l’énumération ne sont pas conservées en mémoire. Toutefois, si vous définissez une propriété à l’aide de SwDeviceCreate, vous pouvez mettre à jour la valeur avec SwDevicePropertySet, et cette mise à jour est appliquée à la valeur en mémoire ainsi qu’au magasin persistant.

Nous recommandons que toutes les propriétés soient spécifiées dans le cadre de l’appel à SwDeviceCreate lorsque cela est possible et que ces propriétés soient spécifiées pour chaque appel à SwDeviceCreate.

Note Le système d’exploitation peut appeler SW_DEVICE_CREATE_CALLBACK avant que l’appel à SwDeviceCreate ne retourne. Pour cette raison, le handle d’appareil logiciel de l’appareil est fourni en tant que paramètre à la fonction de rappel.

Vous pouvez créer un appareil logiciel en tant qu’enfant d’un parent qui n’est pas présent à ce moment-là. PnP énumère l’appareil logiciel une fois que le parent devient présent.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8
Serveur minimal pris en charge	Windows Server 2012
Plateforme cible	Universal
En-tête	swdevice.h
Bibliothèque	Swdevice.lib ; OneCoreUAP.lib sur Windows 10
DLL	Cfgmgr32.dll

Voir aussi

SW_DEVICE_CREATE_CALLBACK

Partager via