NetUserGetGroups-Funktion (lmaccess.h)
Die NetUserGetGroups-Funktion ruft eine Liste globaler Gruppen ab, zu denen ein angegebener Benutzer gehört.
Syntax
NET_API_STATUS NET_API_FUNCTION NetUserGetGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[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, nach dem in jedem Gruppenkonto gesucht werden soll. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[in] level
Die Informationsebene der angeforderten Daten. Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
|
Gibt die Namen der globalen Gruppen zurück, zu denen der Benutzer gehört. Der bufptr-Parameter verweist auf ein Array von GROUP_USERS_INFO_0 Strukturen. |
|
Gibt die Namen der globalen Gruppen, zu denen der Benutzer gehört, mit Attributen zurück. Der bufptr-Parameter verweist auf ein Array von GROUP_USERS_INFO_1 Strukturen. |
[out] bufptr
Ein Zeiger auf den Puffer, der die Daten empfängt. Dieser Puffer wird vom System zugewiesen 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 MAX_PREFERRED_LENGTH angegeben ist, ordnet die Funktion den für die Daten erforderlichen Arbeitsspeicher zu. Wenn in diesem Parameter ein anderer Wert angegeben wird, kann die Anzahl von Bytes eingeschränkt werden, die die Funktion zurückgibt. 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 abgerufenen Elemente empfängt.
[out] totalentries
Ein Zeiger auf einen Wert, der die Gesamtzahl der Einträge empfängt, die abgerufen 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. |
|
Der Netzwerkpfad wurde nicht gefunden.“ Dieser Fehler wird zurückgegeben, wenn der Parameter servername nicht gefunden wurde. |
|
Die Ebene des Systemaufrufs ist falsch. Dieser Fehler wird zurückgegeben, wenn der Levelparameter als anderer Wert als 0 oder 1 angegeben wurde. |
|
Die Namenssyntax ist falsch. Dieser Fehler wird zurückgegeben, wenn der Servername-Parameter führende oder nachfolgende Leerzeichen enthält oder ein ungültiges Zeichen enthält. |
|
Weitere Einträge sind verfügbar. Geben Sie einen ausreichend großen Puffer an, um alle Einträge zu empfangen. |
|
Zum Abschließen des Vorgangs war nicht genügend Arbeitsspeicher verfügbar. |
|
Interner Fehler. |
|
Der Benutzer konnte nicht gefunden werden. Dieser Fehler wird zurückgegeben, wenn der Benutzername 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 dieselbe Funktionalität zu erzielen, die Sie durch aufrufen der Netzwerkverwaltungsbenutzerfunktionen 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.
Die Sicherheitsbeschreibung des User-Objekts wird verwendet, um die Zugriffsprüfung für diese Funktion durchzuführen.
Um eine Liste der lokalen Gruppen abzurufen, zu denen ein Benutzer gehört, können Sie die NetUserGetLocalGroups-Funktion aufrufen. Netzwerkgruppen sind getrennt und unterscheiden sich von Windows NT-Systemgruppen.
Benutzerkontonamen sind auf 20 Zeichen und Gruppennamen auf 256 Zeichen beschränkt. Darüber hinaus können Kontonamen nicht durch einen Punkt beendet werden und dürfen keine Kommas oder eines der folgenden druckbaren Zeichen enthalten: ", /, , [, ], :, |, <, , >, +, =, ;, ?, *. Namen dürfen auch keine Zeichen im Bereich 1-31 enthalten, die nicht druckbar sind.
Beispiele
Im folgenden Codebeispiel wird veranschaulicht, wie sie mit einem Aufruf der NetUserGetGroups-Funktion eine Liste globaler Gruppen abrufen, zu denen ein Benutzer gehört. Im Beispiel wird NetUserGetGroups aufgerufen, wobei die Informationsebene 0 (GROUP_USERS_INFO_0) angegeben wird. Der Code durchläuft die Einträge und gibt den Namen der globalen Gruppen aus, in denen der Benutzer Mitglied ist. Das Beispiel gibt auch die Gesamtzahl der verfügbaren Einträge und die Anzahl der tatsächlich aufgelisteten Einträge an, wenn sie nicht übereinstimmen. Schließlich gibt das Codebeispiel den für den Puffer zugewiesenen 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[])
{
LPGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
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 NetUserGetGroups function, specifying level 0.
//
nStatus = NetUserGetGroups(argv[1],
argv[2],
dwLevel,
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nGlobal group(s):\n");
//
// Loop through the entries;
// print the name of the global 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->grui0_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 buffer.
//
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 |