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

指定應該寫入原則數據的 RSoP 命名空間的 WMI 服務指標。停用 RSoP 記錄時，此參數為 NULL ，表示延伸模組不應該記錄 RSoP 數據。

[out] pRsopStatus

HRESULT 傳回碼的指標，指出 RSoP 記錄是否成功。

傳回值

如果已成功套用原則，請 傳回ERROR_SUCCESS。如果 GPO 清單沒有任何變更，而且要再次呼叫擴充功能，請傳回 ERROR_OVERRIDE_NOCHANGES。傳回 ERROR_OVERRIDE_NOCHANGES 可確保重新呼叫延伸模組，即使已設定 NoGPOListChanges 登錄值也一樣。 (如需此登錄值的詳細資訊，請參閱.)

如果針對原則的異步前景重新整理呼叫函式，但無法在異步重新整理期間套用原則，則傳回 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 函式，或者您可以覆寫另一個線程的狀態消息。