Funzione SwDeviceCreate (swdevice.h)

Articolo
01/10/2024

Avvia l'enumerazione di un dispositivo software.

Sintassi

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

Parametri

[in] pszEnumeratorName

Stringa che assegna un nome all'enumeratore del dispositivo software. Scegliere un nome che rappresenta il componente che enumera i dispositivi.

[in] pszParentDeviceInstance

Stringa che specifica l'ID istanza del dispositivo che rappresenta l'elemento padre del dispositivo software.

Può trattarsi di HTREE\ROOT\0, ma è consigliabile mantenere minimo gli elementi figlio del dispositivo radice. È anche consigliabile che l'elemento padre preferito di un dispositivo software sia un dispositivo reale per il quale il dispositivo software estende la funzionalità. Nelle situazioni in cui un dispositivo software non ha un padre naturale di questo tipo, creare un dispositivo come figlio della radice in grado di raccogliere tutti i dispositivi software che un componente enumererà; enumerare quindi i dispositivi software effettivi come elementi figlio di questo nodo di raggruppamento di dispositivi. In questo modo gli elementi figlio del dispositivo radice vengono mantenuto in un numero gestibile.

[in] pCreateInfo

Puntatore a una struttura SW_DEVICE_CREATE_INFO che descrive le informazioni usate da PnP per creare il dispositivo.

[in] cPropertyCount

Numero di strutture DEVPROPERTY nella matrice pProperties .

[in, optional] pProperties

Matrice facoltativa di strutture DEVPROPERTY . Queste proprietà vengono impostate nel dispositivo dopo la creazione, ma prima dell'invio di una notifica che indica che il dispositivo è stato creato. Per altre info, vedi Osservazioni. Questo puntatore può essere NULL.

[in] pCallback

La SW_DEVICE_CREATE_CALLBACK funzione di callback che il sistema operativo chiama dopo che PnP enumera il dispositivo.

[in, optional] pContext

Contesto client facoltativo che il sistema operativo passa alla funzione di callback. Questo puntatore può essere NULL.

[out] phSwDevice

Puntatore a una variabile che riceve l'handle HSWDEVICE che rappresenta il dispositivo. Chiama SwDeviceClose per chiudere questo handle dopo che l'app client vuole che PnP rimuovono il dispositivo.


DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;

Valore restituito

S_OK viene restituito se l'enumerazione del dispositivo è stata avviata correttamente. Ciò non significa che il dispositivo è stato enumerato correttamente. Controllare il parametro CreateResult della funzione di callback SW_DEVICE_CREATE_CALLBACK per determinare se il dispositivo è stato enumerato correttamente.

Commenti

SwDeviceCreate restituisce un handle che rappresenta il dispositivo. Dopo la chiusura di questo handle, PnP rimuoverà il dispositivo.

Il processo chiamante deve avere accesso come amministratore per avviare l'enumerazione di un dispositivo software.

PnP forma l'ID istanza del dispositivo di un dispositivo software come "SWD< pszEnumeratorName>< pszInstanceId>", ma questa stringa potrebbe cambiare o PnP potrebbe decorare il nome. Ottenere sempre l'ID istanza del dispositivo dalla funzione di callback.

Esiste una sottile differenza tra le proprietà impostate come parte di una chiamata SwDeviceCreate e le proprietà che vengono successivamente impostate chiamando SwDevicePropertySet. Le proprietà impostate come parte di SwDeviceCreate vengono archiviate in memoria; se il dispositivo viene disinstallato o un driver Null cancella gli archivi delle proprietà, queste proprietà vengono scritte di nuovo dalla funzionalità API Dispositivo software quando PnP enumera nuovamente i dispositivi. Questo è tutto trasparente per il client. Proprietà impostate usando SwDevicePropertySet dopo che l'enumerazione non viene mantenuta in memoria. Tuttavia, se imposti una proprietà usando SwDeviceCreate, puoi aggiornare il valore con SwDevicePropertySet e questo aggiornamento viene applicato al valore in memoria e all'archivio persistente.

È consigliabile specificare tutte le proprietà come parte della chiamata a SwDeviceCreate quando possibile e che queste proprietà vengano specificate per ogni chiamata a SwDeviceCreate.

Nota Il sistema operativo potrebbe chiamare SW_DEVICE_CREATE_CALLBACK prima che la chiamata a SwDeviceCreate restituisca . Per questo motivo, l'handle del dispositivo software per il dispositivo viene fornito come parametro per la funzione di callback.

È possibile creare un dispositivo software come figlio di un elemento padre che non è presente al momento. PnP enumera il dispositivo software dopo che l'elemento padre diventa presente.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8
Server minimo supportato	Windows Server 2012
Piattaforma di destinazione	Universale
Intestazione	swdevice.h
Libreria	Swdevice.lib; OneCoreUAP.lib in Windows 10
DLL	Cfgmgr32.dll

Vedi anche

SW_DEVICE_CREATE_CALLBACK

Condividi tramite