ZwGetNotificationResourceManager 函式 (wdm.h)

發行項
02/29/2024

ZwGetNotificationResourceManager 例程會從指定的資源管理員通知佇列擷取下一個交易通知。

語法

NTSYSCALLAPI NTSTATUS ZwGetNotificationResourceManager(
  [in]            HANDLE                    ResourceManagerHandle,
  [out]           PTRANSACTION_NOTIFICATION TransactionNotification,
  [in]            ULONG                     NotificationLength,
  [in]            PLARGE_INTEGER            Timeout,
  [out, optional] PULONG                    ReturnLength,
  [in]            ULONG                     Asynchronous,
  [in, optional]  ULONG_PTR                 AsynchronousContext
);

參數

[in] ResourceManagerHandle

由先前呼叫 ZwCreateResourceManager 或 ZwOpenResourceManager 取得的資源管理員物件的句柄。句柄必須具有物件的RESOURCEMANAGER_GET_NOTIFICATION存取權。

[out] TransactionNotification

呼叫端配置的緩衝區指標，可接收所擷取通知的相關信息。緩衝區必須夠大，才能包含 TRANSACTION_NOTIFICATION 結構加上其他通知特定自變數。

[in] NotificationLength

TransactionNotification 參數指向的緩衝區長度，以位元組為單位。

[in] Timeout

值的指標，指定以 100 奈秒為單位的相對或絕對時間。此指標是選擇性的，可以是 NULL。

如果指標為 NULL，則在交易通知可用之前， ZwGetNotificationResourceManager 不會傳回。如果指定時間值， 則 ZwGetNotificationResourceManager 會在通知可用時傳回，或是在指定的時間經過之後傳回，無論何時優先。

負值會指定相對於目前系統時間的時間。例如，5 秒的相對時間值會導致 ZwGetNotificationResourceManager 在呼叫後逾時五秒。

正值會指定絕對時間，這實際上相對於 00：00,1601 年 1 月 1 日。如果指定了絕對時間值，操作系統會將絕對時間值新增至代表 00：00、1601 年 1 月 1 日的時間值。

如果呼叫端指定零值 (而不是 NULL 指標) ， 則 ZwGetNotificationResourceManager 會立即傳回通知，無論通知是否可用。

[out, optional] ReturnLength

變數的選擇性指標。如果此指標不是 NULL，而且 NotificationLength 參數的值太小， 則 ZwGetNotificationResourceManager 會在變數中提供所需的長度，並傳回STATUS_BUFFER_TOO_SMALL。

[in] Asynchronous

必須是零的 ULONG 值。 ZwGetNotificationResourceManager 不支持異步通知。使用 TmEnableCallbacks 來啟用異步通知。

[in, optional] AsynchronousContext

ULONG 值的指標。此指標必須是 NULL。

傳回值

如果作業成功且有通知可用，ZwGetNotificationResourceManager 會傳回STATUS_SUCCESS。否則，此例程可能會傳回下列其中一個值：

傳回碼	Description
STATUS_TIMEOUT	Timeout 指定在通知可用之前經過的逾時間隔。
STATUS_OBJECT_TYPE_MISMATCH	指定的句柄不是 Resource Manager 物件的句柄。
STATUS_INVALID_HANDLE	物件句柄無效。
STATUS_ACCESS_DENIED	呼叫端沒有資源管理員對象的適當存取權。
STATUS_BUFFER_TOO_SMALL	NotificationLength 參數的值太小。

例程可能會傳回其他 NTSTATUS值。

備註

使用 ZwGetNotificationResourceManager 例程同步取得通知。使用 TmEnableCallbacks 例程來啟用異步通知。

收到的 TRANSACTION_NOTIFICATION 結構包含資源管理員在呼叫 ZwCreateEnlistment 時所指定的登記索引鍵。您可以使用登記金鑰來識別通知套用的登記。

如需 ZwGetNotificationResourceManager 例程的詳細資訊，請參閱建立 Resource Manager。

NtGetNotificationResourceManager 和 ZwGetNotificationResourceManager 是相同 Windows 原生系統服務例程的兩個版本。

對於核心模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本在處理和解譯輸入參數的方式可能會有不同的行為。如需例程 NtXxx 和 ZwXxx 版本之間的關聯性詳細資訊，請參閱使用 Nt 和 Zw 版本的原生系統服務例程。

規格需求

需求	值
最低支援的用戶端	適用於 Windows Vista 和更新版本的作業系統版本。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	= PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 PowerIrpDDis (wdm)