SwDeviceCreate-Funktion (swdevice.h)

Artikel
03/06/2024

Initiiert die Enumeration eines Softwaregeräts.

Syntax

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

Parameter

[in] pszEnumeratorName

Eine Zeichenfolge, die den Enumerator des Softwaregeräts benennt. Wählen Sie einen Namen aus, der die Komponente darstellt, die die Geräte aufzählt.

[in] pszParentDeviceInstance

Eine Zeichenfolge, die das Gerät instance ID des Geräts angibt, das das übergeordnete Gerät des Softwaregeräts ist.

Dies kann HTREE\ROOT\0 sein, es wird jedoch empfohlen, untergeordnete Elemente des Stammgeräts auf ein Minimum zu beschränken. Außerdem wird empfohlen, dass das bevorzugte übergeordnete Element eines Softwaregeräts ein echtes Gerät ist, für das das Softwaregerät die Funktionalität erweitert. Erstellen Sie in Situationen, in denen ein Softwaregerät nicht über ein solches natürliches übergeordnetes Element verfügt, ein Gerät als untergeordnetes Element des Stammes, das alle Softwaregeräte sammeln kann, die eine Komponente aufzählt. enumerieren Sie dann die tatsächlichen Softwaregeräte als untergeordnete Elemente dieses Gerätegruppierungsknotens. Dadurch bleiben die untergeordneten Elemente des Stammgeräts auf einer verwaltbaren Zahl.

[in] pCreateInfo

Ein Zeiger auf eine SW_DEVICE_CREATE_INFO-Struktur , die Informationen beschreibt, die PnP zum Erstellen des Geräts verwendet.

[in] cPropertyCount

Die Anzahl der DEVPROPERTY-Strukturen im pProperties-Array .

[in, optional] pProperties

Ein optionales Array von DEVPROPERTY-Strukturen . Diese Eigenschaften werden auf dem Gerät festgelegt, nachdem es erstellt wurde, aber bevor eine Benachrichtigung gesendet wird, dass das Gerät erstellt wurde. Weitere Informationen finden Sie unter Hinweise. Dieser Zeiger kann NULL sein.

[in] pCallback

Die SW_DEVICE_CREATE_CALLBACK Rückruffunktion, die das Betriebssystem aufruft, nachdem PnP das Gerät aufgezählt hat.

[in, optional] pContext

Ein optionaler Clientkontext, den das Betriebssystem an die Rückruffunktion übergibt. Dieser Zeiger kann NULL sein.

[out] phSwDevice

Ein Zeiger auf eine Variable, die das HSWDEVICE-Handle empfängt, das das Gerät darstellt. Rufen Sie SwDeviceClose auf, um dieses Handle zu schließen, nachdem die Client-App PnP das Gerät entfernen möchte.


DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;

Rückgabewert

S_OK wird zurückgegeben, wenn die Geräteenumeration erfolgreich initiiert wurde. Dies bedeutet nicht, dass das Gerät erfolgreich aufgezählt wurde. Überprüfen Sie den CreateResult-Parameter der SW_DEVICE_CREATE_CALLBACK Rückruffunktion, um festzustellen, ob das Gerät erfolgreich aufgezählt wurde.

Hinweise

SwDeviceCreate gibt ein Handle zurück, das das Gerät darstellt. Nachdem dieses Handle geschlossen wurde, entfernt PnP das Gerät.

Der aufrufende Prozess muss über Administratorzugriff verfügen, um die Enumeration eines Softwaregeräts zu initiieren.

PnP bildet das Gerät instance ID eines Softwaregeräts als "SWD< pszEnumeratorName>< pszInstanceId>", aber diese Zeichenfolge kann sich ändern, oder PnP könnte den Namen schmücken. Rufen Sie immer die Geräte-instance-ID aus der Rückruffunktion ab.

Es gibt einen geringfügigen Unterschied zwischen Eigenschaften, die als Teil eines SwDeviceCreate-Aufrufs festgelegt werden, und Eigenschaften, die später durch Aufrufen von SwDevicePropertySet festgelegt werden. Eigenschaften, die als Teil von SwDeviceCreate festgelegt werden, werden im Arbeitsspeicher gespeichert. Wenn das Gerät deinstalliert wird oder ein NULL-Treiber die Eigenschaftenspeicher löscht, werden diese Eigenschaften von der Softwaregeräte-API-Funktion erneut geschrieben, wenn PnP die Geräte erneut aufzählt. Dies alles ist für den Client transparent. Eigenschaften, die mit SwDevicePropertySet nach der Enumeration festgelegt werden, bleiben nicht im Arbeitsspeicher erhalten. Wenn Sie jedoch eine Eigenschaft mithilfe von SwDeviceCreate festlegen, können Sie den Wert mit SwDevicePropertySet aktualisieren, und dieses Update wird sowohl auf den Wert im Arbeitsspeicher als auch auf den persistenten Speicher angewendet.

Es wird empfohlen, nach Möglichkeit alle Eigenschaften im Rahmen des Aufrufs von SwDeviceCreate anzugeben und diese Eigenschaften für jeden Aufruf von SwDeviceCreate anzugeben.

Hinweis Möglicherweise ruft das Betriebssystem SW_DEVICE_CREATE_CALLBACK auf, bevor der Aufruf von SwDeviceCreate zurückgibt. Aus diesem Grund wird das Softwaregerätehandle für das Gerät als Parameter für die Rückruffunktion bereitgestellt.

Sie können ein Softwaregerät als untergeordnetes Element eines übergeordneten Geräts erstellen, das zu diesem Zeitpunkt nicht vorhanden ist. PnP listet das Softwaregerät auf, nachdem das übergeordnete Element vorhanden ist.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8
Unterstützte Mindestversion (Server)	Windows Server 2012
Zielplattform	Universell
Header	swdevice.h
Bibliothek	Swdevice.lib; OneCoreUAP.lib auf Windows 10
DLL	Cfgmgr32.dll

Weitere Informationen

SW_DEVICE_CREATE_CALLBACK

Freigeben über