ZwDuplicateObject 函式 (ntifs.h)

ZwDuplicateObject 例程會建立一個句柄，該句柄是指定之來源句柄的複本。

語法

NTSYSAPI NTSTATUS ZwDuplicateObject(
  [in]            HANDLE      SourceProcessHandle,
  [in]            HANDLE      SourceHandle,
  [in, optional]  HANDLE      TargetProcessHandle,
  [out, optional] PHANDLE     TargetHandle,
  [in]            ACCESS_MASK DesiredAccess,
  [in]            ULONG       HandleAttributes,
  [in]            ULONG       Options
);

參數

[in] SourceProcessHandle

要複製之句柄的來源進程句柄。

[in] SourceHandle

要複製的句柄。

[in, optional] TargetProcessHandle

要接收新句柄的目標進程句柄。 此參數是選擇性的，如果選項中設定了DUPLICATE_CLOSE_SOURCE旗標，則可以指定為 NULL。

[out, optional] TargetHandle

HANDLE 變數的指標，例程會將新的重複句柄寫入其中。 重複的句柄在指定的目標進程中有效。 此參數是選擇性的，如果未建立重複的句柄，則可以指定為 NULL。

[in] DesiredAccess

指定新句柄所需存取 權的ACCESS_MASK 值。

[in] HandleAttributes

指定新句柄所需屬性的 ULONG。 如需屬性的詳細資訊，請參閱 OBJECT_ATTRIBUTES 中的 Attributes 成員描述。

[in] Options

一組旗標，可控制重複作業的行為。 將此參數設定為零，或設定為下列一或多個旗標的位 OR。

旗標名稱	Description
DUPLICATE_SAME_ATTRIBUTES	不要使用 HandleAttributes 參數，請將來源句柄中的屬性複製到目標句柄。
DUPLICATE_SAME_ACCESS	請從來源句柄將訪問許可權複製到目標句柄，而不是使用 DesiredAccess 參數。
DUPLICATE_CLOSE_SOURCE	關閉來源句柄。

傳回值

如果呼叫成功，ZwDuplicateObject 會傳回STATUS_SUCCESS。 否則，它會傳回適當的錯誤狀態代碼。

備註

來源句柄會在指定的來源進程內容中進行評估。 呼叫進程必須具有來源進程的 PROCESS_DUP_HANDLE 存取權。 重複的句柄會在指定之目標進程的句柄數據表中建立。 呼叫進程 必須PROCESS_DUP_HANDLE目標 進程的存取權。

根據預設，重複的句柄會使用 HandleAttributes 參數所指定的屬性，以及 DesiredAccess 參數所指定的訪問許可權來建立。 如有必要，呼叫端可以藉由在Options參數中設定DUPLICATE_SAME_ATTRIBUTES和DUPLICATE_SAME_ACCESS旗標，來覆寫一或兩個預設值。

如果呼叫此函式發生在使用者模式中，您應該使用名稱 「NtDuplicateObject」，而不是 「ZwDuplicateObject」。。

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

規格需求

需求	值
最低支援的用戶端	Windows 2000。
目標平台	Universal
標頭	ntifs.h (包括 Ntdef.h、Ntifs.h、Fltkernel.h)
程式庫	Ntoskrnl.lib
IRQL	PASSIVE_LEVEL

另請參閱

ACCESS_MASK

OBJECT_ATTRIBUTES

使用原生系統服務例程的 Nt 和 Zw 版本