GetGPOListW 関数 (userenv.h)

[アーティクル]
03/03/2024

GetGPOList 関数は、指定したユーザーまたはコンピューターの GPO の一覧を取得します。この関数は、2 つの方法で呼び出すことができます。最初に、ユーザーまたはコンピューターのトークンを使用するか、2 つ目に、ユーザーまたはコンピューターの名前とドメインコントローラーの名前を使用できます。

構文

USERENVAPI BOOL GetGPOListW(
  [in]  HANDLE                hToken,
  [in]  LPCWSTR               lpName,
  [in]  LPCWSTR               lpHostName,
  [in]  LPCWSTR               lpComputerName,
  [in]  DWORD                 dwFlags,
  [out] PGROUP_POLICY_OBJECTW *pGPOList
);

パラメーター

[in] hToken

LogonUser、CreateRestrictedToken、DuplicateToken、OpenProcessToken、または OpenThreadToken 関数から返される、ユーザーまたはコンピューターのトークン。このトークンには 、TOKEN_IMPERSONATE と TOKEN_QUERY アクセス権が必要です。詳細については、「 Access-Token オブジェクトのアクセス権」および次の「解説」セクションを参照してください。

このパラメーターが NULL の場合は、lpName パラメーターと lpHostName パラメーターの値を指定する必要があります。

[in] lpName

完全修飾識別名形式のユーザー名またはコンピューター名へのポインター (例: "CN=user, OU=users, DC=contoso, DC=com")。

hToken パラメーターが NULL でない場合、このパラメーターは NULL である必要があります。

[in] lpHostName

DNS ドメイン名 (推奨) またはドメインコントローラー名。ドメインコントローラー名は、dsGetDcName 関数を使用して取得し、flags パラメーターにDS_DIRECTORY_SERVICE_REQUIREDを指定します。

hToken パラメーターが NULL でない場合、このパラメーターは NULL である必要があります。

[in] lpComputerName

サイトの場所を決定するために使用されるコンピューターの名前へのポインター。名前の形式は "\\computer_name" です。このパラメーターが NULL の場合は、ローカルコンピューター名が使用されます。

[in] dwFlags

情報の取得を制御するために使用される追加のフラグを指定する値。 GPO_LIST_FLAG_MACHINEを指定すると、関数はコンピューターのポリシー情報を取得します。 GPO_LIST_FLAG_MACHINEを指定しない場合、関数はユーザーのポリシー情報を取得します。

GPO_LIST_FLAG_SITEONLYを指定した場合、関数はコンピューターまたはユーザーのサイト情報のみを返します。

[out] pGPOList

GPO 構造の一覧を受け取るポインター。詳細については、「 GROUP_POLICY_OBJECT」を参照してください。

戻り値

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

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

解説

GetGPOList 関数は、ユーザーまたはコンピューターに代わって動作するサービスで使用することを目的としています。サービスはこの関数を呼び出して GPO の一覧を取得し、各 GPO でサービス固有のポリシーを確認します。

トークンを使用してこの関数を呼び出すと、最も正確なリストが提供されます。システムは、ユーザーまたはコンピューターのアクセスチェックを実行できます。この関数をユーザー名またはコンピューター名とドメインコントローラー名で呼び出す方が、トークンを使用して呼び出すよりも高速です。ただし、トークンが指定されていない場合、システムは呼び出し元のセキュリティアクセスを使用します。つまり、一覧が目的のユーザーまたはコンピューターに対して完全に正しくない可能性があります。

GetGPOList を呼び出すときにコンピューターの GPO の最も正確な一覧を取得するには、呼び出し元がコンピュータードメイン内の各 OU とサイトに対する読み取りアクセス権を持ち、そのドメインのサイト、ドメイン、または OU にリンクされているすべての GPO にグループポリシーアクセス権を読み取って適用する必要があります。呼び出し元の例としては、 lpName パラメーターに名前が指定されているコンピューターで実行されているサービスがあります。 GPO の一覧を取得する別の方法は、RsopPlanningModeProvider WMI クラスの RsopCreateSession メソッドを呼び出す方法です。メソッドは、仮定のシナリオで、コンピューターまたはユーザーアカウントの結果のポリシーデータを生成できます。

FreeGPOList 関数を呼び出して、GPO リストの処理が完了したら解放します。

一般に、次のコード例に示すように、ユーザーの GPO の一覧を取得するときは、トークンを使用して GetGPOList を呼び出す必要があります。

LPGROUP_POLICY_OBJECT  pGPOList;
      if (GetGPOList (hToken, NULL, NULL, NULL, 0, &pGPOList))
      {
//        Perform processing here. 
//
//        Free the GPO list when you finish processing.
          FreeGPOList (pGPOList);
      }

通常、コンピューターの GPO の一覧を取得するには、次のコードスニペットに示すように、コンピューター名とドメインコントローラー名を使用して GetGPOList を呼び出すことができます。

LPGROUP_POLICY_OBJECT  pGPOList;
      if (GetGPOList (NULL, lpMachineName, lpHostName, lpMachineName, GPO_LIST_FLAG_MACHINE, &pGPOList))
      {
//        Perform processing here. 
//
//        Free the GPO list when you finish processing.
          FreeGPOList (pGPOList);
      }

特定のユーザーまたはコンピューターと拡張機能に適用されている GPO の一覧を取得するには、 GetAppliedGPOList 関数を呼び出します。

注意

userenv.h ヘッダーは、GetGPOList をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows Vista
サポートされている最小のサーバー	Windows Server 2008
対象プラットフォーム	Windows
ヘッダー	userenv.h
Library	Userenv.lib
[DLL]	Userenv.dll