AddAce 函式 (securitybaseapi.h)

發行項
03/05/2024

AddAce 函式會將一或多個存取控制專案 (ACL) 新增至指定的訪問控制清單 (ACL) 。

語法

BOOL AddAce(
  [in, out] PACL   pAcl,
  [in]      DWORD  dwAceRevision,
  [in]      DWORD  dwStartingAceIndex,
  [in]      LPVOID pAceList,
  [in]      DWORD  nAceListLength
);

參數

[in, out] pAcl

ACL 的指標。此函式會將 ACE 新增至此 ACL。

[in] dwAceRevision

指定要修改之 ACL 的修訂層級。

此值可以是ACL_REVISION或ACL_REVISION_DS。如果 ACL 包含特定物件 ACE，請使用ACL_REVISION_DS。此值必須與 pAceList 中所有 ACE 的 AceType 字段相容。否則，函式將會失敗，並將最後一個錯誤設定為 ERROR_INVALID_PARAMETER。

[in] dwStartingAceIndex

指定 ACL 清單中要新增 ACE 的位置。值為零會在清單開頭插入 ACE。 MAXDWORD 的值會將 ACE 附加至清單結尾。

[in] pAceList

要新增至指定 ACL 之一或多個 ACE 列表的指標。清單中的 ACE 必須連續儲存。

[in] nAceListLength

指定 pAceList 參數所指向之輸入緩衝區的大小，以位元組為單位。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。以下是可能的錯誤值。

傳回碼	Description
ERROR_INSUFFICIENT_BUFFER	新的 ACE 不適用於 ACL。需要較大的 ACL 緩衝區。
ERROR_INVALID_PARAMETER	指定的 ACL 格式不正確。
ERROR_SUCCESS	已成功新增 ACE。

備註

使用 AddAce 函式操作 ACL 時，應用程式經常使用 FindFirstFreeAce 和 GetAce 函式。此外，GetAclInformation 函式所擷取的ACL_SIZE_INFORMATION結構包含 ACL 的大小及其包含的 ACE 數目。

範例

如需使用此函式的範例，請參閱啟動互動式用戶端程式。

規格需求

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