setSecurityInfo 函式 (aclapi.h)

發行項
02/23/2024

SetSecurityInfo 函式會在指定物件的安全性描述元中設定指定的安全性資訊。呼叫端會依句柄識別物件。

若要設定物件的 SACL，呼叫端必須啟用 SE_SECURITY_NAME 許可權。

語法

DWORD SetSecurityInfo(
  [in]           HANDLE               handle,
  [in]           SE_OBJECT_TYPE       ObjectType,
  [in]           SECURITY_INFORMATION SecurityInfo,
  [in, optional] PSID                 psidOwner,
  [in, optional] PSID                 psidGroup,
  [in, optional] PACL                 pDacl,
  [in, optional] PACL                 pSacl
);

參數

[in] handle

要為其設定安全性信息的物件句柄。

[in] ObjectType

SE_OBJECT_TYPE列舉的成員，指出 handle 參數所識別的物件類型。

[in] SecurityInfo

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

[in, optional] psidOwner

識別物件擁有者之 SID 的指標。 SID 必須是可指派為安全性描述元擁有者 SID 的 SID。 SecurityInfo 參數必須包含 OWNER_SECURITY_INFORMATION 旗標。如果您未設定擁有者 SID，此參數可以是 NULL 。

[in, optional] psidGroup

識別物件主要群組之 SID 的指標。 SecurityInfo 參數必須包含 GROUP_SECURITY_INFORMATION 旗標。如果您未設定主要群組 SID，此參數可以是 NULL 。

[in, optional] pDacl

物件之新 DACL 的指標。除非 SecurityInfo 參數的值包含 DACL_SECURITY_INFORMATION 旗標，否則會忽略此參數。如果 SecurityInfo 參數的值包含 DACL_SECURITY_INFORMATION 旗標，且此參數的值設定為 NULL，則會將物件的完整存取權授與所有人。如需 Null DACL 的相關信息，請參閱建立 DACL。

[in, optional] pSacl

物件之新 SACL 的指標。 SecurityInfo 參數必須包含下列任何旗標：SACL_SECURITY_INFORMATION、LABEL_SECURITY_INFORMATION、ATTRIBUTE_SECURITY_INFORMATION、SCOPE_SECURITY_INFORMATION或BACKUP_SECURITY_INFORMATION。如果設定SACL_SECURITY_INFORMATION或SCOPE_SECURITY_INFORMATION，呼叫端必須啟用SE_SECURITY_NAME許可權。如果您未設定 SACL，此參數可以是 NULL 。

傳回值

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

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

備註

如果您要設定 DACL ( DACL) 或任何系統存取控制清單中的元素， (物件的 SACL) ，系統會根據 ACE 繼承規則，自動將任何可繼承的存取控制專案傳播 (ACE) 至現有的子物件。

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

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

SetSecurityInfo 函式不會根據慣用的順序重新排序允許或拒絕存取 ACE。將可繼承的 ACE 傳播至現有的子物件時， SetSecurityInfo 會將繼承的 ACE 依序放在子物件之 DACL 中的所有非繼承 ACE 之後。

注意如果無法使用物件子系的共用存取權，此函式將不會將未受保護的 ACE 傳播至子系。例如，如果以獨佔存取權開啟目錄，當目錄上的安全性變更時，操作系統將不會將未受保護的 ACE 傳播至該目錄的子目錄或檔案。

警告如果提供的句柄是以MAXIMUM_ALLOWED ACCESS_MASK值開啟，則 SetSecurityInfo 函式不會將 ACE 傳播至子系。

規格需求

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