InitializeAcl 関数 (securitybaseapi.h)

[アーティクル]
08/25/2023

InitializeAcl 関数は、新しい ACL 構造体を初期化します。

構文

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

パラメーター

[out] pAcl

この関数によって初期化される ACL 構造体へのポインター。この関数を呼び出す前に 、pAcl にメモリを割り当てます。

[in] nAclLength

pAcl パラメーターが指すバッファーの長さ (バイト単位)。この値は、ACL ヘッダーと、ACL に格納されるすべてのアクセス制御エントリ (ACE) を含むのに十分な大きさである必要があります。 さらに、この値は DWORD でアラインされている必要があります。 ACL のサイズの計算の詳細については、「解説」を参照してください。

[in] dwAclRevision

作成される ACL 構造体のリビジョンレベル。

この値は、ACL_REVISIONまたはACL_REVISION_DSできます。アクセス制御リスト (ACL) でオブジェクト固有の ACE がサポートされている場合は、ACL_REVISION_DSを使用します。

戻り値

関数が成功した場合、関数は 0 以外の値を返します。

関数が失敗すると、0 が返されます。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

InitializeAcl 関数は空の ACL 構造体を作成します。ACL に ACE が含まれない。空の ACL をオブジェクトに適用すると、そのオブジェクトへのすべてのアクセスが拒否されます。

ACL の初期サイズは、ACL を使用する前に ACL に追加する予定の ACE の数によって異なります。たとえば、 ACL にユーザーとグループの ACE を含める場合は、2 つの ACE に基づいて ACL を初期化します。既存の ACL の変更の詳細については、「オブジェクトの ACL の変更」を参照してください。

ACL の初期サイズを計算するには、次を一緒に追加し、結果を最も近い DWORD に揃えます。

ACL 構造体のサイズ。
ACL に含める各 ACE 構造体のサイズから ACE の SidStart メンバー (DWORD) を引いた値。
各 ACE に含める SID の長さ。

例

次の例では、 InitializeAcl 関数を呼び出します。 ACL のサイズは、3 つのアクセス許可 ACE に基づいています。オプションとして、セキュリティ記述子定義言語 (SDDL) を使用して ACL を作成できます。詳細については、「 DACL の作成」を参照してください。

この例では、簡略化のためのステップも省略しています。詳細については、「オブジェクト所有権の取得」の例を参照してください。 AllocateAndInitializeSid 関数を呼び出すために、コード例の最後に FreeSid 関数を呼び出す必要があります。

#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 を含む)
Library	Advapi32.lib
[DLL]	Advapi32.dll