ProcessGroupPolicyEx callback function

The ProcessGroupPolicyEx function is an application-defined callback function used when applying policy. This extended function also supports the logging of Resultant Set of Policy (RSoP) data. The PFNPROCESSGROUPPOLICYEX type defines a pointer to this callback function. ProcessGroupPolicyEx is a placeholder for the application-defined function name.

Syntax


DWORD CALLBACK ProcessGroupPolicyEx(
  _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
);

Parameters

dwFlags [in]

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

FlagMeaning
GPO_INFO_FLAG_MACHINE

Apply computer policy rather than user policy.

GPO_INFO_FLAG_BACKGROUND

Perform a background refresh of the policy. For more information, see the text following this table.

GPO_INFO_FLAG_ASYNC_FOREGROUND

Perform an asynchronous foreground refresh of policy. For more information, see the text following this table. 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.

 

The GPO_INFO_FLAG_BACKGROUND flag and the GPO_INFO_FLAG_ASYNC_FOREGROUND flag can both be set. Because policies are always applied asynchronously during a background refresh, most extensions handle an asynchronous foreground refresh in the same manner in which they handle a background refresh. Therefore, they do not need to check for the GPO_INFO_FLAG_ASYNC_FOREGROUND flag. In instances when an extension must distinguish between a background refresh of policy and an asynchronous foreground refresh of policy, the extension can check for the GPO_INFO_FLAG_ASYNC_FOREGROUND flag.

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. For more information, see Access Rights for Access-Token Objects and Client Impersonation.

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 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.

pWbemServices [in]

Specifies a WMI services pointer to the RSoP namespace to which the policy data should be written. This parameter is NULL when RSoP logging is disabled, indicating that the extension should not log RSoP data.

pRsopStatus [out]

Pointer to an HRESULT return code that indicates whether RSoP logging was successful.

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.)

Return ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED if the function was called for an asynchronous foreground refresh of policy but policy could not be applied during the asynchronous refresh. Returning ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED indicates that the function must be called again for a synchronous foreground refresh of policy.

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.

ValueMeaning
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 completes its processing asynchronously.

When the callback function is finished, it should call the ProcessGroupPolicyCompletedEx function.

ExtensionEventSource

A REG_MULTI_SZ value that specifies the (event source name, event log name) for client-side extensions.

GenerateGroupPolicy

A REG_SZ value that specifies the name of the GenerateGroupPolicy callback function that generates RSoP data.

MaxNoGPOListChangesInterval

Specifies the maximum number of minutes to skip the extension when policy has not changed. If the system is refreshing policy and this limit has been exceeded, the system calls the extension without specifying GPO_INFO_FLAG_NOCHANGES.

NoBackgroundPolicy

If this value is 1, do not call the callback function when policy is applied in the background.

NoGPOListChanges

If this value is 1, it indicates that it is not necessary to call the callback function when there has been no change in the GPO list.

NoMachinePolicy

If this value is 1, do not call the callback function when computer policy is processed.

NoSlowLink

If this value is 1, do not call the callback function over a slow link.

NotifyLinkTransition

If this value is 1, call the callback function to notify the extension when a change in link speed is detected between policy applications.

NoUserPolicy

If this value is 1, do not call the callback function 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 application-defined ProcessGroupPolicy callback function.

Note that this value has been superseded by the ProcessGroupPolicyEx value.

ProcessGroupPolicyEx

A REG_SZ value that specifies the name of the application-defined ProcessGroupPolicyEx callback function.

RequiresSuccessfulRegistry

If this value is 1, the callback function should be called only if the registry extension was successfully processed on the client.

 

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 or you may overwrite another thread's status message.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Userenv.h

See also

Group Policy Overview
Group Policy Functions
ProcessGroupPolicyCompletedEx
RefreshPolicy
RefreshPolicyEx
StatusMessageCallback
RSOP_ExtensionStatus
ProcessGroupPolicy

 

 

Show:
© 2014 Microsoft