AdjustTokenPrivileges 関数 (securitybaseapi.h)

AdjustTokenPrivileges 関数は、指定されたアクセス トークンの特権を有効または無効にします。 アクセス トークンで特権を有効または無効にするには、TOKEN_ADJUST_PRIVILEGESアクセスが必要です。

構文

BOOL AdjustTokenPrivileges(
  [in]            HANDLE            TokenHandle,
  [in]            BOOL              DisableAllPrivileges,
  [in, optional]  PTOKEN_PRIVILEGES NewState,
  [in]            DWORD             BufferLength,
  [out, optional] PTOKEN_PRIVILEGES PreviousState,
  [out, optional] PDWORD            ReturnLength
);

パラメーター

[in] TokenHandle

変更する特権を含むアクセス トークンへのハンドル。 ハンドルには、トークンへのTOKEN_ADJUST_PRIVILEGESアクセス権が必要です。 PreviousState パラメーターが NULL でない場合、ハンドルにはTOKEN_QUERYアクセス権も必要です。

[in] DisableAllPrivileges

関数がトークンのすべての特権を無効にするかどうかを指定します。 この値が TRUE の場合、関数はすべての特権を無効にし、 NewState パラメーターを無視します。 FALSE の場合、関数は NewState パラメーターが指す情報に基づいて特権を変更します。

[in, optional] NewState

特権とその属性の配列を指定する TOKEN_PRIVILEGES 構造体へのポインター。 DisableAllPrivileges パラメーターが FALSE の場合、AdjustTokenPrivileges 関数はトークンに対するこれらの特権を有効、無効、または削除します。 次の表では、 AdjustTokenPrivileges 関数によって実行されるアクションについて、特権属性に基づいて説明します。

DisableAllPrivileges が TRUE の場合、関数はこのパラメーターを無視します。

[in] BufferLength

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

[out, optional] PreviousState

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

変更された特権の完全な一覧を受け取るために小さすぎるバッファーを指定すると、関数は失敗し、特権は調整されません。 この場合、関数は ReturnLength パラメーターが指す変数を、変更された特権の完全な一覧を保持するために必要なバイト数に設定します。

[out, optional] ReturnLength

PreviousState パラメーターが指すバッファーの必要なサイズ (バイト単位) を受け取る変数へのポインター。 PreviousState が NULL の場合、このパラメーターは NULL にすることができます。

戻り値

関数が成功すると、戻り値は 0 以外になります。 関数が指定されたすべての特権を調整したかどうかを判断するには、 GetLastError を呼び出します。この呼び出しは、関数が成功したときに次のいずれかの値を返します。

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

解説

AdjustTokenPrivileges 関数は、アクセス トークンに新しい特権を追加できません。 トークンの既存の特権のみを有効または無効にすることができます。 トークンの特権を確認するには、 GetTokenInformation 関数を呼び出します。

NewState パラメーターは、関数を失敗させることなく、トークンに含まれない特権を指定できます。 この場合、関数はトークンが持つ特権を調整し、関数が成功するように他の特権を無視します。 GetLastError 関数を呼び出して、関数が指定されたすべての特権を調整したかどうかを判断します。 PreviousState パラメーターは、調整された特権を示します。

PreviousState パラメーターは、調整された特権の元の状態を含むTOKEN_PRIVILEGES構造体を取得します。 元の状態を復元するには、以降の AdjustTokenPrivileges 関数の呼び出しで PreviousState ポインターを NewState パラメーターとして渡します。

例

この関数を使用する例については、「 特権の有効化と無効化」を参照してください。

要件

こちらもご覧ください

アクセス制御の概要

AdjustTokenGroups

基本的なAccess Control関数

GetTokenInformation

OpenProcessToken

OpenThreadToken

SetTokenInformation

TOKEN_PRIVILEGES