ioGetDmaAdapter 函式 (wdm.h)
IoGetDmaAdapter 例程會傳回實體裝置物件的 DMA 配接器結構的指標。
語法
_DMA_ADAPTER * IoGetDmaAdapter(
[in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
[in] _DEVICE_DESCRIPTION *DeviceDescription,
[out] PULONG NumberOfMapRegisters
);
參數
[in, optional] PhysicalDeviceObject
要求 DMA 配接器結構的裝置實體裝置物件的指標。
[in] DeviceDescription
DEVICE_DESCRIPTION 結構的指標，其描述實體裝置的屬性。 不論DEVICE_DESCRIPTION結構中設定的版本為何，此函式一律會傳 DMA_ADAPTER->Version == 1回 。
[out] NumberOfMapRegisters
在輸出上，驅動程式可配置給任何 DMA 傳輸作業的對應緩存器數目上限指標。
傳回值
IoGetDmaAdapter 會傳回 DMA_ADAPTER 結構的指標，其中包含支持系統定義 DMA 作業之函式的指標。 如果無法配置 結構，則例程會傳回 NULL。 請參閱上述版本批注，以取得 DeviceDescription 參數的描述。
備註
呼叫此例程之前，驅動程式必須以零起始 DeviceDescription 指向的DEVICE_DESCRIPTION結構，然後將其裝置的相關信息新增至此結構。
成功時，例程的傳回值會指向 DMA_ADAPTER 結構。 此結構包含 DMA_OPERATIONS 結構的指標，這是驅動程式後續可用來執行 DMA 作業之函式的指標數據表。 例程所傳回的這個 結構版本會依下列方式決定：
如果驅動程式將DEVICE_DESCRIPTION結構的 Version 成員設定為DEVICE_DESCRIPTION_VERSION或DEVICE_DESCRIPTION_VERSION1，則傳回的DMA_ADAPTER結構會指向DMA_OPERATIONS結構的第 1 版。
如果驅動程式設定 Version = DEVICE_DESCRIPTION_VERSION2，如果支援第 2 版，傳回 DMA_ADAPTER 結構會指向第 2 版 DMA_OPERATIONS 結構;否則，例程會傳回 NULL。 驅動程式必須檢查是否支援第 2 版，才能嘗試使用任何第 2 版函式。
如果驅動程式設定 Version = DEVICE_DESCRIPTION_VERSION3，如果支援第 3 版，傳回 DMA_ADAPTER 結構會指向第 3 版 DMA_OPERATIONS 結構;否則，例程會傳回 NULL。 驅動程式必須檢查是否支援第 3 版，才能嘗試使用任何第 3 版函式。 從 Windows 8 開始，支援第3版。
當呼叫 PnP 驅動程式的 AddDevice 例程或處理裝置的 PnP IRP_MN_START_DEVICE要求時，PnP 驅動程式會呼叫 IoGetDmaAdapter。 此 IRP 包含驅動程式必須在 DeviceDescription 結構中提供之裝置硬體資源的相關信息。
呼叫端會使用 DeviceDescription 結構中的 MaximumLength 成員，指出它可以使用的最佳地圖緩存器數目。 I/O 管理員會嘗試配置足夠的對應緩存器，以容納此大小上限的 DMA 傳輸作業。 輸出時，I/O 管理員會在 NumberOfMapRegisters 參數中傳回它配置的對應緩存器數目。 驅動程式應該檢查傳回的值;不保證驅動程式會收到所要求的相同地圖緩存器數目。
若要釋放配接器對象，驅動程式應該透過DMA_ADAPTER結構中傳回的指標呼叫 PutDmaAdapter。
如先前所述，如果 IoGetDmaAdapter 不支援 DeviceDescription-Version> 所指定的DMA_ADAPTER結構版本，IoGetDmaAdapter 會傳回 NULL。 呼叫端應該依賴這個行為來判斷例程是否傳回所要求版本的 DMA_ADAPTER 結構的指標。 當 IoGetDmaAdapter 傳回 第 1 版或第 2 版或第 3 版DMA_ADAPTER結構的指標時，此結構的 Version 成員一律會設定為 1。 因此，呼叫端無法使用所傳回之 DMA_ADAPTER 結構的 Version 成員來區分這個結構的版本 1、2 和 3。
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | Universal |
| 標頭 | wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h) |
| 程式庫 | NtosKrnl.lib |
| Dll | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 合規性規則 | HwStorPortProhibitedDDIs (storport) 、 IrqlIoPassive5 (wdm) 、 PowerIrpDDis (wdm) |