Funzione NetQueryDisplayInformation (lmaccess.h)
La funzione NetQueryDisplayInformation restituisce informazioni sull'account utente, sul computer o sull'account del gruppo. Chiamare questa funzione per enumerare rapidamente le informazioni sull'account per la visualizzazione nelle interfacce utente.
Sintassi
NET_API_STATUS NET_API_FUNCTION NetQueryDisplayInformation(
[in] LPCWSTR ServerName,
[in] DWORD Level,
[in] DWORD Index,
[in] DWORD EntriesRequested,
[in] DWORD PreferredMaximumLength,
[out] LPDWORD ReturnedEntryCount,
[out] PVOID *SortedBuffer
);
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] Level
Specifica il livello di informazioni dei dati. Questo parametro può avere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Restituire le informazioni sull'account utente. Il parametro SortedBuffer punta a una matrice di strutture NET_DISPLAY_USER . |
|
Restituisce singole informazioni sul computer. Il parametro SortedBuffer punta a una matrice di strutture NET_DISPLAY_MACHINE . |
|
Restituire le informazioni sull'account del gruppo. Il parametro SortedBuffer punta a una matrice di strutture NET_DISPLAY_GROUP . |
[in] Index
Specifica l'indice della prima voce per cui recuperare informazioni. Specificare zero per recuperare le informazioni sull'account a partire dalla prima voce di informazioni di visualizzazione. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in] EntriesRequested
Specifica il numero massimo di voci per cui recuperare informazioni. In Windows 2000 e versioni successive ogni chiamata a NetQueryDisplayInformation restituisce un massimo di 100 oggetti.
[in] PreferredMaximumLength
Specifica le dimensioni massime preferite, in byte, del buffer allocato dal sistema restituito nel parametro SortedBuffer . È consigliabile impostare questo parametro su MAX_PREFERRED_LENGTH.
[out] ReturnedEntryCount
Puntatore a un valore che riceve il numero di voci nel buffer restituito nel parametro SortedBuffer . Se questo parametro è zero, non sono presenti voci con un indice di grandi dimensioni come specificato. Le voci possono essere restituite quando il valore restituito della funzione è NERR_Success o ERROR_MORE_DATA.
[out] SortedBuffer
Puntatore a un buffer che riceve un puntatore a un buffer allocato dal sistema che specifica un elenco ordinato delle informazioni richieste. Il formato di questi dati dipende dal valore del parametro Level . Poiché questo buffer viene allocato dal sistema, 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. Per altre informazioni, vedere la sezione Valori restituiti seguenti e gli argomenti Buffer delle funzioni di gestione della rete e lunghezze del buffer delle funzioni di gestione della rete.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è NERR_Success.
Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.
| Codice restituito | Descrizione |
|---|---|
|
L'utente non ha accesso alle informazioni richieste. |
|
Il parametro Level specifica un valore non valido. |
|
Sono disponibili altre voci. Ovvero, l'ultima voce restituita nel parametro SortedBuffer non è l'ultima voce disponibile. Per recuperare voci aggiuntive, chiamare di nuovo NetQueryDisplayInformation con il parametro Index impostato sul valore restituito nel membro next_index dell'ultima voce in SortedBuffer. Si noti che non è consigliabile usare il valore del membro next_index per qualsiasi scopo, tranne per recuperare altri dati con chiamate aggiuntive a NetQueryDisplayInformation. |
Commenti
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.
La funzione NetQueryDisplayInformation restituisce solo informazioni a cui il chiamante ha accesso in lettura. Il chiamante deve disporre dell'accesso al contenuto elenco all'oggetto Domain e enumera l'intero accesso al dominio SAM nell'oggetto SAM Server che si trova nel contenitore System.
Le funzioni NetQueryDisplayInformation e NetGetDisplayInformationIndex forniscono un meccanismo efficiente per enumerare gli account utente e di gruppo. Se possibile, usare queste funzioni anziché la funzione NetUserEnum o la funzione NetGroupEnum.
Per enumerare domini di attendibilità o account computer membro, chiamare NetUserEnum, specificando il valore di filtro appropriato per ottenere le informazioni sull'account necessarie. Per enumerare i domini attendibili, chiamare la funzione LsaEnumerateTrustedDomains o LsaEnumerateTrustedDomainsEx .
Il numero di voci restituite da questa funzione dipende dal descrittore di sicurezza che si trova nell'oggetto di dominio radice. L'API restituirà le prime 100 voci o l'intero set di voci nel dominio, a seconda dei privilegi di accesso dell'utente. L'ACE usato per controllare questo comportamento è "SAM-Enumerate-Entire-Domain" e viene concesso agli utenti autenticati per impostazione predefinita. Gli amministratori possono modificare questa impostazione per consentire agli utenti di enumerare l'intero dominio.
Ogni chiamata a NetQueryDisplayInformation restituisce un massimo di 100 oggetti. La chiamata alla funzione NetQueryDisplayInformation per enumerare le informazioni sull'account di dominio può essere costosa in termini di prestazioni. Se si esegue la programmazione per Active Directory, è possibile usare i metodi nell'interfaccia IDirectorySearch per eseguire query impaginate sul dominio. Per altre informazioni, vedere IDirectorySearch::SetSearchPreference e IDirectorySearch::ExecuteSearch. Per enumerare i domini attendibili, chiamare la funzione LsaEnumerateTrustedDomainsEx .
Esempio
Nell'esempio di codice seguente viene illustrato come restituire informazioni sull'account del gruppo usando una chiamata alla funzione NetQueryDisplayInformation . Se l'utente specifica un nome del server, l'esempio chiama prima la funzione MultiByteToWideChar per convertire il nome in Unicode. L'esempio chiama NetQueryDisplayInformation, specificando il livello di informazioni 3 (NET_DISPLAY_GROUP) per recuperare le informazioni sull'account del gruppo. Se sono presenti voci da restituire, l'esempio restituisce i dati e stampa le informazioni del gruppo. Infine, l'esempio di codice libera la memoria allocata per il buffer delle informazioni.
#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <stdio.h>
#include <lm.h>
#pragma comment(lib, "netapi32.lib")
void main( int argc, char *argv[ ] )
{
PNET_DISPLAY_GROUP pBuff, p;
DWORD res, dwRec, i = 0;
//
// You can pass a NULL or empty string
// to retrieve the local information.
//
TCHAR szServer[255]=TEXT("");
if(argc > 1)
//
// Check to see if a server name was passed;
// if so, convert it to Unicode.
//
MultiByteToWideChar(CP_ACP, 0, argv[1], -1, szServer, 255);
do // begin do
{
//
// Call the NetQueryDisplayInformation function;
// specify information level 3 (group account information).
//
res = NetQueryDisplayInformation(szServer, 3, i, 1000, MAX_PREFERRED_LENGTH, &dwRec, (PVOID*) &pBuff);
//
// If the call succeeds,
//
if((res==ERROR_SUCCESS) || (res==ERROR_MORE_DATA))
{
p = pBuff;
for(;dwRec>0;dwRec--)
{
//
// Print the retrieved group information.
//
printf("Name: %S\n"
"Comment: %S\n"
"Group ID: %u\n"
"Attributes: %u\n"
"--------------------------------\n",
p->grpi3_name,
p->grpi3_comment,
p->grpi3_group_id,
p->grpi3_attributes);
//
// If there is more data, set the index.
//
i = p->grpi3_next_index;
p++;
}
//
// Free the allocated memory.
//
NetApiBufferFree(pBuff);
}
else
printf("Error: %u\n", res);
//
// Continue while there is more data.
//
} while (res==ERROR_MORE_DATA); // end do
return;
}
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 |