PCANCEL_ADAPTER_CHANNEL Rückruffunktion (wdm.h)

Artikel
02/27/2024

Die CancelAdapterChannel-Routine versucht, eine ausstehende Anforderung zum Zuweisen eines DMA-Kanals abzubrechen.

Syntax

PCANCEL_ADAPTER_CHANNEL PcancelAdapterChannel;

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

Parameter

[in] DmaAdapter

Ein Zeiger auf eine DMA_ADAPTER Struktur. Diese Struktur ist das Adapterobjekt, das auf die Gewährung der ausstehenden Ressourcenzuordnungsanforderung wartet. Der Aufrufer hat diesen Zeiger aus einem vorherigen Aufruf der IoGetDmaAdapter-Routine abgerufen, und der Aufrufer übergab diesen Zeiger an den Aufruf "AllocateAdapterChannelEx", "GetScatterGatherListEx" oder "BuildScatterGatherListEx ", der die Ressourcenzuweisung angefordert hat.

[in] DeviceObject

Ein Zeiger auf eine DEVICE_OBJECT-Struktur . Diese Struktur ist das physische Geräteobjekt (PDO), das das Zielgerät für den DMA-Vorgang darstellt, für den der DMA-Kanal angefordert wurde.

[in] DmaTransferContext

Ein Zeiger auf einen DMA-Übertragungskontext. Dieser Parameterwert muss derselbe DMA-Übertragungskontext sein, der an den Aufruf AllocateAdapterChannelEx, GetScatterGatherListEx oder BuildScatterGatherListEx übergeben wurde, der die Adapterkanalzuordnung angefordert hat.

Rückgabewert

CancelAdapterChannel gibt TRUE zurück, wenn die ausstehende Zuordnungsanforderung erfolgreich abgebrochen wurde. Die Routine gibt FALSE zurück, wenn die Anforderung nicht abgebrochen werden konnte (z. B. weil der DMA-Kanal zugewiesen wurde, bevor die Anforderung abgebrochen werden konnte).

Hinweise

CancelAdapterChannel ist keine Systemroutine, die direkt mit dem Namen aufgerufen werden kann. Diese Routine kann nur durch zeiger von der Adresse aufgerufen werden, die in einer DMA_OPERATIONS-Struktur zurückgegeben wird.Treiber erhalten die Adresse dieser Routine, indem Sie IoGetDmaAdapter aufrufen, wobei das Versionselement des DeviceDescription-Parameters auf DEVICE_DESCRIPTION_VERSION3 festgelegt ist. Wenn IoGetDmaAdapterNULL zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

CancelAdapterChannel versucht, eine ausstehende Zuordnungsanforderung abzubrechen, die von einem asynchronen Aufruf einer Zuordnungsroutine wie AllocateAdapterChannelEx, GetScatterGatherListEx oder BuildScatterGatherListEx ausgeführt wurde. Beim asynchronen Aufruf kann die Zuordnungsroutine zurückgeben, während die Zuordnungsanforderung noch aussteht und bevor die vom Treiber bereitgestellte Ausführungsroutine (AdapterControl oder AdapterListControl) aufgerufen wird. Wenn CancelAdapterChannel die ausstehende Zuordnungsanforderung erfolgreich abbricht, werden die Ressourcen nicht zugeordnet, und die Ausführungsroutine wird nicht aufgerufen.

Wenn ein Treiber AllocateAdapterChannelEx aufruft, um Ressourcen für eine vom Treiber bereitgestellte AdapterControl-Routine anzufordern, und dann CancelAdapterChannel aufruft, um die Anforderung abzubrechen, kann CancelAdapterChannel einen der folgenden Werte zurückgeben:

TRUE, wenn das Adapterobjekt auf die angeforderte Zuordnung wartet, wenn der CancelAdapterChannel-Aufruf auftritt. In diesem Fall bricht CancelAdapterChannel die ausstehende Zuordnungsanforderung ab, und die AdapterControl-Routine des Treibers wird nicht aufgerufen.
FALSE, wenn die AdapterControl-Routine bereits aufgerufen wurde oder aufgerufen werden soll.

Wenn ein Treiber GetScatterGatherListEx oder BuildScatterGatherListEx aufruft, um Ressourcen für eine vom Treiber bereitgestellte AdapterListControl-Routine anzufordern, und dann CancelAdapterChannel aufruft, um die Anforderung abzubrechen, kann CancelAdapterChannel einen der folgenden Werte zurückgeben:

TRUE, wenn das Adapterobjekt auf die angeforderte Zuordnung wartet, wenn der CancelAdapterChannel-Aufruf auftritt. In diesem Fall bricht CancelAdapterChannel die ausstehende Zuordnungsanforderung ab, und die AdapterListControl-Routine des Treibers wird nicht aufgerufen.
FALSE, wenn die AdapterListControl-Routine bereits aufgerufen wurde oder aufgerufen werden soll.

CancelAdapterChannel kann zukünftige Kanalzuordnungsanforderungen, die den angegebenen DMA-Übertragungskontext verwenden, vorzeitig abbrechen. Wenn der Aufrufer beispielsweise denselben DMA-Übertragungskontext an CancelAdapterChannel und AllocateAdapterChannelEx bereitstellt und der CancelAdapterChannel-Aufruf erfolgreich ist und vor dem AllocationAdapterChannelEx-Aufruf erfolgt, wird die vom AllocateAdapterChannelEx-Aufruf angeforderte Zuordnung automatisch abgebrochen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL