Funzione di callback PFNPROCESSGROUPPOLICYEX (userenv.h)

Articolo
08/26/2023

La funzione ProcessGroupPolicyEx è una funzione di callback definita dall'applicazione usata durante l'applicazione dei criteri. Questa funzione estesa supporta anche la registrazione dei dati RSoP (Resultant Set of Policy). Il tipo PFNPROCESSGROUPPOLICYEX definisce un puntatore a questa funzione di callback. ProcessGroupPolicyEx è un segnaposto per il nome della funzione definito dall'applicazione.

Sintassi

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

Parametri

[in] dwFlags

Questo parametro può essere uno o più dei flag seguenti.

GPO_INFO_FLAG_MACHINE

Applicare criteri computer anziché criteri utente.

GPO_INFO_FLAG_BACKGROUND

Eseguire un aggiornamento in background del criterio. Per altre informazioni, vedere il testo seguente in questo elenco.

GPO_INFO_FLAG_ASYNC_FOREGROUND

Eseguire un aggiornamento in primo piano asincrono dei criteri. Per altre informazioni, vedere il testo seguente in questo elenco. Per altre informazioni sull'applicazione dei criteri in primo piano, vedere Elaborazione iniziale di Criteri di gruppo.

GPO_INFO_FLAG_SLOWLINK

Il criterio viene applicato in un collegamento lento.

GPO_INFO_FLAG_VERBOSE

Scrivere un output dettagliato nel registro eventi.

GPO_INFO_FLAG_NOCHANGES

Non sono state rilevate modifiche all'oggetto Criteri di gruppo.

GPO_INFO_FLAG_LINKTRANSITION

È stata rilevata una modifica della velocità del collegamento tra le applicazioni dei criteri.

GPO_INFO_FLAG_LOGRSOP_TRANSITION

È stata rilevata una modifica nella registrazione RSoP tra l'applicazione dei criteri precedenti e l'applicazione del criterio corrente.

GPO_INFO_FLAG_FORCED_REFRESH

Viene applicato un aggiornamento forzato dei criteri.

GPO_INFO_FLAG_SAFEMODE_BOOT

Flag modalità provvisoria.

Il flag GPO_INFO_FLAG_BACKGROUND e il flag di GPO_INFO_FLAG_ASYNC_FOREGROUND possono essere impostati entrambi. Poiché i criteri vengono sempre applicati in modo asincrono durante un aggiornamento in background, la maggior parte delle estensioni gestisce un aggiornamento in primo piano asincrono nello stesso modo in cui gestiscono un aggiornamento in background. Pertanto, non è necessario verificare la presenza del flag di GPO_INFO_FLAG_ASYNC_FOREGROUND . Nelle istanze in cui un'estensione deve distinguere tra un aggiornamento in background dei criteri e un aggiornamento in primo piano asincrono dei criteri, l'estensione può verificare la presenza del flag di GPO_INFO_FLAG_ASYNC_FOREGROUND .

[in] hToken

Token per l'utente o il computer restituito dalla funzione LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken o OpenThreadToken. Questo token deve avere TOKEN_IMPERSONATE e TOKEN_QUERY accesso. Per altre informazioni, vedere Diritti di accesso per oggetti Access-Token e rappresentazione client.

[in] hKeyRoot

Gestire la chiave del Registro di sistema HKEY_LOCAL_MACHINE o HKEY_CURRENT_USER .

[in] pDeletedGPOList

Puntatore che riceve l'elenco di strutture oggetto Criteri di gruppo eliminate. Per altre informazioni, vedere GROUP_POLICY_OBJECT.

[in] pChangedGPOList

Puntatore che riceve l'elenco delle strutture oggetto Criteri di gruppo modificate. Per altre informazioni, vedere GROUP_POLICY_OBJECT.

[in] pHandle

Handle di completamento asincrono. Se la funzione callback non supporta l'elaborazione asincrona, questo handle è zero.

[in] pbAbort

Specifica se continuare l'elaborazione degli oggetti Criteri di gruppo. Se questo parametro è TRUE, l'elaborazione criteri di gruppo verrà interrotta. Se questo parametro è FALSE, l'elaborazione criteri di gruppo continuerà.

[in] pStatusCallback

Puntatore a una funzione di callback StatusMessageCallback che visualizza i messaggi di stato. Questo parametro può essere NULL in alcuni casi. Ad esempio, se il sistema applica criteri in background, l'interfaccia utente di stato non è presente e l'applicazione non può inviare messaggi di stato da visualizzare. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in] pWbemServices

Specifica un puntatore ai servizi WMI allo spazio dei nomi RSoP a cui devono essere scritti i dati dei criteri. Questo parametro è NULL quando la registrazione RSoP è disabilitata, che indica che l'estensione non deve registrare i dati RSoP.

[out] pRsopStatus

Puntatore a un codice restituito HRESULT che indica se la registrazione RSoP ha avuto esito positivo.

Valore restituito

Se i criteri sono stati applicati correttamente, restituire ERROR_SUCCESS. Se non sono presenti modifiche all'elenco criteri di gruppo e l'estensione deve essere chiamata di nuovo, restituire ERROR_OVERRIDE_NOCHANGES. La restituzione di ERROR_OVERRIDE_NOCHANGES garantisce che l'estensione venga chiamata di nuovo, anche se il valore del Registro di sistema NoGPOListChanges è impostato. Per altre informazioni su questo valore del Registro di sistema, vedere Osservazioni.

Restituisce ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED se la funzione è stata chiamata per un aggiornamento in primo piano asincrono dei criteri, ma non è stato possibile applicare criteri durante l'aggiornamento asincrono. La restituzione di ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED indica che la funzione deve essere chiamata di nuovo per un aggiornamento in primo piano sincrono dei criteri.

In caso contrario, restituisce un codice di errore di sistema.

Commenti

Per altre informazioni, vedere Implementazione di un'estensione lato client Criteri di gruppo.

Il sistema chiama questa funzione nel contesto dell'account LocalSystem, con privilegi estesi nel computer locale. Per usare le risorse di rete, è necessario rappresentare l'utente o il computer usando il token fornito nel parametro hToken .

Per registrare questa funzione di callback, creare una sottochiave nella chiave del Registro di sistema seguente:

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

La sottochiave deve essere un GUID, in modo che sia univoca. Deve contenere i valori seguenti.

È consigliabile aggiornare il messaggio di stato solo se si applicano criteri in modo sincrono. In questo modo è possibile fornire commenti e suggerimenti e diagnostica durante un'applicazione di criteri di lunghezza. Per usare la funzione callback del messaggio di stato, è necessario verificare che pStatusCallback non sia NULL. Caricare quindi la risorsa stringa di messaggio. Quando si chiama la funzione di stato, è necessario indicare se la stringa è dettagliata. Se la stringa è dettagliata, la funzione callback verificherà che il computer sia in modalità dettagliata e visualizzi il messaggio. Per altre informazioni, vedere StatusMessageCallback.

Avviso Non chiamare la funzione pStatusCallback da un thread in background oppure è possibile sovrascrivere il messaggio di stato di un altro thread.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	userenv.h