AdjustTokenGroups 関数 (securitybaseapi.h)

AdjustTokenGroups 関数は、指定されたアクセス トークンに既に存在するグループを有効または無効にします。 アクセス トークン内のグループを有効または無効にするには、TOKEN_ADJUST_GROUPSへのアクセスが必要です。

構文

BOOL AdjustTokenGroups(
  [in]            HANDLE        TokenHandle,
  [in]            BOOL          ResetToDefault,
  [in, optional]  PTOKEN_GROUPS NewState,
  [in]            DWORD         BufferLength,
  [out, optional] PTOKEN_GROUPS PreviousState,
  [out, optional] PDWORD        ReturnLength
);

パラメーター

[in] TokenHandle

有効または無効にするグループを含むアクセス トークンへのハンドル。 ハンドルには、トークンへのTOKEN_ADJUST_GROUPSアクセス権が必要です。 PreviousState パラメーターが NULL でない場合、ハンドルにはTOKEN_QUERYアクセス権も必要です。

[in] ResetToDefault

グループを既定の有効状態と無効状態に設定するかどうかを示すブール値。 この値が TRUE の場合、グループは既定の状態に設定され、 NewState パラメーターは無視されます。 この値が FALSE の場合、 グループは NewState パラメーターが指す情報に従って設定されます。

[in, optional] NewState

有効または無効にするグループを含む TOKEN_GROUPS 構造体へのポインター。 ResetToDefault パラメーターが FALSE の場合、関数は各グループを、TOKEN_GROUPS構造体内のそのグループのSE_GROUP_ENABLED属性の値に設定します。 ResetToDefault が TRUE の場合、このパラメーターは無視されます。

[in] BufferLength

PreviousState パラメーターが指すバッファーのサイズ (バイト単位)。 PreviousState パラメーターが NULL の場合、このパラメーターは 0 にすることができます。

[out, optional] PreviousState

関数が変更するグループの以前の状態を含む TOKEN_GROUPS 構造体を受け取るバッファーへのポインター。 つまり、この関数によってグループが変更された場合、そのグループとその前の状態は、PreviousState によって参照されるTOKEN_GROUPS構造体に含まれます。 TOKEN_GROUPS の GroupCount メンバーが 0 の場合、この関数によってグループは変更されていません。 このパラメーターは、NULL でもかまいません。

バッファーが指定されていても、変更されたグループの完全なリストを受け取るのに十分な領域が含まれていない場合、グループの状態は変更されず、関数は失敗します。 この場合、関数は ReturnLength パラメーターによって指される変数を、変更されたグループの完全な一覧を保持するために必要なバイト数に設定します。

[out, optional] ReturnLength

PreviousState パラメーターが指すバッファーに必要な実際のバイト数を受け取る変数へのポインター。 このパラメーターは NULL にすることができ、 PreviousState が NULL の場合は無視されます。

戻り値

関数が成功すると、戻り値は 0 以外になります。

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

解説

PreviousState パラメーターで取得された情報は、TOKEN_GROUPS構造体として書式設定されます。 つまり、バッファーへのポインターは、AdjustTokenGroups 関数の後続の呼び出しで NewState パラメーターとして渡され、グループの元の状態が復元されます。

NewState パラメーターは、アクセス トークンに存在しない変更するグループを一覧表示できます。 これは、トークン内のグループの正常な変更には影響しません。

AdjustTokenGroups 関数は、TOKEN_GROUPS構造体の SE_GROUP_MANDATORY 属性を持つグループを無効にできません。 代わりに CreateRestrictedToken を使用してください。

SE_GROUP_USE_FOR_DENY_ONLY属性を持つグループを有効にすることはできません。

要件

関連項目

アクセス制御の概要

AdjustTokenPrivileges

基本的なAccess Control関数

CreateRestrictedToken

GetTokenInformation

OpenProcessToken

OpenThreadToken

SetTokenInformation

TOKEN_GROUPS