PCANCEL_ADAPTER_CHANNEL funzione di callback (wdm.h)

Articolo
03/08/2023

La routine CancelAdapterChannel tenta di annullare una richiesta in sospeso per allocare un canale DMA.

Sintassi

PCANCEL_ADAPTER_CHANNEL PcancelAdapterChannel;

BOOLEAN PcancelAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PVOID DmaTransferContext
)
{...}

Parametri

[in] DmaAdapter

Puntatore a una struttura DMA_ADAPTER . Questa struttura è l'oggetto adapter in attesa della richiesta di allocazione delle risorse in sospeso. Il chiamante ha ottenuto questo puntatore da una chiamata precedente alla routine IoGetDmaAdapter e il chiamante ha passato questo puntatore all'oggetto AllocateAdapterChannelEx, GetScatterGatherListEx o BuildScatterGatherListEx che ha richiesto l'allocazione della risorsa.

[in] DeviceObject

Puntatore a una struttura DEVICE_OBJECT . Questa struttura è l'oggetto dispositivo fisico (PDO) che rappresenta il dispositivo di destinazione per l'operazione DMA per cui è stato richiesto il canale DMA.

[in] DmaTransferContext

Puntatore a un contesto di trasferimento DMA. Questo valore di parametro deve essere lo stesso contesto di trasferimento DMA passato alla chiamata AllocateAdapterChannelEx, GetScatterGatherListEx o BuildScatterGatherListEx che ha richiesto l'allocazione del canale dell'adattatore.

Valore restituito

CancelAdapterChannel restituisce TRUE se la richiesta di allocazione in sospeso viene annullata correttamente. La routine restituisce FALSE se la richiesta non può essere annullata, ad esempio perché il canale DMA è stato allocato prima che la richiesta possa essere annullata.

Commenti

CancelAdapterChannel non è una routine di sistema che può essere chiamata direttamente in base al nome. Questa routine può essere chiamata solo dal puntatore dall'indirizzo restituito in una struttura DMA_OPERATIONS. I driver ottengono l'indirizzo di questa routine chiamando IoGetDmaAdapter con il membro Version del parametro DeviceDescription impostato su DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter restituisce NULL, la routine non è disponibile nella piattaforma.

CancelAdapterChannel tenta di annullare una richiesta di allocazione in sospeso effettuata da una chiamata asincrona a una routine di allocazione, ad esempio AllocateAdapterChannelEx, GetScatterGatherListEx o BuildScatterGatherListEx. Quando viene chiamato in modo asincrono, la routine di allocazione può restituire mentre la richiesta di allocazione è ancora in sospeso e prima che venga chiamata la routine di esecuzione fornita dal driver (AdapterControl o AdapterListControl). Se CancelAdapterChannel annulla correttamente la richiesta di allocazione in sospeso, le risorse non vengono allocate e la routine di esecuzione non viene chiamata.

Se un driver chiama AllocateAdapterChannelEx per richiedere risorse per una routine AdapterControl fornita dal driver e quindi chiama CancelAdapterChannel per annullare la richiesta, CancelAdapterChannel può restituire uno dei valori seguenti:

TRUE, se l'oggetto adapter è in attesa dell'allocazione richiesta quando si verifica la chiamata CancelAdapterChannel . In questo caso , CancelAdapterChannel annulla la richiesta di allocazione in sospeso e la routine AdapterControl del driver non viene chiamata.
FALSE, se la routine AdapterControl è già stata chiamata o sta per essere chiamata.

Analogamente, se un driver chiama GetScatterGatherListEx o BuildScatterGatherListEx per richiedere risorse per una routine AdapterListControl fornita dal driver e quindi chiama CancelAdapterChannel per annullare la richiesta, CancelAdapterChannel può restituire uno dei valori seguenti:

TRUE, se l'oggetto adapter è in attesa dell'allocazione richiesta quando si verifica la chiamata CancelAdapterChannel . In questo caso , CancelAdapterChannel annulla la richiesta di allocazione in sospeso e la routine AdapterListControl del driver non viene chiamata.
FALSE, se la routine AdapterListControl è già stata chiamata o sta per essere chiamata.

CancelAdapterChannel può annullare in modo preliminare le richieste di allocazione dei canali future che usano il contesto di trasferimento DMA specificato. Ad esempio, se il chiamante fornisce lo stesso contesto di trasferimento DMA a CancelAdapterChannel e AllocateAdapterChannelEx e la chiamata CancelAdapterChannel ha esito positivo e si verifica prima della chiamata AllocateAdapterChannelEx , l'allocazione richiesta dalla chiamata AllocateAdapterChannelEx viene annullata automaticamente.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL