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.

[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.

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

Vedi anche

Ottenere funzioni

LsaEnumerateTrustedDomains

LsaEnumerateTrustedDomainsEx

NET_DISPLAY_GROUP

NET_DISPLAY_MACHINE

NET_DISPLAY_USER

NetGetDisplayInformationIndex

NetGroupEnum

NetUserEnum

Funzioni di gestione della rete

Panoramica sulla gestione della rete