DRIVER_DISPATCH funzione di callback (wdm.h)

  • Articolo

I servizi di routine di callback vari ip. Per un elenco di codici di funzione, vedere Osservazioni.

Sintassi

DRIVER_DISPATCH DriverDispatch;

NTSTATUS DriverDispatch(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

Parametri

[in, out] DeviceObject

Puntatore fornito dal chiamante a una struttura DEVICE_OBJECT . Si tratta dell'oggetto dispositivo per il dispositivo di destinazione, creato in precedenza dalla routine AddDevice del driver.

[in, out] Irp

Puntatore fornito dal chiamante a una struttura IRP che descrive l'operazione di I/O richiesta.

Valore restituito

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

Commenti

I parametri di input per tutte le routine dispatch vengono forniti nella struttura IRP a cui punta l'IRP. I parametri aggiuntivi vengono forniti nella posizione dello stack I/O associato del driver, descritta dalla struttura IO_STACK_LOCATION e possono essere ottenuti chiamando IoGetCurrentIrpStackLocation.

In genere, tutte le routine dispatch vengono eseguite in un contesto di thread arbitrario in IRQL = PASSIVE_LEVEL, ma esistono eccezioni. Per altre informazioni, vedere Routine di invio e IRQLs.

Per altre informazioni sulle routine di invio, vedere Scrittura di routine di invio. Per altre informazioni sui provider di servizi di integrazione, vedere Gestione dei provider di servizi di integrazione.

IRP Informazioni sull'implementazione del callback
IRP_MJ_CLEANUP La routine DispatchCleanup di un driver deve essere denominata XxxDispatchCleanup, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchCleanup in DriverObject-MajorFunction>[IRP_MJ_CLEANUP].
IRP_MJ_CLOSE La routine DispatchClose di un driver deve essere denominata XxxDispatchClose, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchClose in DriverObject-MajorFunction>[IRP_MJ_CLOSE].
IRP_MJ_CREATE La routine DispatchCreate di un driver deve essere denominata XxxDispatchCreate, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchCreate in DriverObject-MajorFunction>[IRP_MJ_CREATE].
IRP_MJ_CREATE o IRP_MJ_CLOSE Un driver può fornire una singola routine DispatchCreateClose anziché le routine DispatchCreate e DispatchClose separate.

La routine DispatchCreateClose di un driver deve essere denominata XxxDispatchCreateClose, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchCreateClose in DriverObject-MajorFunction[IRP_MJ_CREATE] e in DriverObject-MajorFunction>>[IRP_MJ_CLOSE].
IRP_MJ_DEVICE_CONTROL La routine DispatchDeviceControl di un driver deve essere denominata XxxDispatchDeviceControl, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchDeviceControl in DriverObject-MajorFunction>[IRP_MJ_DEVICE_CONTROL].

Il sistema usa i flag FILE_XXX nel codice di controllo I/O per determinare se il mittente IRP ha i privilegi per inviare l'IRP all'oggetto device. I driver per Windows Server 2003 e versioni successive di Windows possono usare la routine IoValidateDeviceIoControlAccess per eseguire controlli di accesso più rigorosi all'interno di DispatchDeviceControl.
IRP_MJ_FLUSH_BUFFERS La routine DispatchFlushBuffers di un driver deve essere denominata XxxDispatchFlushBuffers, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchFlushBuffers in DriverObject-MajorFunction>[IRP_MJ_FLUSH_BUFFERS].
IRP_MJ_INTERNAL_DEVICE_CONTROL La routine DispatchInternalDeviceControl di un driver deve essere denominata XxxDispatchInternalDeviceControl, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchInternalDeviceControl in DriverObject-MajorFunction>[IRP_MJ_INTERNAL_DEVICE_CONTROL].
IRP_MJ_PNP La routine DispatchPnP di un driver deve essere denominata XxxDispatchPnP, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchPnP in DriverObject-MajorFunction>[IRP_MJ_PNP].
IRP_MJ_POWER La routine DispatchPower di un driver deve essere denominata XxxDispatchPower, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchPower in DriverObject-MajorFunction>[IRP_MJ_POWER].
IRP_MJ_QUERY_INFORMATION La routine DispatchQueryInformation di un driver deve essere denominata XxxDispatchQueryInformation, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchQueryInformation in DriverObject-MajorFunction>[IRP_MJ_QUERY_INFORMATION].
IRP_MJ_READ La routine DispatchRead di un driver deve essere denominata XxxDispatchRead, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchRead in DriverObject-MajorFunction>[IRP_MJ_READ].
IRP_MJ_READ o IRP_MJ_WRITE Un driver può fornire una singola routine DispatchReadWrite anziché routine DispatchRead e DispatchWrite separate.

La routine DispatchReadWrite di un driver deve essere denominata XxxDispatchReadWrite, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchReadWrite in DriverObject-MajorFunction[IRP_MJ_READ] e in DriverObject-MajorFunction>>[IRP_MJ_WRITE].
IRP_MJ_SET_INFORMATION La routine DispatchSetInformation di un driver deve essere denominata XxxDispatchSetInformation, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchSetInformation in DriverObject-MajorFunction>[IRP_MJ_SET_INFORMATION].
IRP_MJ_SHUTDOWN La routine DispatchShutdown di un driver deve essere denominata XxxDispatchShutdown, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchShutdown in DriverObject-MajorFunction>[IRP_MJ_SHUTDOWN].

Inoltre, per ricevere IRP_MJ_SHUTDOWN richieste, un driver deve chiamare IoRegisterShutdownNotification o IoRegisterLastChanceShutdownNotification per registrare la routine DispatchShutdown con il sistema.
IRP_MJ_SYSTEM_CONTROL La routine DispatchSystemControl di un driver deve essere denominata XxxDispatchSystemControl, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchSystemControl in DriverObject-MajorFunction>[IRP_MJ_SYSTEM_CONTROL].
IRP_MJ_WRITE La routine DispatchWrite di un driver deve essere denominata XxxDispatchWrite, dove Xxx è un prefisso specifico del driver. La routine DriverEntry del driver deve archiviare l'indirizzo della routine DispatchWrite in DriverObject-MajorFunction>[IRP_MJ_WRITE].

Esempio

Per definire una routine di callback, è prima necessario specificare 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 usando i tipi di funzione callback consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback DispatchCleanup denominata MyDispatchCleanup, usare il tipo di DRIVER_DISPATCH, come illustrato in questo esempio di codice:

DRIVER_DISPATCH MyDispatchCleanup;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
NTSTATUS
  MyDispatchCleanup(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

Il tipo di funzione DRIVER_DISPATCH viene 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 the_Use_decl_annotations_annotation alla definizione della funzione. The_Use_decl_annotations_annotation garantisce che vengano usate le annotazioni applicate al tipo di funzione DRIVER_DISPATCH nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo 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).