Funzione NetUserGetLocalGroups (lmaccess.h)
La funzione NetUserGetLocalGroups recupera un elenco di gruppi locali a cui appartiene un utente specificato.
Sintassi
NET_API_STATUS NET_API_FUNCTION NetUserGetLocalGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[in] DWORD flags,
[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 eseguire la funzione. Se questo parametro è NULL, viene usato il computer locale.
[in] username
Puntatore a una stringa costante che specifica il nome dell'utente per cui restituire le informazioni sull'appartenenza al gruppo locale. Se la stringa è del formato DomainName UserName\, è previsto che il nome utente venga trovato nel dominio. Se la stringa è del modulo UserName, il nome utente deve essere trovato nel server specificato dal parametro nome server . Per altre informazioni, vedere la sezione Osservazioni.
[in] level
Livello di informazioni dei dati. Questo parametro può essere il valore seguente.
| Valore | Significato |
|---|---|
|
Restituisce i nomi dei gruppi locali a cui appartiene l'utente. Il parametro bufptr punta a una matrice di strutture LOCALGROUP_USERS_INFO_0 . |
[in] flags
Maschera di flag che influiscono sull'operazione. Attualmente, solo il valore definito è LG_INCLUDE_INDIRECT. Se questo bit è impostato, la funzione restituisce anche i nomi dei gruppi locali in cui l'utente è indirettamente un membro , ovvero l'utente ha l'appartenenza a un gruppo globale che è un membro di uno o più gruppi locali.
[out] bufptr
Puntatore al buffer che riceve i dati. Il formato di questi dati dipende dal valore del parametro di livello . 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 MAX_PREFERRED_LENGTH viene specificato in questo parametro, 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 della rete e lunghezze del buffer delle funzioni di gestione della 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.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è 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. Questo errore viene restituito anche se il parametro nome server ha un valore finale vuoto. |
|
Il livello di chiamata di sistema non è corretto. Questo errore viene restituito se il parametro di livello non è stato specificato come 0. |
|
Un parametro non è corretto. Questo errore viene restituito se il parametro flag contiene un valore diverso da LG_INCLUDE_INDIRECT. |
|
Sono disponibili altre voci. Specificare un buffer sufficiente per ricevere tutte le voci. |
|
Memoria insufficiente disponibile per completare l'operazione. |
|
Impossibile trovare il controller di dominio. |
|
Impossibile trovare l'utente. Questo errore viene restituito se non è stato possibile trovare il nome utente . |
|
Server RPC non disponibile. Questo errore viene restituito se il parametro nome server non è stato trovato. |
Commenti
Se si sta programmando per Active Directory, potrebbe essere possibile chiamare determinati metodi di Active Directory Service Interface (ADSI) per ottenere la stessa funzionalità che è possibile ottenere chiamando le funzioni utente di gestione della rete. Per altre informazioni, vedere IADsUser e IADsComputer.
Se si chiama questa funzione in un controller di dominio che esegue Active Directory, l'accesso è 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 ai membri del gruppo "Accesso compatibile con Windows 2000" di pre-Windows 2000 per 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 della rete. Per altre informazioni sugli elenchi di controllo di accesso, sugli ACL e sui token di accesso, vedere Controllo di accesso Modello.
Il descrittore di sicurezza dell'oggetto Domain viene usato per eseguire il controllo di accesso per questa funzione. Il chiamante deve disporre dell'autorizzazione Read Property per l'oggetto Domain.
Per recuperare un elenco di gruppi globali a cui appartiene un utente specificato, è possibile chiamare la funzione NetUserGetGroups .
I nomi degli account utente sono limitati a 20 caratteri e i nomi di gruppo sono limitati a 256 caratteri. Inoltre, i nomi degli 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
Nell'esempio di codice seguente viene illustrato come recuperare un elenco dei gruppi locali a cui appartiene un utente con una chiamata alla funzione NetUserGetLocalGroups . L'esempio chiama NetUserGetLocalGroups, specificando il livello di informazioni 0 (LOCALGROUP_USERS_INFO_0). L'esempio scorre le voci e stampa il nome di ogni gruppo locale in cui l'utente ha appartenenza. Se tutte le voci disponibili non sono enumerate, stampa anche il numero di voci effettivamente enumerate e il numero totale di voci disponibili. Infine, l'esempio di codice libera la memoria allocata per il buffer delle informazioni.
#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[])
{
LPLOCALGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
DWORD dwFlags = LG_INCLUDE_INDIRECT ;
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 NetUserGetLocalGroups function
// specifying information level 0.
//
// The LG_INCLUDE_INDIRECT flag specifies that the
// function should also return the names of the local
// groups in which the user is indirectly a member.
//
nStatus = NetUserGetLocalGroups(argv[1],
argv[2],
dwLevel,
dwFlags,
(LPBYTE *) &pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPLOCALGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nLocal group(s):\n");
//
// Loop through the entries and
// print the names of the local 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->lgrui0_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 memory.
//
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 |
Vedi anche
Funzioni di gestione della rete