RtlCreateAcl 函式 (ntifs.h)

發行項
02/26/2024

RtlCreateAcl 例程會在 ACL) (建立和初始化訪問控制清單。

語法

NTSYSAPI NTSTATUS RtlCreateAcl(
  [out] PACL  Acl,
  [in]  ULONG AclLength,
        ULONG AclRevision
);

參數

[out] Acl

呼叫端配置的緩衝區指標，以接收初始化的 ACL 結構。此緩衝區 的大小必須至少 為 (ACL) ，

[in] AclLength

Acl 參數所指向緩衝區的長度，以位元組為單位。此值必須夠大，才能包含 ACL 標頭和所有存取控制專案， (ACE) 儲存在 ACL 中。如需計算 ACL 大小的相關信息，請參閱下列一節。

AclRevision

要新增之 ACE 的 ACL 修訂層級。 Windows 版本需求如下：

值	意義
ACL_REVISION	所有 Windows 版本的修訂層級都有效。
ACL_REVISION_DS	注意如果 Acl 中的 ACL 包含物件特定的 ACE，則必須ACL_REVISION_DS AceRevision。

傳回值

RtlCreateAcl 可以傳回下列其中一個狀態值：

傳回碼	Description
STATUS_SUCCESS	已成功建立並初始化 ACL。
STATUS_BUFFER_TOO_SMALL	新的 ACL 無法放入 Acl 的緩衝區中。需要較大的 ACL 緩衝區。
STATUS_INVALID_PARAMETER	指定的修訂不是最新的，或 AclLength 的值太大。

備註

由 RtlCreateAcl 初始化的 ACL 不包含 ACE) (存取控制專案。這個 ACL 是空的，而不是不存在的 ACL。如果空的 ACL 套用至物件，ACL 會隱含拒絕該物件的所有存取。若要將 ACL 新增 ACL，請使用 RtlAddAccessAllowedAce。

若要計算 ACL 的大小，請將 sizeof (ACL) 新增至要儲存在 ACL 中的所有 ACE 大小。若要計算 ACE 的大小，請將 ACE 結構的大小，例如 sizeof (ACCESS_ALLOWED_ACE) 新增至與 ACE 相關聯的 SID 長度，然後減去 SidStart 成員的大小， (ACE 結構和 SID) 的一部分。使用 RtlLengthSid 函式來取得指定 SID 的長度。

下列範例示範如何計算允許存取的 ACE 大小：

sizeof (ACCESS_ALLOWED_ACE) - sizeof (ACCESS_ALLOWED_ACE.SidStart) 
        + GetLengthSid (pAceSid);

若要計算 ACL 的大小，請使用下列演算法，以 sizeof (ACE) 表示式取代適當的 ACE 結構：

cbAcl = sizeof (ACL);
for (i = 0 ; i < nAceCount ; i++) {
    // subtract ACE.SidStart from the size
    cbAce = sizeof (ACE) - sizeof (DWORD);
    // add this ACE's SID length
    cbAce += GetLengthSid (pAceSid[i]);
    // add the length of each ACE to the total ACL length
    cbAcl += cbAce;
}

如需安全性和訪問控制的詳細資訊，請參閱適用於驅動程序開發人員的 Windows 安全性模型，以及 Windows SDK 中這些主題的相關文件。