InitializeAcl 函式 (securitybaseapi.h)

發行項
03/13/2024

InitializeAcl 函式會初始化新的 ACL 結構。

語法

BOOL InitializeAcl(
  [out] PACL  pAcl,
  [in]  DWORD nAclLength,
  [in]  DWORD dwAclRevision
);

參數

[out] pAcl

要由這個函式初始化之 ACL 結構的指標。呼叫此函式之前，請先配置 pAcl 的記憶體。

[in] nAclLength

pAcl 參數所指向之緩衝區的長度，以位元組為單位。此值必須夠大，才能包含 ACL 標頭和所有存取控制專案， (ACL) 儲存在 ACL 中。此外，此值必須對齊 DWORD。如需計算 ACL 大小的詳細資訊，請參閱。

[in] dwAclRevision

正在建立之 ACL 結構的修訂層級。

此值可以是ACL_REVISION或ACL_REVISION_DS。如果訪問控制清單 (ACL) 支援物件特定的 ACE，請使用ACL_REVISION_DS。

傳回值

如果函式成功，函式會傳回非零。

如果函式失敗，則會傳回零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

InitializeAcl 函式會建立空的 ACL 結構;ACL 不包含 ACE。將空 的 ACL 套用至物件會拒絕該物件的所有存取。

ACL 的初始大小取決於您打算在使用 ACL 之前新增至 ACL 的 ACL 數目。例如，如果 ACL 是要包含使用者和群組的 ACE，您會根據兩個 ACE 初始化 ACL 。如需修改現有 ACL 的詳細資訊，請參閱修改物件的 ACL。

若要計算 ACL 的初始大小，請將下列內容加在一起，然後將結果對齊最接近 的 DWORD：

ACL 結構的大小。
ACL 要包含之每個 ACE 結構的大小減去 ACE (DWORD) SidStart 成員。
每個 ACE 要包含的 SID 長度。

範例

下列範例會呼叫 InitializeAcl 函式。 ACL 的大小是以三個允許存取 ACE 為基礎。您可以選擇使用安全性描述元定義語言 (SDDL) 來建立 ACL。如需詳細資訊，請參閱建立 DACL。

此範例也會省略簡化的步驟。如需詳細資訊，請參閱取得對象擁有權範例。您必須在範例程式代碼結尾呼叫 FreeSid 函式，因為呼叫 AllocateAndInitializeSid 函式。

#include <windows.h>
#include <Winbase.h>
#pragma comment(lib, "duser.lib")

#define NUM_OF_ACES 3

void main()
{
    PACL pAcl = NULL;
    DWORD cbAcl = 0;
    PSID psids[NUM_OF_ACES];

    // Allocate and initialize SIDs.
    // Step omitted - See Taking Object Ownership example.

    // Add the SID for each ACE to psids. 
    cbAcl = sizeof(ACL) + 
        ((sizeof(ACCESS_ALLOWED_ACE)) * NUM_OF_ACES);
    for (int i = 0; i < NUM_OF_ACES; i++)
    {
        cbAcl += GetLengthSid(psids[i]) - sizeof(DWORD);
    }

    // Align cbAcl to a DWORD.
    cbAcl = (cbAcl + (sizeof(DWORD) - 1)) & 0xfffffffc;

    pAcl = (ACL*)LocalAlloc(LPTR, cbAcl);
    if (pAcl)
    {
        if (InitializeAcl(pAcl, cbAcl, ACL_REVISION))
        {

            // Add the ACEs to the ACL.
            // Add the ACL to the object's security descriptor.
        }
        else
        {

            // Handle error.
        }
    }
    {

        // Handle error.
    }

    // Free pAcl when finished.
    // Call FreeSid when finished.
}

規格需求

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