getGPOListW 函数 (userenv.h)

  • 项目

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=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。

返回值

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

如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 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

另请参阅

DsGetDcName

FreeGPOList

GROUP_POLICY_OBJECT

组策略函数

组策略概述