Функция обратного вызова PFNPROCESSGROUPPOLICYEX (userenv.h)

Статья
03/15/2023

Функция 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_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

Указатель, получающий список удаленных структур объектов групповой политики. Дополнительные сведения см. в разделе GROUP_POLICY_OBJECT.

[in] pChangedGPOList

Указатель, получающий список измененных структур объектов групповой политики. Дополнительные сведения см. в разделе GROUP_POLICY_OBJECT.

[in] pHandle

Дескриптор асинхронного завершения. Если функция обратного вызова не поддерживает асинхронную обработку, этот дескриптор равен нулю.

[in] pbAbort

Указывает, следует ли продолжать обработку объектов групповой политики. Если этот параметр имеет значение TRUE, обработка объекта групповой политики будет прекращена. Если этот параметр имеет значение FALSE, обработка объектов групповой политики продолжится.

[in] pStatusCallback

Указатель на функцию обратного вызова StatusMessageCallback , которая отображает сообщения о состоянии. В некоторых случаях этот параметр может иметь значение NULL . Например, если система применяет политику в фоновом режиме, пользовательский интерфейс состояния отсутствует и приложение не может отправлять сообщения о состоянии для отображения. Дополнительные сведения см. в разделе "Примечания".

[in] pWbemServices

Указывает указатель служб WMI на пространство имен RSoP, в которое должны быть записаны данные политики. Этот параметр имеет значение NULL , если ведение журнала RSoP отключено, что означает, что расширение не должно регистрировать данные RSoP.

[out] pRsopStatus

Указатель на код возврата HRESULT , указывающий, успешно ли выполнено ведение журнала RSoP.

Возвращаемое значение

Если политика успешно применена, верните ERROR_SUCCESS. Если в списке объектов групповой политики нет изменений и расширение необходимо вызвать снова, верните ERROR_OVERRIDE_NOCHANGES. Возврат ERROR_OVERRIDE_NOCHANGES гарантирует повторное вызов расширения, даже если задано значение реестра NoGPOListChanges . (Дополнительные сведения об этом значении реестра см. в разделе Примечания.)

Возврат ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED , если функция была вызвана для асинхронного обновления политики переднего плана, но политика не может быть применена во время асинхронного обновления. Возвращая ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED , функция должна вызываться снова для синхронного обновления политики переднего плана.

В противном случае верните код системной ошибки.

Система вызывает эту функцию в контексте учетной записи LocalSystem, которая имеет обширные привилегии на локальном компьютере. Чтобы использовать сетевые ресурсы, необходимо олицетворять пользователя или компьютер с помощью маркера, предоставленного в параметре hToken .

Чтобы зарегистрировать эту функцию обратного вызова, создайте подраздел в следующем разделе реестра:

HKEY_LOCAL_MACHINE\ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ\Microsoft\\ Windows NT CurrentVersion\Winlogon\GPExtensions\ClientExtensionGuid

Подраздел должен быть идентификатором GUID, чтобы он был уникальным. Он должен содержать следующие значения.

Обновлять сообщение о состоянии следует только в том случае, если политика применяется синхронно. Это позволяет предоставлять отзывы и диагностика во время длительного приложения политики. Чтобы использовать функцию обратного вызова сообщения о состоянии, необходимо убедиться, что pStatusCallback не имеет значение NULL. Затем загрузите ресурс строки сообщения. При вызове функции состояния необходимо указать, является ли строка подробной. Если строка является подробной, функция обратного вызова проверит, что компьютер находится в подробном режиме, и отобразит сообщение. Дополнительные сведения см. в разделе StatusMessageCallback.

Предупреждение Не вызывайте функцию pStatusCallback из фонового потока, иначе вы можете перезаписать сообщение о состоянии другого потока.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Минимальная версия сервера	Windows Server 2008
Целевая платформа	Windows
Header	userenv.h