GetGPOListW 函数（userenv.h）

项目
11/20/2024

GetGPOList 函数检索指定用户或计算机的 GPO 列表。可以通过两种方式调用此函数：首先，可以使用用户或计算机的令牌，或者，第二种方法是，可以使用用户或计算机的名称和域控制器的名称。

语法

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=用户，OU=用户，DC=contoso，DC=com”。

如果 hToken 参数未 NULL，则此参数必须 NULL。

[in] lpHostName

DNS 域名（首选）或域控制器名称。可以使用 DsGetDcName 函数检索域控制器名称，并在标志参数中指定 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。

返回值

如果函数成功，则返回值为非零。

如果函数失败，则返回值为零。若要获取扩展的错误信息，请调用 GetLastError。

言论

GetGPOList 函数旨在由代表用户或计算机操作的服务使用。服务调用此函数以获取 GPO 列表，然后检查每个 GPO 是否存在特定于服务的策略。

使用令牌调用此函数可提供最准确的列表。系统可以针对用户或计算机执行访问检查。使用用户或计算机名称调用此函数，域控制器名称比使用令牌调用此函数更快。但是，如果未指定令牌，则系统将使用调用方的安全访问，这意味着列表可能不适合预期用户或计算机。

若要在调用 GetGPOList时获取计算机的 GPO 最准确的列表，调用方必须具有对计算机域中每个 OU 和站点的读取访问权限，并读取并应用组策略访问链接到该域的站点、域或 OU 的所有 GPO。调用方的示例是在 lpName 参数中指定的计算机上运行的服务。获取 GPO 列表的替代方法是调用 RsopPlanningModeProvider WMI 类的 RsopCreateSession 方法。此方法可以在假设方案中为计算机或用户帐户生成生成的策略数据。

在处理完 GPO 列表后，调用 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
目标平台	窗户
标头	userenv.h
库	Userenv.lib
DLL	Userenv.dll