SetNamedSecurityInfoA 函式 (aclapi.h)

發行項
02/23/2024

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

語法

DWORD SetNamedSecurityInfoA(
  [in]           LPSTR                pObjectName,
  [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] pObjectName

Null 終止字串的指標，指定要設定安全性資訊之對象的名稱。這可以是NTFS檔案系統、網路共用、登錄機碼、旗號、事件、mutex、檔案對應或可等候定時器上的本機或遠端檔案或目錄名稱。

如需不同物件類型的字串格式描述，請參閱 SE_OBJECT_TYPE。

[in] ObjectType

SE_OBJECT_TYPE列舉的值，指出 pObjectName 參數所命名的物件類型。

[in] SecurityInfo

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

[in, optional] psidOwner

識別物件擁有者之 SID 結構的指標。如果呼叫端沒有 SeRestorePrivilege 常數 (請參閱 Privilege Constants) ，此 SID 必須包含在呼叫者的令牌中，而且必須啟用 SE_GROUP_OWNER 許可權。 SecurityInfo 參數必須包含 OWNER_SECURITY_INFORMATION 旗標。若要設定擁有者，呼叫端必須具有物件的WRITE_OWNER存取權，或啟用SE_TAKE_OWNERSHIP_NAME許可權。如果您未設定擁有者 SID，此參數可以是 NULL。

[in, optional] psidGroup

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

[in, optional] pDacl

物件之新 DACL 的指標。 SecurityInfo 參數必須包含 DACL_SECURITY_INFORMATION 旗標。呼叫端必須具有物件WRITE_DAC存取權，或是對象的擁有者。如果您未設定 DACL，此參數可以是 NULL。

[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) 至現有的子物件。

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

NTFS 上的本機或遠端檔案或目錄
本機或遠端印表機
本機或遠端 Windows 服務
網路共用
登錄機碼
旗號、事件、mutex 和可等候的定時器
檔案對應物件
目錄服務物件

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

此函式會以純文本傳輸資訊。除非系統已關閉簽署，否則會簽署此函式傳輸的資訊，但不會執行加密。

當您更新 UNC 路徑所指示之資料夾的訪問許可權時，例如 \Test\TestFolder，會移除原始繼承的 ACE，且不包含完整磁碟區路徑。

範例

如需使用此函式的範例，請參閱修改物件的 ACL 或取得對象擁有權。

注意

aclapi.h 標頭會將 SetNamedSecurityInfo 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

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