Platform SDK: Group Policy

ProcessGroupPolicyProc

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

DWORD ProcessGroupPolicyProc(
  DWORD dwFlags,
  HANDLE hToken,
  HKEY hKeyRoot,
  PGROUP_POLICY_OBJECT pDeletedGPOList,
  PGROUP_POLICY_OBJECT pChangedGPOList,
  ASYNCCOMPLETIONHANDLE pHandle,
  BOOL *pbAbort,
  PFNSTATUSMESSAGECALLBACK pStatusCallback
);

Parameters

dwFlags

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

Flag	Description
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_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.

hToken

[in] 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.

hKeyRoot

[in] Handle to the HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER registry key.

pDeletedGPOList

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

pChangedGPOList

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

pHandle

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

pbAbort

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

pStatusCallback

[in] Pointer to a StatusMessageCallback callback function that displays status messages. This parameter can be NULL. 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 Values

If policy was applied successfully, return ERROR_SUCCESS. If the extension should be called again even if the NoGPOListChanges registry value is set (see Remarks) and there are no changes to the GPO list, return ERROR_OVERRIDE_NOCHANGES. Otherwise, return a Win32 error code.

Remarks

The system calls this function in the context of the LocalSystem account. 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

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

Value	Meaning
DllName	A REG_EXPAND_SZ value that specifies the path to the DLL that contains the callback function.
EnableAsynchronousProcessing	If this value is 1, the callback function will complete its processing asynchronously. When the callback function is finished, it should call the ProcessGroupPolicyCompleted function.
MaxNoGPOListChangesInterval	Specifies the maximum number of minutes the extension is to be skipped because policy has not changed. If the system is refreshing policy and this limit has been exceeded, the extension is called without GPO_INFO_FLAG_NOCHANGES.
NoBackgroundPolicy	If this value is 1, the callback function is not called when policy is applied in the background.
NoGPOListChanges	If this value is 1, the callback function is not called when there are no changes in the GPO list.
NoMachinePolicy	If this value is 1, the callback function is not called when computer policy is processed.
NoSlowLink	If this value is 1, the callback function is not called over a slow link.
NotifyLinkTransition	If this value is 1, the callback function is called when a change in link speed is detected between policy applications.
NoUserPolicy	If this value is 1, the callback function is not called when user policy is processed.
PerUserLocalSettings	If this value is 1, user policy settings must be cached on a per-user and per-computer basis.
ProcessGroupPolicy	A REG_SZ value that specifies the name of the callback function.
RequiresSuccessfulRegistry	If this value is 1, the callback function should be called only if the registry extension was successfully processed.

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.

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

Requirements

Windows NT/2000: Requires Windows 2000.
Header: Declared in Userenv.h.

ProcessGroupPolicyProc

Parameters

Return Values

Remarks

Requirements

See Also