ホーム › Security.Authorization › SetEntriesInAclA

SetEntriesInAclA

関数

明示的アクセスエントリのリストから新しいACLを作成する(ANSI版)。

DLLADVAPI32.dll文字セットANSI (-A)呼出規約winapi対応OSWindows XP 以降

シグネチャ

// ADVAPI32.dll  (ANSI / -A)
#include <windows.h>

WIN32_ERROR SetEntriesInAclA(
    DWORD cCountOfExplicitEntries,
    EXPLICIT_ACCESS_A* pListOfExplicitEntries,   // optional
    ACL* OldAcl,   // optional
    ACL** NewAcl
);

パラメーター

名前	型	方向	説明
cCountOfExplicitEntries	DWORD	in	pListOfExplicitEntries 配列内の EXPLICIT_ACCESS 構造体の数。
pListOfExplicitEntries	EXPLICIT_ACCESS_A*	inoptional	既存の ACL にマージするアクセス制御情報を記述した EXPLICIT_ACCESS 構造体の配列へのポインター。
OldAcl	ACL*	inoptional	既存の ACL へのポインター。このパラメーターは NULL にすることができ、その場合、関数は EXPLICIT_ACCESS エントリに基づいて新しい ACL を作成します。
NewAcl	ACL**	out	新しい ACL へのポインターを受け取る変数へのポインター。関数が成功した場合は、 LocalFree 関数を呼び出して、返されたバッファーを解放する必要があります。

戻り値の型: WIN32_ERROR

公式ドキュメント

新しいアクセス制御情報または監査制御情報を既存の ACL 構造体にマージして、新しいアクセス制御リスト (ACL) を作成します。(ANSI)

戻り値

関数が成功した場合、ERROR_SUCCESS を返します。

関数が失敗した場合、WinError.h で定義されている 0 以外のエラーコードを返します。

解説(Remarks)

EXPLICIT_ACCESS 構造体の配列内の各エントリは、指定された trustee に対するアクセス制御情報または監査制御情報を指定します。trustee には、ユーザー、グループ、またはその他の security identifier (SID) 値 (logon identifier やログオンの種類 (たとえば Windows サービスやバッチジョブ) など) を指定できます。trustee を識別するには、名前または SID を使用できます。

SetEntriesInAcl 関数を使用すると、discretionary access control list (DACL) または system access control list (SACL) 内の access control entries (ACE) のリストを変更できます。SetEntriesInAcl は、同一の ACL 内でアクセス制御情報と監査制御情報を混在させることを妨げませんが、その場合、結果として得られる ACL には無意味なエントリが含まれることに注意してください。

DACL の場合、 EXPLICIT_ACCESS 構造体の grfAccessMode メンバーは、trustee に対するアクセス権を許可、拒否、または取り消すかどうかを指定します。このメンバーには、次のいずれかの値を指定できます。

これらの値については、ACCESS_MODE を参照してください。

SetEntriesInAcl 関数は、新しいアクセス拒否 ACE を、新しい ACL の ACE リストの先頭に配置します。また、新しいアクセス許可 ACE を、既存のアクセス許可 ACE の直前に配置します。

SACL の場合、 EXPLICIT_ACCESS 構造体の grfAccessMode メンバーには、次の値を指定できます。

SET_AUDIT_FAILURE と SET_AUDIT_SUCCESS は組み合わせることができます。これらの値については、ACCESS_MODE を参照してください。

SetEntriesInAcl 関数は、新しいシステム監査 ACE を、新しい ACL の ACE リストの先頭に配置します。

例

この関数を使用する例については、オブジェクトの ACL の変更、新しいオブジェクトのセキュリティ記述子の作成、またはオブジェクトの所有権の取得を参照してください。

メモ

aclapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして SetEntriesInAcl を定義します。エンコーディング中立のエイリアスの使用を、エンコーディング中立でないコードと混在させると、コンパイルエラーまたは実行時エラーを引き起こす不一致が生じる可能性があります。詳細については、関数プロトタイプの規則を参照してください。

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

各言語での呼び出し定義

// ADVAPI32.dll  (ANSI / -A)
#include <windows.h>

WIN32_ERROR SetEntriesInAclA(
    DWORD cCountOfExplicitEntries,
    EXPLICIT_ACCESS_A* pListOfExplicitEntries,   // optional
    ACL* OldAcl,   // optional
    ACL** NewAcl
);

[DllImport("ADVAPI32.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern uint SetEntriesInAclA(
    uint cCountOfExplicitEntries,   // DWORD
    IntPtr pListOfExplicitEntries,   // EXPLICIT_ACCESS_A* optional
    IntPtr OldAcl,   // ACL* optional
    IntPtr NewAcl   // ACL** out
);

<DllImport("ADVAPI32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function SetEntriesInAclA(
    cCountOfExplicitEntries As UInteger,   ' DWORD
    pListOfExplicitEntries As IntPtr,   ' EXPLICIT_ACCESS_A* optional
    OldAcl As IntPtr,   ' ACL* optional
    NewAcl As IntPtr   ' ACL** out
) As UInteger
End Function

' cCountOfExplicitEntries : DWORD
' pListOfExplicitEntries : EXPLICIT_ACCESS_A* optional
' OldAcl : ACL* optional
' NewAcl : ACL** out
Declare PtrSafe Function SetEntriesInAclA Lib "advapi32" ( _
    ByVal cCountOfExplicitEntries As Long, _
    ByVal pListOfExplicitEntries As LongPtr, _
    ByVal OldAcl As LongPtr, _
    ByVal NewAcl As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

SetEntriesInAclA = ctypes.windll.advapi32.SetEntriesInAclA
SetEntriesInAclA.restype = wintypes.DWORD
SetEntriesInAclA.argtypes = [
    wintypes.DWORD,  # cCountOfExplicitEntries : DWORD
    ctypes.c_void_p,  # pListOfExplicitEntries : EXPLICIT_ACCESS_A* optional
    ctypes.c_void_p,  # OldAcl : ACL* optional
    ctypes.c_void_p,  # NewAcl : ACL** out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
SetEntriesInAclA = Fiddle::Function.new(
  lib['SetEntriesInAclA'],
  [
    -Fiddle::TYPE_INT,  # cCountOfExplicitEntries : DWORD
    Fiddle::TYPE_VOIDP,  # pListOfExplicitEntries : EXPLICIT_ACCESS_A* optional
    Fiddle::TYPE_VOIDP,  # OldAcl : ACL* optional
    Fiddle::TYPE_VOIDP,  # NewAcl : ACL** out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn SetEntriesInAclA(
        cCountOfExplicitEntries: u32,  // DWORD
        pListOfExplicitEntries: *mut EXPLICIT_ACCESS_A,  // EXPLICIT_ACCESS_A* optional
        OldAcl: *mut ACL,  // ACL* optional
        NewAcl: *mut *mut ACL  // ACL** out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ADVAPI32.dll", CharSet = CharSet.Ansi)]
public static extern uint SetEntriesInAclA(uint cCountOfExplicitEntries, IntPtr pListOfExplicitEntries, IntPtr OldAcl, IntPtr NewAcl);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_SetEntriesInAclA' -Namespace Win32 -PassThru
# $api::SetEntriesInAclA(cCountOfExplicitEntries, pListOfExplicitEntries, OldAcl, NewAcl)

#uselib "ADVAPI32.dll"
#func global SetEntriesInAclA "SetEntriesInAclA" sptr, sptr, sptr, sptr
; SetEntriesInAclA cCountOfExplicitEntries, varptr(pListOfExplicitEntries), varptr(OldAcl), varptr(NewAcl)   ; 戻り値は stat
; cCountOfExplicitEntries : DWORD -> "sptr"
; pListOfExplicitEntries : EXPLICIT_ACCESS_A* optional -> "sptr"
; OldAcl : ACL* optional -> "sptr"
; NewAcl : ACL** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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