PFNPROCESSGROUPPOLICY callback function (userenv.h)

Article
02/22/2024

The ProcessGroupPolicy function is an application-defined callback function used when applying policy. The PFNPROCESSGROUPPOLICY type defines a pointer to this callback function. ProcessGroupPolicy is a placeholder for the application-defined function name.

This callback function is not useful for Resultant Set of Policy (RSoP) processing; use the ProcessGroupPolicyEx callback function instead.

Syntax

PFNPROCESSGROUPPOLICY Pfnprocessgrouppolicy;

DWORD Pfnprocessgrouppolicy(
  [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
)
{...}

Parameters

[in] dwFlags

This parameter can be one or more of the following flags.

GPO_INFO_FLAG_MACHINE

Apply computer policy rather than user policy.

GPO_INFO_FLAG_BACKGROUND

Perform a background refresh of the policy.

GPO_INFO_FLAG_ASYNC_FOREGROUND

Perform an asynchronous foreground refresh of policy. For more information about foreground policy application, see Initial Processing of Group Policy.

GPO_INFO_FLAG_SLOWLINK

The policy is being applied across a slow link.

GPO_INFO_FLAG_VERBOSE

Write verbose output to the event log.

GPO_INFO_FLAG_NOCHANGES

No changes to the GPO were detected.

GPO_INFO_FLAG_LINKTRANSITION

A change in the link speed was detected between policy applications.

GPO_INFO_FLAG_LOGRSOP_TRANSITION

A change in RSoP logging was detected between the application of the previous policy and the application of the current policy.

GPO_INFO_FLAG_FORCED_REFRESH

A forced policy refresh is being applied.

GPO_INFO_FLAG_SAFEMODE_BOOT

Safe mode flag.

[in] hToken

Token for the user or computer, returned from the LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken, or OpenThreadToken function. This token must have TOKEN_IMPERSONATE and TOKEN_QUERY access. For more information, see Access Rights for Access-Token Objects and Client Impersonation.

[in] hKeyRoot

Handle to the HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER registry key.

[in] pDeletedGPOList

Pointer that receives the list of deleted GPO structures. For more information, see GROUP_POLICY_OBJECT.

[in] pChangedGPOList

Pointer that receives the list of changed GPO structures. For more information, see GROUP_POLICY_OBJECT.

[in] pHandle

Asynchronous completion handle. If the callback function does not support asynchronous processing, this handle is zero.

[in] pbAbort

Specifies whether to continue processing GPOs. If this parameter is TRUE, GPO processing will cease. If this parameter is FALSE, GPO processing will continue.

[in] pStatusCallback

Pointer to a StatusMessageCallback callback function that displays status messages. This parameter can be NULL in certain cases. For example, if the system is applying policy in the background, the status user interface is not present and the application cannot send status messages to be displayed. For more information, see the following Remarks section.

Return value

If policy was applied successfully, return ERROR_SUCCESS. If there are no changes to the GPO list, and the extension is to be called again, return ERROR_OVERRIDE_NOCHANGES. Returning ERROR_OVERRIDE_NOCHANGES ensures that the extension is called again, even if the NoGPOListChanges registry value is set. (For more information about this registry value, see Remarks.) Otherwise, return a system error code.

Remarks

For more information, see Implementing a Group Policy Client-side Extension.

The system calls this function in the context of the LocalSystem account, which has extensive privileges on the local computer. To use network resources, you must impersonate the user or computer by using the token provided in the hToken parameter.

To register this callback function, create a subkey under the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GPExtensions\ClientExtensionGuid

The subkey should be a GUID, so that it is unique. It should contain the following values.

You should update the status message only if you are applying policy synchronously. This allows you to provide feedback and diagnostics during a lengthy policy application. To use the status message callback function, you must verify that pStatusCallback is not NULL. Then load your message string resource. When you call the status function, you must indicate whether the string is verbose. If the string is verbose, the callback function will verify that the computer is in verbose mode and display the message. For more information, see StatusMessageCallback.

Warning Do not call the pStatusCallback function from a background thread because you may overwrite another thread's status message.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	userenv.h