PFNPROCESSGROUPPOLICYEX 回调函数 (userenv.h)

项目
03/03/2024

ProcessGroupPolicyEx 函数是应用策略时使用的应用程序定义的回调函数。此扩展函数还支持记录策略的结果集 (RSoP) 数据。 PFNPROCESSGROUPPOLICYEX 类型定义指向此回调函数的指针。 ProcessGroupPolicyEx 是应用程序定义的函数名称的占位符。

语法

PFNPROCESSGROUPPOLICYEX Pfnprocessgrouppolicyex;

DWORD Pfnprocessgrouppolicyex(
  [in]  DWORD dwFlags,
  [in]  HANDLE hToken,
  [in]  HKEY hKeyRoot,
  [in]  PGROUP_POLICY_OBJECT pDeletedGPOList,
  [in]  PGROUP_POLICY_OBJECT pChangedGPOList,
  [in]  ASYNCCOMPLETIONHANDLE pHandle,
  [in]  BOOL *pbAbort,
  [in]  PFNSTATUSMESSAGECALLBACK pStatusCallback,
  [in]  IWbemServices *pWbemServices,
  [out] HRESULT *pRsopStatus
)
{...}

参数

[in] dwFlags

此参数可以是以下一个或多个标志。

GPO_INFO_FLAG_MACHINE

应用计算机策略而不是用户策略。

GPO_INFO_FLAG_BACKGROUND

执行策略的后台刷新。有关详细信息，请参阅此列表后面的文本。

GPO_INFO_FLAG_ASYNC_FOREGROUND

执行策略的异步前台刷新。有关详细信息，请参阅此列表后面的文本。有关前台策略应用程序的详细信息，请参阅组策略的初始处理。

GPO_INFO_FLAG_SLOWLINK

正在跨慢速链接应用策略。

GPO_INFO_FLAG_VERBOSE

将详细输出写入事件日志。

GPO_INFO_FLAG_NOCHANGES

未检测到对 GPO 的更改。

GPO_INFO_FLAG_LINKTRANSITION

在策略应用程序之间检测到链接速度的变化。

GPO_INFO_FLAG_LOGRSOP_TRANSITION

在上一个策略的应用和当前策略的应用之间检测到 RSoP 日志记录发生了更改。

GPO_INFO_FLAG_FORCED_REFRESH

正在应用强制策略刷新。

GPO_INFO_FLAG_SAFEMODE_BOOT

安全模式标志。

可以设置 GPO_INFO_FLAG_BACKGROUND 标志和 GPO_INFO_FLAG_ASYNC_FOREGROUND 标志。由于策略在后台刷新期间始终以异步方式应用，因此大多数扩展处理异步前台刷新的方式与处理后台刷新的方式相同。因此，他们不需要为GPO_INFO_FLAG_ASYNC_FOREGROUND标志检查。如果扩展必须区分策略的后台刷新和策略的异步前台刷新，则扩展可以为GPO_INFO_FLAG_ASYNC_FOREGROUND标志检查。

[in] hToken

用户或计算机的令牌，从 LogonUser、 CreateRestrictedToken、 DuplicateToken、 OpenProcessToken 或 OpenThreadToken 函数返回。此令牌必须具有 TOKEN_IMPERSONATE 和 TOKEN_QUERY 访问权限。有关详细信息，请参阅 Access-Token 对象和客户端模拟的访问权限。

[in] hKeyRoot

HKEY_LOCAL_MACHINE或HKEY_CURRENT_USER注册表项的句柄。

[in] pDeletedGPOList

接收已删除 GPO 结构列表的指针。有关详细信息，请参阅 GROUP_POLICY_OBJECT。

[in] pChangedGPOList

接收已更改 GPO 结构列表的指针。有关详细信息，请参阅 GROUP_POLICY_OBJECT。

[in] pHandle

异步完成句柄。如果回调函数不支持异步处理，则此句柄为零。

[in] pbAbort

指定是否继续处理 GPO。如果此参数为 TRUE，GPO 处理将停止。如果此参数为 FALSE，GPO 处理将继续。

[in] pStatusCallback

指向显示状态消息的 StatusMessageCallback 回调函数的指针。在某些情况下，此参数可以为 NULL 。例如，如果系统在后台应用策略，则状态用户界面不存在，并且应用程序无法发送要显示的状态消息。有关更多信息，请参见下面的“备注”部分。

[in] pWbemServices

指定一个 WMI 服务指针，指向策略数据应写入到的 RSoP 命名空间。禁用 RSoP 日志记录时，此参数为 NULL ，表示扩展不应记录 RSoP 数据。

[out] pRsopStatus

指向 HRESULT 返回代码的指针，该代码指示 RSoP 日志记录是否成功。

返回值

如果已成功应用策略， 则返回ERROR_SUCCESS。如果 GPO 列表没有更改，并且要再次调用扩展，则返回 ERROR_OVERRIDE_NOCHANGES。返回 ERROR_OVERRIDE_NOCHANGES 可确保再次调用扩展，即使设置了 NoGPOListChanges 注册表值。 (有关此注册表值的详细信息，请参阅 Remarks.)

如果为策略的异步前台刷新调用了函数，但在异步刷新期间无法应用策略，则返回 ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED 。返回 ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED 指示必须再次调用函数才能同步刷新策略的前景。

否则，返回系统错误代码。

注解

有关详细信息，请参阅实现组策略客户端扩展。

系统会在 LocalSystem 帐户的上下文中调用此函数，该帐户在本地计算机上具有广泛的权限。若要使用网络资源，必须使用 hToken 参数中提供的令牌来模拟用户或计算机。

若要注册此回调函数，请在以下注册表项下创建子项：

\ HKEY_LOCAL_MACHINE软件\微软\\ Windows NT CurrentVersion\Winlogon\GPExtensions\ClientExtensionGuid

子项应为 GUID，以便其唯一。它应包含以下值。

仅当同步应用策略时，才应更新状态消息。这样，就可以在冗长的策略应用程序中提供反馈和诊断。若要使用状态消息回调函数，必须验证 pStatusCallback 是否为 NULL。然后加载消息字符串资源。调用 status 函数时，必须指示字符串是否详细。如果字符串是详细字符串，则回调函数将验证计算机是否处于详细模式并显示消息。有关详细信息，请参阅 StatusMessageCallback。

警告请勿从后台线程调用 pStatusCallback 函数，否则可能会覆盖另一个线程的状态消息。