IoAttachDeviceToDeviceStackSafe 函式 (ntddk.h)

  • 發行項

IoAttachDeviceToDeviceStackSafe 例程會將呼叫端的裝置物件附加至驅動程式堆疊中最上層的裝置物件。

語法

NTSTATUS IoAttachDeviceToDeviceStackSafe(
  [in]  PDEVICE_OBJECT SourceDevice,
  [in]  PDEVICE_OBJECT TargetDevice,
  [out] PDEVICE_OBJECT *AttachedToDeviceObject
);

參數

[in] SourceDevice

呼叫端所建立裝置物件的指標。

[in] TargetDevice

要附加SourceDevice物件之堆疊中裝置物件的指標。

[out] AttachedToDeviceObject

在輸入時，此參數會指定SourceDevice-DeviceExtension-AttachedToDeviceObject>>的位址，此位址必須包含NULL指標。 在輸出時，此參數會接收 SourceDevice 所附加裝置物件的指標。

傳回值

IoAttachDeviceToDeviceStackSafe 如果 SourceDevice 成功附加在 TargetDevice 上方，就會傳回STATUS_SUCCESS;否則會傳回STATUS_NO_SUCH_DEVICE。

備註

如同 IoAttachDeviceToDeviceStack，IoAttachDeviceToDeviceStackSafe 會在驅動程式之間建立分層，讓相同的 IRP 傳送至堆疊中的每個驅動程式。 不過，不同於 IoAttachDeviceToDeviceStack，IoAttachDeviceToDeviceStackSafe 有額外的參數 AttachedToDeviceObject，篩選驅動程式會用來傳遞 SourceDevice 物件的 AttachedToDeviceObject 字段的位址。 IoAttachDeviceToDeviceStackSafe 會在保存 I/O 系統資料庫鎖定時更新此字段。 由於它保留此鎖定， 所以 IoAttachDeviceToDeviceStackSafe 會避免競爭條件，如果 SourceDevice 物件在已更新其 AttachedToDeviceObject 字段之前收到 IRP，就會發生此競爭狀況。

文件系統篩選驅動程式會呼叫 IoAttachDeviceToDeviceStackSafe ，將自己的篩選裝置物件附加 (SourceDevice) 裝置物件上方， (TargetDevice) 屬於文件系統或其他篩選驅動程式。 篩選驅動程式會先收到傳送至 AttachedToDeviceObject 的後續 I/O 要求，其會先處理這些要求，並透過呼叫 IoCallDriver 將其轉送至堆疊中的下一個驅動程式。

如果 TargetDevice 指定的裝置物件目前位於驅動程式堆疊頂端， SourceDevice 會直接連結至 TargetDevice。 在此情況下， TargetDevice 和傳回的 AttachedToDeviceObject 指標相等。

如果驅動程式堆疊中的 TargetDevice 上方已經附加一或多個篩選裝置物件， IoAttachDeviceToDeviceStackSafe 會將 SourceDevice 附加至最上層篩選裝置物件。 後者的指標會在 AttachedToDeviceObject 中傳回。

在緊接至堆疊頂端之後， SourceDevice 會佔用驅動程式堆疊的頂端。 不過請注意，這不一定表示 SourceDevice 會保留在驅動程式堆疊的頂端。 其他篩選條件可以在堆疊中的 SourceDevice 上方附加自己的篩選裝置物件。

IoAttachDeviceToDeviceStackSafe 會將 SourceDevice 指向之裝置物件的 AlignmentRequirement 成員設定為下一個較低裝置對象中對應的 值，並將 SourceDevice 中的 StackSize 設定為下一個較低物件加上一個值。

規格需求

需求 值
最低支援的用戶端 此例程適用於 Windows 2000 Service Pack 4 (SP4) 和 Windows XP 和更新版本的更新匯總。
目標平台 Universal
標頭 ntddk.h (包含 Ntddk.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL <= DISPATCH_LEVEL
DDI 合規性規則 HwStorPortProhibitedDIS (storport)

另請參閱

IoAttachDeviceToDeviceStack

IoCallDriver