DRIVER_ADD_DEVICE funzione di callback (wdm.h)

Articolo
03/08/2023

La routine AddDevice è responsabile della creazione di oggetti dispositivo funzionale (FDO) o di filtro degli oggetti dispositivo (FILTRO DO) per i dispositivi enumerati dal gestore Plug and Play (PnP).

Sintassi

DRIVER_ADD_DEVICE DriverAddDevice;

NTSTATUS DriverAddDevice(
  [in] _DRIVER_OBJECT *DriverObject,
  [in] _DEVICE_OBJECT *PhysicalDeviceObject
)
{...}

Parametri

[in] DriverObject

Puntatore fornito dal chiamante a una struttura DRIVER_OBJECT . Si tratta dell'oggetto driver del driver.

[in] PhysicalDeviceObject

Puntatore fornito dal chiamante a una struttura DEVICE_OBJECT che rappresenta un oggetto dispositivo fisico (PDO) creato da un driver di livello inferiore.

Valore restituito

Se la routine ha esito positivo, deve restituire STATUS_SUCCESS. In caso contrario, deve restituire uno dei valori di stato di errore definiti in Ntstatus.h.

Commenti

Tutti i driver in modalità kernel che supportano PnP devono fornire una routine AddDevice .

La routine AddDevice di un driver deve essere denominata XxxAddDevice, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine AddDevice in DriverObject-DriverExtension-AddDevice>>.

Le responsabilità principali di una routine AddDevice chiamano IoCreateDevice per creare un oggetto dispositivo, quindi chiama IoAttachDeviceToDeviceToDeviceStack per collegare l'oggetto dispositivo allo stack di dispositivi. Per informazioni dettagliate sull'implementazione della routine AddDevice di un driver, vedere Scrittura di una routine AddDevice.

Una routine AddDevice viene eseguita in un contesto di thread di sistema in IRQL = PASSIVE_LEVEL.

Esempio

Per definire una routine di callback AddDevice , è innanzitutto necessario fornire una dichiarazione di funzione che identifica il tipo di routine di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback AddDevice denominata MyAddDevice<, usare il tipo di DRIVER_ADD_DEVICE come illustrato nell'esempio di codice seguente:

DRIVER_ADD_DEVICE MyAddDevice;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
NTSTATUS
  MyAddDevice(
    struct _DRIVER_OBJECT  *DriverObject,
    struct _DEVICE_OBJECT  *PhysicalDeviceObject 
    )
  {
      // Function body
  }

Il tipo di funzione DRIVER_ADD_DEVICE è definito nel file di intestazione Wdm.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione _Use_decl_annotations_ alla definizione della funzione. L'annotazione _Use_decl_annotations_ garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione DRIVER_ADD_DEVICE nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver WDM. Per informazioni su _Use_decl_annotations_, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Chiamato in PASSIVE_LEVEL (vedere la sezione Osservazioni).

Condividi tramite