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.

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

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

Weitere Informationen

LOCALGROUP_USERS_INFO_0

NetUserGetGroups

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung

Benutzerfunktionen