GetSecurityInfo 函式 (aclapi.h)

發行項
02/23/2024

GetSecurityInfo 函式會擷取句柄所指定對象的安全性描述元複本。

語法

DWORD GetSecurityInfo(
  [in]            HANDLE               handle,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

參數

[in] handle

要從中擷取安全性信息的物件句柄。

[in] ObjectType

SE_OBJECT_TYPE 列舉值，指出對象的類型。

[in] SecurityInfo

一組位旗標，指出要擷取的安全性信息類型。此參數可以是 SECURITY_INFORMATION 位旗標的組合。

[out, optional] ppsidOwner

變數的指標，會接收 ppSecurityDescriptor 所傳回之安全性描述元中擁有者 SID 的指標。只有在您設定OWNER_SECURITY_INFORMATION旗標時，傳回的指標才有效。如果您不需要擁有者 SID，此參數可以是 NULL 。

[out, optional] ppsidGroup

在傳回的安全性描述元中，接收主要群組 SID 指標的變數指標。只有在您設定GROUP_SECURITY_INFORMATION旗標時，傳回的指標才有效。如果您不需要群組 SID，此參數可以是 NULL 。

[out, optional] ppDacl

在傳回的安全性描述元中，接收 DACL 指標的變數指標。只有在您設定DACL_SECURITY_INFORMATION旗標時，傳回的指標才有效。如果您不需要 DACL，此參數可以是 NULL 。

[out, optional] ppSacl

在傳回的安全性描述元中接收 SACL 指標的變數指標。只有在您設定SACL_SECURITY_INFORMATION旗標時，傳回的指標才有效。如果您不需要 SACL，此參數可以是 NULL 。

[out, optional] ppSecurityDescriptor

接收物件之安全性描述元指標之變數的指標。當您完成使用指標時，請呼叫 LocalFree 函式以釋放傳回的緩衝區。

如果其中一個 ppsidOwner、 ppsidGroup、 ppDacl 或 ppSacl 參數不是 NULL，則需要此參數。

傳回值

如果函式成功，傳回值會ERROR_SUCCESS。

如果函式失敗，傳回值是 WinError.h 中定義的非零錯誤碼。

備註

如果 ppsidOwner、 ppsidGroup、 ppDacl 和 ppSacl 參數不是 NULL， 且 SecurityInfo 參數會指定從物件擷取這些參數，這些參數將會指向 ppSecurityDescriptor 所傳回之安全性描述元中的對應參數。

若要從物件的安全性描述元讀取擁有者、群組或 DACL，呼叫程式必須在開啟句柄時授與READ_CONTROL存取權。若要取得READ_CONTROL存取權，呼叫端必須是對象的擁有者，或者物件的 DACL 必須授與存取權。

若要從安全性描述元讀取 SACL，呼叫進程必須在開啟句柄時授與ACCESS_SYSTEM_SECURITY存取權。取得此存取權的適當方式是在呼叫端的目前令牌中啟用SE_SECURITY_NAME許可權、開啟ACCESS_SYSTEM_SECURITY存取的句柄，然後停用許可權。如需啟用許可權之安全性含意的資訊，請參閱以特殊許可權執行。

您可以使用 GetSecurityInfo 函式搭配下列類型的物件：

NTFS 檔案系統上的本機或遠端檔案或目錄
具名管道
本機或遠端印表機
本機或遠端 Windows 服務
網路共用
登錄機碼
旗號、事件、mutex 和可等候的定時器
進程、線程、作業和檔案對應物件
互動式服務視窗月臺和桌面
目錄服務物件

此函式不會處理競爭條件。如果您的線程在大約另一個線程變更物件的安全性描述元時呼叫此函式，則此函式可能會失敗。

範例

如需使用此函式的範例，請參閱尋找 File 對象的擁有者。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	aclapi.h
程式庫	Advapi32.lib
Dll	Advapi32.dll