AccessCheckByTypeResultList 関数 (securitybaseapi.h)
AccessCheckByTypeResultList 関数は、セキュリティ記述子が、アクセス トークンによって識別されるクライアントに対して、指定されたアクセス権のセットを付与するかどうかを決定します。 関数は、オブジェクト、そのプロパティ セット、プロパティなどのオブジェクトの階層に対するクライアントのアクセスをチェックできます。 この関数は、階層内の各オブジェクトの種類に対して付与または拒否されたアクセス権を報告します。 通常、サーバー アプリケーションはこの関数を使用して、プライベート オブジェクトへのアクセスをチェックします。
構文
BOOL AccessCheckByTypeResultList(
[in] PSECURITY_DESCRIPTOR pSecurityDescriptor,
[in, optional] PSID PrincipalSelfSid,
[in] HANDLE ClientToken,
[in] DWORD DesiredAccess,
[in, out, optional] POBJECT_TYPE_LIST ObjectTypeList,
[in] DWORD ObjectTypeListLength,
[out] PGENERIC_MAPPING GenericMapping,
[out, optional] PPRIVILEGE_SET PrivilegeSet,
[in, out] LPDWORD PrivilegeSetLength,
[out] LPDWORD GrantedAccessList,
[out] LPDWORD AccessStatusList
);
パラメーター
[in] pSecurityDescriptor
アクセスがチェックされる SECURITY_DESCRIPTOR 構造体へのポインター。
[in, optional] PrincipalSelfSid
セキュリティ識別子 (SID) へのポインター。 セキュリティ記述子がプリンシパル (ユーザー オブジェクトなど) を表すオブジェクトに関連付けられている場合、 PrincipalSelfSid パラメーターはオブジェクトの SID である必要があります。 アクセスを評価するときに、この SID は、既知のPRINCIPAL_SELF SID (S-1-5-10) を含む 任意のアクセス制御エントリ (ACE) の SID を論理的に置き換えます。 既知の SID の詳細については、「 既知の SID」を参照してください。
保護されたオブジェクトがプリンシパルを表していない場合は、このパラメーターを NULL に設定 します。
[in] ClientToken
アクセスを試みるクライアントを表す 偽装トークン へのハンドル。 ハンドルには、トークンへのTOKEN_QUERYアクセス権が必要です。それ以外の場合、関数は ERROR_ACCESS_DENIED で失敗します。
[in] DesiredAccess
チェックへのアクセス権を指定するアクセス マスク。 このマスクは、汎用アクセス権を含まない MapGenericMask 関数によってマップされている必要があります。
このパラメーターがMAXIMUM_ALLOWEDの場合、この関数は GrantedAccess 配列のアクセス マスクを設定して、オブジェクト型リスト内の各要素に対するクライアントの最大アクセス権を示します。
[in, out, optional] ObjectTypeList
アクセスをチェックするオブジェクト型の階層を識別するOBJECT_TYPE_LIST構造体の配列へのポインター。 配列内の各要素は、オブジェクトの種類を識別する GUID と、オブジェクト型の階層内のオブジェクト型のレベルを示す値を指定します。 配列には、同じ GUID を持つ 2 つの要素を含めてはいけません。
配列には少なくとも 1 つの要素が必要です。 配列の最初の要素はレベル 0 で、オブジェクト自体を識別する必要があります。 配列には、レベル 0 要素を 1 つだけ含めることができます。 2 番目の要素は、レベル 1 のプロパティ セットなどのサブオブジェクトです。 各レベル 1 エントリの後には、レベル 2 から 4 のサブオブジェクトの下位エントリがあります。 したがって、配列内の要素のレベルは{0、1、2、2、1、2、3}になります。 オブジェクトの種類の一覧の順序が正しくありません。 AccessCheckByTypeResultList は失敗し、 GetLastError は ERROR_INVALID_PARAMETERを返します。
[in] ObjectTypeListLength
ObjectTypeList 配列内の要素の数。 これは、 GrantedAccessList パラメーターと AccessStatusList パラメーターによって指される配列内の要素の数でもあります。
[out] GenericMapping
アクセスがチェックされているオブジェクトに関連付けられている GENERIC_MAPPING 構造体へのポインター。
[out, optional] PrivilegeSet
アクセス 検証の実行 に使用される 特権 を受け取るPRIVILEGE_SET構造体へのポインター。 特権が使用されなかった場合、この関数は PrivilegeCount メンバーを 0 に設定します。
[in, out] PrivilegeSetLength
PrivilegeSet パラメーターが指すバッファーのサイズ (バイト単位)。
[out] GrantedAccessList
アクセス マスクの配列へのポインター。 関数は、各アクセス マスクを設定して、オブジェクト型リスト内の対応する要素に付与されるアクセス権を示します。 関数が失敗した場合、アクセス マスクは設定されません。
[out] AccessStatusList
オブジェクト型リスト内の対応する要素の状態コードの配列へのポインター。 関数は、アクセスチェック中に特定のエラーを示すために、成功を示す要素を 0 に設定するか、0 以外の値を設定します。 関数が失敗した場合、配列内のどの要素も設定されません。
戻り値
関数が成功した場合、関数は 0 以外の値を返します。
関数が失敗すると、0 が返されます。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
詳細については、「 AccessCheck のしくみ の概要」を参照してください。
AccessCheckByTypeResultList 関数は、指定されたセキュリティ記述子と指定したアクセス トークンを比較し、AccessStatusList パラメーターで、オブジェクト型リスト内の各要素に対してアクセスが許可または拒否されるかどうかを示します。
ObjectTypeList 配列は、定義されたオブジェクト全体を必ずしも表すわけではありません。 代わりに、アクセスをチェックするオブジェクトのサブセットを表します。 たとえば、プロパティ セット内の 2 つのプロパティへのアクセスをチェックするには、レベル 0 のオブジェクト自体、レベル 1 のプロパティ セット、レベル 2 の 2 つのプロパティの 4 つの要素を含むオブジェクト型リストを指定します。
AccessCheckByTypeResultList 関数は、オブジェクト自体に適用される ACE と ObjectTypeList 配列にリストされているオブジェクト型のオブジェクト固有 ACE を評価します。 この関数は、 ObjectTypeList 配列にリストされていないオブジェクト型のオブジェクト固有の ACE を無視します。 したがって、 AccessStatusList パラメーターの要素 0 に対して返される結果は、オブジェクト全体ではなく、 ObjectTypeList パラメーターで定義されたオブジェクトのサブセットへのアクセスが許可されていることを示します。
ACE の階層がオブジェクトとそのサブオブジェクトへのアクセスを制御する方法の詳細については、「オブジェクトの プロパティへのアクセスを制御する ACE」を参照してください。
セキュリティ記述子の 随意アクセス制御リスト (DACL) が NULL の場合、この関数はオブジェクト型リスト内のすべての要素に要求されたアクセス権を付与します。
セキュリティ記述子に所有者 SID とグループ SID が含まれていない場合、 AccessCheckByTypeResultList はERROR_INVALID_SECURITY_DESCRで失敗します。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | securitybaseapi.h (Windows.h を含む) |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |
こちらもご覧ください
AccessCheckByTypeAndAuditAlarm