SetNamedSecurityInfoW 函式（aclapi.h）

發行項
11/20/2024

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

語法

DWORD SetNamedSecurityInfoW(
  [in]           LPWSTR               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）或任何系統訪問控制清單（SACL）中任何元素設定為對象，系統會根據繼承規則，自動將任何可繼承訪問控制專案（ACE）傳播至現有的子物件。

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

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

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

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

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

例子

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

注意

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

要求

要求	價值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
標頭	aclapi.h
連結庫	Advapi32.lib
DLL	Advapi32.dll