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.

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

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

Weitere Informationen

GROUP_USERS_INFO_0

GROUP_USERS_INFO_1

NetGroupGetUsers

NetQueryDisplayInformation

NetUserGetInfo

NetUserGetLocalGroups

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung

Benutzerfunktionen