Funzione GetGPOListW (userenv.h)

La funzione GetGPOList recupera l'elenco di oggetti Criteri di gruppo per l'utente o il computer specificato. Questa funzione può essere chiamata in due modi: prima, è possibile usare il token per l'utente o il computer oppure, in secondo luogo, è possibile usare il nome dell'utente o del computer e il nome del controller di dominio.

Sintassi

USERENVAPI BOOL GetGPOListW(
  [in]  HANDLE                hToken,
  [in]  LPCWSTR               lpName,
  [in]  LPCWSTR               lpHostName,
  [in]  LPCWSTR               lpComputerName,
  [in]  DWORD                 dwFlags,
  [out] PGROUP_POLICY_OBJECTW *pGPOList
);

Parametri

[in] hToken

Token per l'utente o il computer restituito dal LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessTokeno funzione openThreadToken. Questo token deve avere accesso TOKEN_IMPERSONATE e TOKEN_QUERY. Per altre informazioni, vedere Access Rights for Access-Token Objects e la sezione Note seguenti.

Se questo parametro è NULL, è necessario specificare i valori per i parametri lpName e lpHostName.

[in] lpName

Puntatore al nome utente o computer, nel formato completo del nome distinto ,ad esempio "CN=utente, OU=utenti, DC=contoso, DC=com").

Se il parametro hToken non è NULL, questo parametro deve essere NULL.

[in] lpHostName

Nome di dominio DNS (preferito) o nome del controller di dominio. È possibile recuperare il nome del controller di dominio usando la funzione DsGetDcName , specificando DS_DIRECTORY_SERVICE_REQUIRED nel parametro flag.

Se il parametro hToken non è NULL, questo parametro deve essere NULL.

[in] lpComputerName

Puntatore al nome del computer utilizzato per determinare il percorso del sito. Il formato del nome è "\\computer_name". Se questo parametro è NULL, viene usato il nome del computer locale.

[in] dwFlags

Valore che specifica flag aggiuntivi utilizzati per controllare il recupero delle informazioni. Se si specifica GPO_LIST_FLAG_MACHINE, la funzione recupera le informazioni sui criteri per il computer. Se non si specifica GPO_LIST_FLAG_MACHINE, la funzione recupera le informazioni sui criteri per l'utente.

Se si specifica GPO_LIST_FLAG_SITEONLY la funzione restituisce solo informazioni sul sito per il computer o l'utente.

[out] pGPOList

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

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

La funzione di GetGPOList è destinata all'uso da parte dei servizi che agiscono per conto di un utente o di un computer. Il servizio chiama questa funzione per ottenere un elenco di oggetti Criteri di gruppo, quindi controlla ogni oggetto Criteri di gruppo per i criteri specifici del servizio.

La chiamata a questa funzione con un token fornisce l'elenco più accurato. Il sistema può eseguire il controllo di accesso per l'utente o il computer. La chiamata a questa funzione con il nome utente o computer e il nome del controller di dominio è più veloce rispetto alla chiamata con un token. Tuttavia, se il token non è specificato, il sistema usa l'accesso di sicurezza del chiamante, il che significa che l'elenco potrebbe non essere completamente corretto per l'utente o il computer desiderato.

Per ottenere l'elenco più accurato di oggetti Criteri di gruppo per un computer quando si chiama GetGPOList, il chiamante deve avere accesso in lettura a ogni unità organizzativa e sito nel dominio del computer, nonché leggere e applicare l'accesso a Criteri di gruppo a tutti gli oggetti Criteri di gruppo collegati ai siti, al dominio o alle unità organizzative di tale dominio. Un esempio di chiamante è un servizio in esecuzione nel computer il cui nome è specificato nel parametro lpName. Un metodo alternativo per ottenere un elenco di oggetti Criteri di gruppo consiste nel chiamare il metodo RsopCreateSession della classe RsopPlanningModeProvider WMI. Il metodo può generare dati dei criteri risultanti per un computer o un account utente in uno scenario ipotetico.

Chiamare la funzione FreeGPOList per liberare l'elenco di oggetti Criteri di gruppo al termine dell'elaborazione.

In genere, è consigliabile chiamare GetGPOList con un token durante il recupero di un elenco di oggetti Criteri di gruppo per un utente, come illustrato nell'esempio di codice seguente.

LPGROUP_POLICY_OBJECT  pGPOList;
      if (GetGPOList (hToken, NULL, NULL, NULL, 0, &pGPOList))
      {
//        Perform processing here. 
//
//        Free the GPO list when you finish processing.
          FreeGPOList (pGPOList);
      }

In genere, per recuperare un elenco di oggetti Criteri di gruppo per un computer, è possibile chiamare GetGPOList con il nome del computer e il nome del controller di dominio, come illustrato nel frammento di codice seguente.

LPGROUP_POLICY_OBJECT  pGPOList;
      if (GetGPOList (NULL, lpMachineName, lpHostName, lpMachineName, GPO_LIST_FLAG_MACHINE, &pGPOList))
      {
//        Perform processing here. 
//
//        Free the GPO list when you finish processing.
          FreeGPOList (pGPOList);
      }

Per recuperare l'elenco di oggetti Criteri di gruppo applicati per un utente o un'estensione e un computer specifici, chiamare la funzione GetAppliedGPOList .

Fabbisogno

Vedere anche

DsGetDcName

FreeGPOList

GROUP_POLICY_OBJECT

Funzioni di Criteri di gruppo

Panoramica di Criteri di gruppo