DRIVER_CONTROL funzione di callback (wdm.h)

Questa routine avvia un trasferimento dati DMA o un'operazione di trasferimento dati.

Sintassi

DRIVER_CONTROL DriverControl;

IO_ALLOCATION_ACTION DriverControl(
  [in]      _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp,
  [in]      PVOID MapRegisterBase,
  [in]      PVOID Context
)
{...}

Parametri

[in] 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 . L'Irp è uguale al valore del membro CurrentIrp di DeviceObject quando è stata registrata la routine di callback.

[in] MapRegisterBase

Nel caso di AdapterControl, si tratta di un valore opaco fornito dal chiamante che rappresenta i registri della mappa assegnati dal sistema per questa operazione di trasferimento. Il driver passa questo valore a FlushAdapterBuffers, FreeMapRegisters e MapTransfer.

Nel caso di ControllerControl, questa operazione non viene usata.

[in] Context

Puntatore fornito dal chiamante alle informazioni di contesto definite dal driver, specificate in una chiamata precedente a AllocateAdapterChannel.

Valore restituito

La routine deve restituire uno dei valori definiti dall'enumerazione IO_ALLOCATION_ACTION . I driver dei dispositivi bus-master restituiscono DeallocateObject o DeallocateObjectKeepRegisters; driver che usano il sistema DMA restituiscono KeepObject.

Commenti

Per registrare una routine AdapterControl per un oggetto dispositivo specifico, un driver deve chiamare IoGetDmaAdapter per ottenere un oggetto adapter, quindi chiamare AllocateAdapterChannel per richiedere l'uso dell'adapter e fornire l'indirizzo della routine AdapterControl . Quando l'adattatore è libero, il sistema chiama la routine AdapterControl .

Se AdapterControl è stato registrato da una routine StartIo , il parametro Irp è garantito puntare all'IRP attualmente elaborato dalla routine StartIo . In caso contrario, i driver devono impostare il membro CurrentIrp della struttura dell'oggetto dispositivo prima di chiamare AllocateAdapterChannel.

Per informazioni dettagliate sull'implementazione di una routine AdapterControl , vedere Scrittura di routine AdapterControl.

La routine ControllerControl di un driver viene eseguita in un contesto di thread arbitrario in IRQL = DISPATCH_LEVEL.

Per registrare una routine ControllerControl per un oggetto dispositivo specifico, un driver deve chiamare IoCreateController per ottenere un oggetto controller, quindi chiamare IoAllocateController per richiedere l'uso del controller e fornire l'indirizzo della routine ControllerControl . Quando il controller è libero, il sistema chiama la routine ControllerControl .

Per informazioni dettagliate sull'implementazione di una routine ControllerControl , vedere Scrittura di routine ControllerControl. Vedere anche Oggetti controller.

Il tipo di funzione DRIVER_CONTROL è 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 usate le annotazioni applicate al tipo di funzione DRIVER_CONTROL 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.

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 AdapterControl denominata MyAdapterControl, usare il tipo di DRIVER_CONTROL, come illustrato in questo esempio di codice:

DRIVER_CONTROL MyAdapterControl;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
IO_ALLOCATION_ACTION
 MyAdapterControl(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp,
    PVOID  MapRegisterBase,
    PVOID  Context
    )
  {
      // Function body
  }

Requisiti

Requisito	Valore
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Chiamato in DISPATCH_LEVEL.

Vedi anche

AllocateAdapterChannel