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.
| Wert | Bedeutung |
|---|---|
|
Zurückgeben von Benutzerkontoinformationen. Der Parameter SortedBuffer verweist auf ein Array von NET_DISPLAY_USER Strukturen. |
|
Zurückgeben einzelner Computerinformationen. Der Parameter SortedBuffer verweist auf ein Array von NET_DISPLAY_MACHINE Strukturen. |
|
Zurückgeben von Gruppenkontoinformationen. Der Parameter SortedBuffer verweist auf ein Array von NET_DISPLAY_GROUP Strukturen. |
[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.
| Rückgabecode | Beschreibung |
|---|---|
|
Der Benutzer besitzt keinen Zugriff auf die angeforderten Informationen. |
|
Der Parameter Level gibt einen ungültigen Wert an. |
|
Weitere Einträge sind verfügbar. Das heißt, der letzte im SortedBuffer-Parameter zurückgegebene Eintrag ist nicht der letzte verfügbare Eintrag. Um weitere Einträge abzurufen, rufen Sie NetQueryDisplayInformation erneut auf, wobei der Index-Parameter auf den Wert festgelegt ist, der im next_index Member des letzten Eintrags in SortedBuffer zurückgegeben wird. Beachten Sie, dass Sie den Wert des next_index-Members nicht zu irgendeinem Zweck verwenden sollten, außer zum Abrufen weiterer Daten mit zusätzlichen Aufrufen von NetQueryDisplayInformation. |
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
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | lmaccess.h (lm.h einschließen) |
| Bibliothek | Netapi32.lib |
| DLL | Netapi32.dll |