NetUserGetLocalGroups-Funktion (lmaccess.h)
Die NetUserGetLocalGroups-Funktion ruft eine Liste der lokalen Gruppen ab, zu denen ein angegebener Benutzer gehört.
Syntax
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
);
Parameter
[in] servername
Ein 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] username
Ein Zeiger auf eine konstante Zeichenfolge, die den Namen des Benutzers angibt, für den Informationen zur lokalen Gruppenmitgliedschaft zurückgegeben werden sollen. Wenn die Zeichenfolge das Format DomainName\UserName hat, wird erwartet, dass der Benutzername in dieser Domäne gefunden wird. Wenn die Zeichenfolge das Format UserName hat, wird erwartet, dass der Benutzername auf dem servername-Parameter angegebenen Server gefunden wird. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
[in] level
Die Informationsebene der Daten. Dieser Parameter kann der folgende Wert sein.
| Wert | Bedeutung |
|---|---|
|
Gibt die Namen der lokalen Gruppen zurück, zu denen der Benutzer gehört. Der bufptr-Parameter verweist auf ein Array von LOCALGROUP_USERS_INFO_0 Strukturen. |
[in] flags
Eine Bitmaske von Flags, die sich auf den Vorgang auswirken. Derzeit wird nur der definierte Wert LG_INCLUDE_INDIRECT. Wenn dieses Bit festgelegt ist, gibt die Funktion auch die Namen der lokalen Gruppen zurück, in denen der Benutzer indirekt Mitglied ist (d. a. der Benutzer ist mitglied in einer globalen Gruppe, die selbst Mitglied einer oder mehrerer lokaler Gruppen ist).
[out] bufptr
Ein Zeiger auf den Puffer, der die Daten empfängt. Das Format dieser Daten hängt vom Wert des level-Parameters ab. Dieser Puffer wird vom System zugeordnet und muss 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.
[in] prefmaxlen
Die bevorzugte maximale Länge der zurückgegebenen Daten in Bytes. Wenn in diesem Parameter MAX_PREFERRED_LENGTH angegeben ist, ordnet die Funktion den für die Daten erforderlichen Arbeitsspeicher zu. Wenn in diesem Parameter ein anderer Wert angegeben ist, kann die Anzahl der Von der Funktion zurückgegebenen Bytes eingeschränkt werden. Wenn die Puffergröße nicht ausreicht, um alle Einträge aufzunehmen, gibt die Funktion ERROR_MORE_DATA zurück. Weitere Informationen finden Sie unter Netzwerkverwaltungsfunktionspuffer und Netzwerkverwaltungsfunktionspufferlängen.
[out] entriesread
Ein Zeiger auf einen Wert, der die Anzahl der tatsächlich aufgezählten Elemente empfängt.
[out] totalentries
Ein Zeiger auf einen Wert, der die Gesamtzahl der Einträge empfängt, die hätte aufgezählt werden können.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.
Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes sein.
| Rückgabecode | Beschreibung |
|---|---|
|
Der Benutzer hat keine Zugriffsrechte auf die angeforderten Informationen. Dieser Fehler wird auch zurückgegeben, wenn der Servername-Parameter einen nachfolgenden leeren Wert aufweist. |
|
Die Ebene des Systemaufrufs ist falsch. Dieser Fehler wird zurückgegeben, wenn der level-Parameter nicht als 0 angegeben wurde. |
|
Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn der Flags-Parameter einen anderen Wert als LG_INCLUDE_INDIRECT enthält. |
|
Weitere Einträge sind verfügbar. Geben Sie einen ausreichend großen Puffer an, um alle Einträge zu empfangen. |
|
Es war nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen. |
|
Der Domänencontroller konnte nicht gefunden werden. |
|
Der Benutzer konnte nicht gefunden werden. Dieser Fehler wird zurückgegeben, wenn der Benutzername nicht gefunden werden konnte. |
|
Der RPC-Server ist nicht verfügbar. Dieser Fehler wird zurückgegeben, wenn der Servername-Parameter nicht gefunden werden konnte. |
Hinweise
Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte ADSI-Methoden (Active Directory Service Interface) aufrufen, um die gleiche Funktionalität zu erreichen, die Sie durch Aufrufen der Benutzerfunktionen der Netzwerkverwaltung erreichen können. Weitere Informationen finden Sie unter IADsUser und IADsComputer.
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.
Der Sicherheitsdeskriptor des Domain-Objekts wird verwendet, um die Zugriffsüberprüfung für diese Funktion durchzuführen. Der Aufrufer muss über die Berechtigung Eigenschaft lesen für das Domain-Objekt verfügen.
Um eine Liste der globalen Gruppen abzurufen, zu denen ein angegebener Benutzer gehört, können Sie die NetUserGetGroups-Funktion aufrufen.
Benutzerkontennamen sind auf 20 Zeichen und Gruppennamen auf 256 Zeichen beschränkt. Darüber hinaus können Kontonamen nicht durch einen Punkt beendet werden, und sie dürfen keine Kommas oder eines der folgenden druckbaren Zeichen enthalten: ", /, , [, ], ], :, |, <, , >+, =, ;, ?, *. Namen können auch keine Zeichen im Bereich 1 bis 31 enthalten, die nicht druckbar sind.
Beispiele
Im folgenden Codebeispiel wird veranschaulicht, wie sie mit einem Aufruf der NetUserGetLocalGroups-Funktion eine Liste der lokalen Gruppen abrufen, zu denen ein Benutzer gehört. Im Beispiel wird NetUserGetLocalGroups aufgerufen, wobei die Informationsebene 0 (LOCALGROUP_USERS_INFO_0) angegeben wird. Das Beispiel durchläuft die Einträge und gibt den Namen jeder lokalen Gruppe aus, in der der Benutzer Mitglied ist. Wenn nicht alle verfügbaren Einträge aufgelistet sind, werden auch die Anzahl der tatsächlich aufgezählten Einträge und die Gesamtzahl der verfügbaren Einträge ausgegeben. Schließlich gibt das Codebeispiel den für den Informationspuffer zugeordneten Arbeitsspeicher frei.
#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;
}
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 |