NetQueryDisplayInformation-Funktion (lmaccess.h)

Die NetQueryDisplayInformation-Funktion gibt Konto-, Computer- oder Gruppenkontoinformationen zurück. Rufen Sie diese Funktion auf, um Kontoinformationen für die Anzeige in Benutzeroberflächen schnell aufzulisten.

Syntax

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
);

Parameter

[in] ServerName

Zeiger auf eine konstante Zeichenfolge, die den DNS- oder NetBIOS-Namen des Remoteservers angibt, auf dem die Funktion ausgeführt werden soll. Wenn dieser Parameter NULL ist, wird der lokale Computer verwendet.

[in] Level

Gibt die Informationsebene der Daten an. Dieser Parameter kann einen der folgenden Werte annehmen.

[in] Index

Gibt den Index des ersten Eintrags an, für den Informationen abgerufen werden sollen. Geben Sie null an, um Kontoinformationen ab dem ersten Anzeigeinformationseintrag abzurufen. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] EntriesRequested

Gibt die maximale Anzahl von Einträgen an, für die Informationen abgerufen werden sollen. Unter Windows 2000 und höher gibt jeder Aufruf von NetQueryDisplayInformation maximal 100 Objekte zurück.

[in] PreferredMaximumLength

Gibt die bevorzugte maximale Größe des vom System zugeordneten Puffers in Byte an, der im SortedBuffer-Parameter zurückgegeben wird. Es wird empfohlen, diesen Parameter auf MAX_PREFERRED_LENGTH festzulegen.

[out] ReturnedEntryCount

Zeiger auf einen Wert, der die Anzahl der Einträge im Puffer empfängt, die im Parameter SortedBuffer zurückgegeben werden. Wenn dieser Parameter null ist, gibt es keine Einträge, deren Index so groß ist wie der angegebene. Einträge können zurückgegeben werden, wenn der Rückgabewert der Funktion entweder NERR_Success oder ERROR_MORE_DATA ist.

[out] SortedBuffer

Zeiger auf einen Puffer, der einen Zeiger auf einen vom System zugewiesenen Puffer empfängt, der eine sortierte Liste der angeforderten Informationen angibt. Das Format dieser Daten hängt vom Wert des Level-Parameters ab. Da dieser Puffer vom System zugeordnet wird, muss er mithilfe der NetApiBufferFree-Funktion freigegeben werden. Beachten Sie, dass Sie den Puffer auch dann freigeben müssen, wenn die Funktion mit ERROR_MORE_DATA fehlschlägt. Weitere Informationen finden Sie im folgenden Abschnitt Rückgabewerte und in den Themen Netzwerkverwaltungsfunktionspuffer und Netzwerkverwaltungsfunktionspufferlängen.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.

Hinweise

Wenn Sie diese Funktion auf einem Domänencontroller aufrufen, auf dem Active Directory ausgeführt wird, wird der Zugriff basierend auf der Zugriffssteuerungsliste (Access Control List, ACL) für das sicherungsfähige Objekt zugelassen oder verweigert. Die Standard-ACL ermöglicht es allen authentifizierten Benutzern und Mitgliedern der Gruppe "Pre-Windows 2000-kompatibler Zugriff", die Informationen anzuzeigen. Wenn Sie diese Funktion auf einem Mitgliedsserver oder einer Arbeitsstation aufrufen, können alle authentifizierten Benutzer die Informationen anzeigen. Informationen zum anonymen Zugriff und zum Einschränken des anonymen Zugriffs auf diesen Plattformen finden Sie unter Sicherheitsanforderungen für die Netzwerkverwaltungsfunktionen. Weitere Informationen zu ACLs, ACEs und Zugriffstoken finden Sie unter Access Control Modell.

Die NetQueryDisplayInformation-Funktion gibt nur Informationen zurück, auf die der Aufrufer Lesezugriff hat. Der Aufrufer muss über Listeninhaltszugriff auf das Domain-Objekt und den Zugriff auf die gesamte SAM-Domäne auf das SAM Server-Objekt im Systemcontainer aufzählen.

Die Funktionen NetQueryDisplayInformation und NetGetDisplayInformationIndex bieten einen effizienten Mechanismus zum Aufzählen von Benutzer- und Gruppenkonten. Verwenden Sie diese Funktionen nach Möglichkeit anstelle der NetUserEnum-Funktion oder der NetGroupEnum-Funktion .

Um vertrauende Domänen oder Mitgliedscomputerkonten aufzulisten, rufen Sie NetUserEnum auf, und geben Sie den entsprechenden Filterwert an, um die von Ihnen benötigten Kontoinformationen abzurufen. Um vertrauenswürdige Domänen aufzulisten, rufen Sie die Funktion LsaEnumerateTrustedDomains oder LsaEnumerateTrustedDomainsEx auf .

Die Anzahl der von dieser Funktion zurückgegebenen Einträge hängt vom Sicherheitsdeskriptor ab, der sich im Stammdomänenobjekt befindet. Die API gibt abhängig von den Zugriffsberechtigungen des Benutzers entweder die ersten 100 Einträge oder den gesamten Satz von Einträgen in der Domäne zurück. Der ACE, der zum Steuern dieses Verhaltens verwendet wird, ist "SAM-Enumerate-Entire-Domain" und wird authentifizierten Benutzern standardmäßig gewährt. Administratoren können diese Einstellung ändern, damit Benutzer die gesamte Domäne auflisten können.

Jeder Aufruf von NetQueryDisplayInformation gibt maximal 100 -Objekte zurück. Das Aufrufen der NetQueryDisplayInformation-Funktion zum Aufzählen von Domänenkontoinformationen kann in Bezug auf die Leistung kostspielig sein. Wenn Sie für Active Directory programmieren, können Sie möglicherweise Methoden auf der IDirectorySearch-Schnittstelle verwenden, um ausgelagerte Abfragen für die Domäne zu erstellen. Weitere Informationen finden Sie unter IDirectorySearch::SetSearchPreference und IDirectorySearch::ExecuteSearch. Um vertrauenswürdige Domänen aufzulisten, rufen Sie die LsaEnumerateTrustedDomainsEx-Funktion auf.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Gruppenkontoinformationen mithilfe eines Aufrufs der NetQueryDisplayInformation-Funktion zurückgegeben werden. Wenn der Benutzer einen Servernamen angibt, ruft das Beispiel zuerst die MultiByteToWideChar-Funktion auf, um den Namen in Unicode zu konvertieren. Im Beispiel wird NetQueryDisplayInformation aufgerufen und die Informationsebene 3 (NET_DISPLAY_GROUP) zum Abrufen von Gruppenkontoinformationen angegeben. Wenn Einträge zurückgegeben werden sollen, gibt das Beispiel die Daten zurück und gibt die Gruppeninformationen aus. Schließlich gibt das Codebeispiel den für den Informationspuffer zugeordneten Arbeitsspeicher frei.

#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;
}

Anforderungen

Weitere Informationen

Abrufen von Funktionen

LsaEnumerateTrustedDomains

LsaEnumerateTrustedDomainsEx

NET_DISPLAY_GROUP

NET_DISPLAY_MACHINE

NET_DISPLAY_USER

NetGetDisplayInformationIndex

NetGroupEnum

NetUserEnum

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung