InitializeAcl

関数

新しい空のACL構造体を初期化する。

DLLADVAPI32.dll呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// ADVAPI32.dll
#include <windows.h>

BOOL InitializeAcl(
    ACL* pAcl,
    DWORD nAclLength,
    ACE_REVISION dwAclRevision
);

パラメーター

名前	型	方向	説明
pAcl	ACL*	out	この関数によって初期化される ACL 構造体へのポインターです。この関数を呼び出す前に、pAcl 用のメモリを割り当ててください。
nAclLength	DWORD	in	pAcl パラメーターが指すバッファーの長さ (バイト単位) です。この値は、ACL ヘッダーと、ACL に格納されるすべてのアクセス制御エントリ (ACE) を収めるのに十分な大きさである必要があります。さらに、この値は DWORD 境界に整列されている必要があります。ACL のサイズの計算方法の詳細については、「解説」を参照してください。
dwAclRevision	ACE_REVISION	in	作成する ACL 構造体のリビジョンレベルです。この値には ACL_REVISION または ACL_REVISION_DS を指定できます。アクセス制御リスト (ACL) がオブジェクト固有の ACE をサポートする場合は、ACL_REVISION_DS を使用してください。

名前

型

方向

説明

pAcl

ACL*

out

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

nAclLength

DWORD

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

dwAclRevision

ACE_REVISION

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

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

戻り値の型: BOOL

公式ドキュメント

新しい ACL 構造体を初期化します。

戻り値

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

関数が失敗した場合は、0 を返します。拡張エラー情報を取得するには、 GetLastError を呼び出してください。

解説(Remarks)

InitializeAcl 関数は、空の ACL 構造体を作成します。この ACL には ACE は含まれません。空の 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.
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// ADVAPI32.dll
#include <windows.h>

BOOL InitializeAcl(
    ACL* pAcl,
    DWORD nAclLength,
    ACE_REVISION dwAclRevision
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool InitializeAcl(
    IntPtr pAcl,   // ACL* out
    uint nAclLength,   // DWORD
    uint dwAclRevision   // ACE_REVISION
);

<DllImport("ADVAPI32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function InitializeAcl(
    pAcl As IntPtr,   ' ACL* out
    nAclLength As UInteger,   ' DWORD
    dwAclRevision As UInteger   ' ACE_REVISION
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' pAcl : ACL* out
' nAclLength : DWORD
' dwAclRevision : ACE_REVISION
Declare PtrSafe Function InitializeAcl Lib "advapi32" ( _
    ByVal pAcl As LongPtr, _
    ByVal nAclLength As Long, _
    ByVal dwAclRevision As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

InitializeAcl = ctypes.windll.advapi32.InitializeAcl
InitializeAcl.restype = wintypes.BOOL
InitializeAcl.argtypes = [
    ctypes.c_void_p,  # pAcl : ACL* out
    wintypes.DWORD,  # nAclLength : DWORD
    wintypes.DWORD,  # dwAclRevision : ACE_REVISION
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
InitializeAcl = Fiddle::Function.new(
  lib['InitializeAcl'],
  [
    Fiddle::TYPE_VOIDP,  # pAcl : ACL* out
    -Fiddle::TYPE_INT,  # nAclLength : DWORD
    -Fiddle::TYPE_INT,  # dwAclRevision : ACE_REVISION
  ],
  Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn InitializeAcl(
        pAcl: *mut ACL,  // ACL* out
        nAclLength: u32,  // DWORD
        dwAclRevision: u32  // ACE_REVISION
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", SetLastError = true)]
public static extern bool InitializeAcl(IntPtr pAcl, uint nAclLength, uint dwAclRevision);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_InitializeAcl' -Namespace Win32 -PassThru
# $api::InitializeAcl(pAcl, nAclLength, dwAclRevision)

#uselib "ADVAPI32.dll"
#func global InitializeAcl "InitializeAcl" sptr, sptr, sptr
; InitializeAcl varptr(pAcl), nAclLength, dwAclRevision   ; 戻り値は stat
; pAcl : ACL* out -> "sptr"
; nAclLength : DWORD -> "sptr"
; dwAclRevision : ACE_REVISION -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global InitializeAcl "InitializeAcl" var, int, int
; res = InitializeAcl(pAcl, nAclLength, dwAclRevision)
; pAcl : ACL* out -> "var"
; nAclLength : DWORD -> "int"
; dwAclRevision : ACE_REVISION -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global InitializeAcl "InitializeAcl" sptr, int, int
; res = InitializeAcl(varptr(pAcl), nAclLength, dwAclRevision)
; pAcl : ACL* out -> "sptr"
; nAclLength : DWORD -> "int"
; dwAclRevision : ACE_REVISION -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。