Funzione NetUserGetGroups (lmaccess.h)
La funzione NetUserGetGroups recupera un elenco di gruppi globali a cui appartiene un utente specificato.
Sintassi
NET_API_STATUS NET_API_FUNCTION NetUserGetGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries
);
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] username
Puntatore a una stringa costante che specifica il nome dell'utente da cercare in ogni account di gruppo. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in] level
Livello informativo dei dati richiesti. Questo parametro può avere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Restituisce i nomi dei gruppi globali a cui appartiene l'utente. Il parametro bufptr punta a una matrice di strutture GROUP_USERS_INFO_0 . |
|
Restituisce i nomi dei gruppi globali a cui appartiene l'utente con attributi. Il parametro bufptr punta a una matrice di strutture GROUP_USERS_INFO_1 . |
[out] bufptr
Puntatore al buffer che riceve i dati. Questo buffer viene allocato dal sistema e deve essere liberato usando la funzione NetApiBufferFree . Si noti che è necessario liberare il buffer anche se la funzione ha esito negativo con ERROR_MORE_DATA.
[in] prefmaxlen
Lunghezza massima preferita, in byte, dei dati restituiti. Se viene specificato MAX_PREFERRED_LENGTH, la funzione alloca la quantità di memoria necessaria per i dati. Se in questo parametro viene specificato un altro valore, può 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 recuperati.
[out] totalentries
Puntatore a un valore che riceve il numero totale di voci che potrebbero essere state recuperate.
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 dispone dei diritti di accesso alle informazioni richieste. |
|
Impossibile trovare il percorso di rete. Questo errore viene restituito se non è stato possibile trovare il parametro servername . |
|
Il livello di chiamata di sistema non è corretto. Questo errore viene restituito se il parametro di livello è stato specificato come valore diverso da 0 o 1. |
|
La sintassi del nome non è corretta. Questo errore viene restituito se il parametro servername contiene spazi vuoti iniziali o finali o contiene un carattere non valido. |
|
Sono disponibili altre voci. Specificare un buffer sufficientemente grande per ricevere tutte le voci. |
|
Memoria insufficiente per completare l'operazione. |
|
An internal error occurred. |
|
Impossibile trovare l'utente. Questo errore viene restituito se non è stato possibile trovare il nome utente . |
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 utente di gestione di rete. Per altre informazioni, vedere IADsUser e IADsComputer.
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.
Il descrittore di sicurezza dell'oggetto User viene utilizzato per eseguire il controllo di accesso per questa funzione.
Per recuperare un elenco dei gruppi locali a cui appartiene un utente, è possibile chiamare la funzione NetUserGetLocalGroups . I gruppi di rete sono separati e distinti dai gruppi di sistema Windows NT.
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.
Esempio
L'esempio di codice seguente illustra come recuperare un elenco di gruppi globali a cui appartiene un utente con una chiamata alla funzione NetUserGetGroups . L'esempio chiama NetUserGetGroups, specificando il livello di informazioni 0 ( GROUP_USERS_INFO_0). Il codice scorre le voci e stampa il nome dei gruppi globali in cui l'utente dispone dell'appartenenza. L'esempio stampa anche il numero totale di voci disponibili e il numero di voci effettivamente enumerate se non corrispondono. Infine, l'esempio di codice libera la memoria allocata per il buffer.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t *argv[])
{
LPGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
NET_API_STATUS nStatus;
if (argc != 3)
{
fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
exit(1);
}
//
// Call the NetUserGetGroups function, specifying level 0.
//
nStatus = NetUserGetGroups(argv[1],
argv[2],
dwLevel,
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nGlobal group(s):\n");
//
// Loop through the entries;
// print the name of the global groups
// to which the user belongs.
//
for (i = 0; i < dwEntriesRead; i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
wprintf(L"\t-- %s\n", pTmpBuf->grui0_name);
pTmpBuf++;
dwTotalCount++;
}
}
//
// If all available entries were
// not enumerated, print the number actually
// enumerated and the total number available.
//
if (dwEntriesRead < dwTotalEntries)
fprintf(stderr, "\nTotal entries: %d", dwTotalEntries);
//
// Otherwise, just print the total.
//
printf("\nEntries enumerated: %d\n", dwTotalCount);
}
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
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 |