Funzione NetGroupEnum (lmaccess.h)
La funzione NetGroupEnum recupera informazioni su ogni gruppo globale nel database di sicurezza, ovvero il database sam (Security Accounts Manager) o, nel caso dei controller di dominio, Active Directory.
La funzione NetQueryDisplayInformation fornisce un meccanismo efficiente per enumerare i gruppi globali. Quando possibile, è consigliabile usare NetQueryDisplayInformation anziché la funzione NetGroupEnum .
Sintassi
NET_API_STATUS NET_API_FUNCTION NetGroupEnum(
[in] LPCWSTR servername,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in, out] PDWORD_PTR resume_handle
);
Parametri
[in] servername
Puntatore a una stringa costante che specifica il nome DNS o NetBIOS del server remoto in cui deve essere eseguita la funzione. Se questo parametro è NULL, viene utilizzato il computer locale.
[in] level
Specifica il livello di informazioni dei dati. Questo parametro può avere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Restituisce il nome del gruppo globale. Il parametro bufptr punta a una matrice di strutture GROUP_INFO_0 . |
|
Restituisce il nome del gruppo globale e un commento. Il parametro bufptr punta a una matrice di strutture GROUP_INFO_1 . |
|
Restituisce informazioni dettagliate sul gruppo globale. Il parametro bufptr punta a una matrice di strutture GROUP_INFO_2 . Si noti che in Windows XP e versioni successive è consigliabile usare GROUP_INFO_3 . |
|
Restituisce informazioni dettagliate sul gruppo globale. Il parametro bufptr punta a una matrice di strutture GROUP_INFO_3 .
Windows 2000: Questo livello non è supportato. |
[out] bufptr
Puntatore al buffer per ricevere la struttura di informazioni del gruppo globale. Il formato di questi dati dipende dal valore del parametro level .
Il sistema alloca la memoria per questo buffer. È necessario chiamare la funzione NetApiBufferFree per deallocare la memoria. Si noti che è necessario liberare il buffer anche se la funzione ha esito negativo con ERROR_MORE_DATA.
[in] prefmaxlen
Specifica la lunghezza massima preferita dei dati restituiti, in byte. Se si specifica MAX_PREFERRED_LENGTH, la funzione alloca la quantità di memoria necessaria per contenere i dati. Se si specifica un altro valore in questo parametro, è possibile limitare il numero di byte restituiti dalla funzione. Se le dimensioni del buffer non sono sufficienti per contenere tutte le voci, la funzione restituisce ERROR_MORE_DATA. Per altre informazioni, vedere Buffer delle funzioni di gestione di rete e lunghezze del buffer delle funzioni di gestione di rete.
[out] entriesread
Puntatore a un valore che riceve il conteggio degli elementi effettivamente enumerati.
[out] totalentries
Puntatore a un valore che riceve il numero totale di voci che potrebbero essere state enumerate dalla posizione di ripresa corrente. Il numero totale di voci è solo un suggerimento. Per ulteriori informazioni sulla determinazione del numero esatto di voci, vedere la sezione Osservazioni seguente.
[in, out] resume_handle
Puntatore a una variabile che contiene un handle di ripresa utilizzato per continuare l'enumerazione globale del gruppo. L'handle deve essere zero nella prima chiamata e lasciare invariato per le chiamate successive. Se questo parametro è NULL, non viene archiviato alcun handle di ripresa.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene NERR_Success.
Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti.
| Codice restituito | Descrizione |
|---|---|
|
L'utente non ha accesso alle informazioni richieste. |
|
Il nome del computer non è valido. |
|
Sono disponibili altre voci. Specificare un buffer sufficientemente grande per ricevere tutte le voci. |
Commenti
Se si esegue la programmazione per Active Directory, è possibile chiamare determinati metodi ADSI (Active Directory Service Interface) per ottenere la stessa funzionalità che è possibile ottenere chiamando le funzioni del gruppo di gestione di rete. Per altre informazioni, vedere IADsGroup.
Se si chiama questa funzione in un controller di dominio che esegue Active Directory, l'accesso viene consentito o negato in base all'elenco di controllo di accesso (ACL) per l'oggetto a protezione diretta. L'elenco di controllo di accesso predefinito consente a tutti gli utenti autenticati e i membri del gruppo "Accesso compatibile con Pre-Windows 2000" di visualizzare le informazioni. Se si chiama questa funzione in un server membro o in una workstation, tutti gli utenti autenticati possono visualizzare le informazioni. Per informazioni sull'accesso anonimo e sulla limitazione dell'accesso anonimo in queste piattaforme, vedere Requisiti di sicurezza per le funzioni di gestione di rete. Per altre informazioni su ACL, ACL e token di accesso, vedere Controllo di accesso Model.
La funzione restituisce solo informazioni a cui il chiamante ha accesso in lettura. Il chiamante deve avere accesso a List Contents all'oggetto Domain e Enumerate Entire SAM Domain access on the SAM Server object located in the System container.
Per determinare il numero totale esatto di gruppi, è necessario enumerare l'intero albero, che può essere un'operazione costosa. Per enumerare l'intero albero, usare il parametro resume_handle per continuare l'enumerazione per le chiamate consecutive e usare il parametrontriesread per accumulare il numero totale di gruppi. Se l'applicazione comunica con un controller di dominio, è consigliabile usare il provider LDAP ADSI per recuperare questo tipo di dati in modo più efficiente. Il provider LDAP ADSI implementa un set di oggetti ADSI che supportano varie interfacce ADSI. Per altre informazioni, vedere Provider di servizi ADSI.
I nomi degli account utente sono limitati a 20 caratteri e i nomi dei gruppi sono limitati a 256 caratteri. Inoltre, i nomi di account non possono essere terminati da un punto e non possono includere virgole o uno dei caratteri stampabili seguenti: ", /, , [, ], :, |, <, , >+, =, ;, ?, *. I nomi non possono includere anche caratteri nell'intervallo 1-31, che non sono stampabili.
Requisiti
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | lmaccess.h (include Lm.h) |
| Libreria | Netapi32.lib |
| DLL | Netapi32.dll |