system_handle屬性

[system_handle] 屬性會指定系統定義的控制碼類型,代表系統物件的存取權。

[system_handle(system-handle-type[,optional-access-mask])]

參數

system-handle-type

指定其中一個系統控制碼類型選項。

有效的選項為:

optional-access-mask

選擇性地要求套用至重複控制碼的特定存取權限。 根據預設,未指定此動作時,控制碼將會以相同的存取權重複。

若要指定不同的存取層級,請使用對應至所選取基礎系統物件的物件特定存取權限。

如需如何在重複期間傳播存取權限的詳細資訊,請參閱 DuplicateHandle 檔。

您可以在 DuplicateHandle 參考以及每個參數頁面的 [另請參閱 ] sh_* 標題中找到每種物件之存取權限清單的連結。

備註

若要使用此屬性,在執行midl.exe時, -target 旗標必須設定為 NT100 (或更高版本) 。

系統控制碼是由作業系統所定義的控制碼,可提供系統資源的存取權。 宣告屬性時,必須指定控制碼後方物件的特定類型。

若為標示 [in] 的控制碼,控制碼將會複製到遠端程式,並在該程式的持續時間維持有效狀態。 從遠端程式傳回時,會釋放重複的控制碼。 若要維護基礎物件的存取權,遠端應用程式必須將控制碼複製到自己的位址空間。

相反地,針對標示 [out] 為 的控制碼,當遠端程式從呼叫傳回控制碼時,遠端程式將會失去其擁有權。 若要維護基礎物件的存取權,遠端程式應該複製控制碼並傳回重複專案。 傳回的控制碼接著會由呼叫端擁有,當不再需要存取基礎系統物件時,負責關閉該控制碼。

由於這是轉譯系統物件存取權的機制,因此此屬性只適用于相同電腦上程式之間的呼叫。

在建立系統控制碼後方,提供給基礎物件的建立和存取參數,將決定是否可以成功封送處理至遠端程式內容。

的陣列 system_handle 可以使用 size_is 屬性 檔中找到的語法傳入或傳出。

範例

下列範例會使用 數個 system_handle 。 如需完整的範例,請參閱 SystemHandlePassing 範例。

interface MyInterface : IUnknown                         
{         
    HRESULT Proc1([in, system_handle(sh_file)] HANDLE writeThisFile);

    HRESULT Proc2([in, system_handle(sh_pipe, FILE_GENERIC_READ)] HANDLE readThisPipe);

    HRESULT Proc3([out, system_handle(sh_composition)] HANDLE* visual);

    HRESULT Proc4([in] DWORD cEvents, [out, system_handle(sh_event), size_is(cEvents)] HANDLE* pWatchAllTheseEvents);
}

規格需求

   
最低支援的用戶端 Windows 10年度更新版 (1607,組建 14393)
最低支援的伺服器 Windows Server 2016 (組建 14393)

另請參閱

/target 參數

系結和控制碼

控制碼和物件

介面定義 (IDL) 檔案

DuplicateHandle

安全性描述項