PCANCEL_ADAPTER_CHANNEL fungsi panggilan balik (wdm.h)

Artikel
07/02/2025

Rutinitas CancelAdapterChannel mencoba membatalkan permintaan yang tertunda untuk mengalokasikan saluran DMA.

Sintaksis

C++

PCANCEL_ADAPTER_CHANNEL PcancelAdapterChannel;

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

Parameter

[in] DmaAdapter

Penunjuk ke struktur DMA_ADAPTER. Struktur ini adalah objek adaptor yang menunggu permintaan alokasi sumber daya yang tertunda diberikan. Pemanggil memperoleh pointer ini dari panggilan sebelumnya ke IoGetDmaAdapter rutin, dan pemanggil meneruskan penunjuk ini ke AllocateAdapterChannelEx, GetScatterGatherListEx, atau BuildScatterGatherListEx memanggil yang meminta alokasi sumber daya.

[in] DeviceObject

Penunjuk ke struktur DEVICE_OBJECT. Struktur ini adalah objek perangkat fisik (PDO) yang mewakili perangkat target untuk operasi DMA tempat saluran DMA diminta.

[in] DmaTransferContext

Penunjuk ke konteks transfer DMA. Nilai parameter ini harus konteks transfer DMA yang sama yang diteruskan ke AllocateAdapterChannelEx, GetScatterGatherListEx, atau BuildScatterGatherListEx memanggil yang meminta alokasi saluran adaptor.

Mengembalikan nilai

CancelAdapterChannel mengembalikan TRUE jika permintaan alokasi yang tertunda berhasil dibatalkan. Rutinitas mengembalikan FALSE jika permintaan tidak dapat dibatalkan (misalnya, karena saluran DMA dialokasikan sebelum permintaan dapat dibatalkan).

Komentar

CancelAdapterChannel bukanlah rutinitas sistem yang dapat dipanggil langsung dengan nama. Rutinitas ini hanya dapat dipanggil oleh pointer dari alamat yang dikembalikan dalam struktur DMA_OPERATIONS. Driver mendapatkan alamat rutinitas ini dengan memanggil IoGetDmaAdapter dengan anggota Versi parameter DeviceDescription diatur ke DEVICE_DESCRIPTION_VERSION3. Jika IoGetDmaAdapter mengembalikan NULL, rutinitas tidak tersedia di platform Anda.

CancelAdapterChannel mencoba membatalkan permintaan alokasi tertunda yang dilakukan oleh panggilan asinkron ke rutinitas alokasi seperti AllocateAdapterChannelEx, GetScatterGatherListEx, atau BuildScatterGatherListEx. Ketika dipanggil secara asinkron, rutinitas alokasi dapat kembali saat permintaan alokasi masih tertunda dan sebelum rutinitas eksekusi yang disediakan driver (AdapterControl atau AdapterListControl) dipanggil. Jika CancelAdapterChannel berhasil membatalkan permintaan alokasi yang tertunda, sumber daya tidak dialokasikan dan rutinitas eksekusi tidak dipanggil.

Jika driver memanggil AllocateAdapterChannelEx untuk meminta sumber daya untuk adapter AdapterControl rutin yang disediakan driver, lalu memanggil CancelAdapterChannel untuk membatalkan permintaan, CancelAdapterChannel dapat mengembalikan salah satu nilai berikut:

TRUE, jika objek adaptor menunggu alokasi yang diminta saat panggilan CancelAdapterChannel terjadi. Dalam hal ini, CancelAdapterChannel membatalkan permintaan alokasi yang tertunda, dan rutinitas AdapterControl driver tidak dipanggil.
FALSE, jika rutinitas AdapterControl sudah dipanggil atau akan dipanggil.

Demikian pula, jika driver memanggil GetScatterGatherListEx atau BuildScatterGatherListEx untuk meminta sumber daya untuk rutinitas AdapterListControl yang disediakan driver, lalu memanggil CancelAdapterChannel untuk membatalkan permintaan, CancelAdapterChannel dapat mengembalikan salah satu nilai berikut:

TRUE, jika objek adaptor menunggu alokasi yang diminta saat panggilan CancelAdapterChannel terjadi. Dalam hal ini, CancelAdapterChannel membatalkan permintaan alokasi yang tertunda, dan rutinitas AdapterListControl driver tidak dipanggil.
FALSE, jika rutinitas AdapterListControl sudah dipanggil atau akan dipanggil.

CancelAdapterChannel dapat membatalkan permintaan alokasi saluran mendatang terlebih dahulu yang menggunakan konteks transfer DMA yang ditentukan. Misalnya, jika pemanggil menyediakan konteks transfer DMA yang sama ke cancelAdapterChannel dan AllocateAdapterChannelEx, dan panggilan CancelAdapterChannel berhasil dan terjadi sebelum panggilan AllocateAdapterChannelEx, alokasi yang diminta oleh panggilan AllocateAdapterChannelEx dibatalkan secara otomatis.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Tersedia dimulai dengan Windows 8.
Platform Target	Desktop
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL