NetWkstaUserEnum-Funktion (lmwksta.h)

Artikel
03/01/2024

Die NetWkstaUserEnum-Funktion listet Informationen zu allen Benutzern auf, die derzeit bei der Arbeitsstation angemeldet sind. Diese Liste enthält interaktive Anmeldungen, Dienst- und Batchanmeldungen.

Syntax

NET_API_STATUS NET_API_FUNCTION NetWkstaUserEnum(
  [in]      LMSTR   servername,
  [in]      DWORD   level,
  [out]     LPBYTE  *bufptr,
  [in]      DWORD   prefmaxlen,
  [out]     LPDWORD entriesread,
  [out]     LPDWORD totalentries,
  [in, out] LPDWORD resumehandle
);

Parameter

[in] servername

Zeiger auf eine 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
0	Gibt die Namen der Benutzer zurück, die derzeit an der Arbeitsstation angemeldet sind. Der parameter bufptr verweist auf ein Array von WKSTA_USER_INFO_0 Strukturen.
1	Gibt die Namen der aktuellen Benutzer und der Domänen zurück, auf die die Arbeitsstation zugreift. Der bufptr-Parameter verweist auf ein Array von WKSTA_USER_INFO_1 Strukturen.

[out] bufptr

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

Gibt die bevorzugte maximale Länge der zurückgegebenen Daten in Bytes an. Wenn Sie MAX_PREFERRED_LENGTH angeben, ordnet die Funktion den für die Daten erforderlichen Arbeitsspeicher zu. Wenn Sie in diesem Parameter einen anderen Wert angeben, kann er die Anzahl der Bytes einschränken, 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

Zeiger auf einen Wert, der die Anzahl der tatsächlich aufgezählten Elemente empfängt.

[out] totalentries

Zeiger auf einen Wert, der die Gesamtzahl der Einträge empfängt, die aus der aktuellen Position des Lebenslaufs hätten aufgezählt werden können. Beachten Sie, dass Anwendungen diesen Wert nur als Hinweis betrachten sollten.

[in, out] resumehandle

Zeiger auf einen Wert, der ein Resume-Handle enthält, das verwendet wird, um eine vorhandene Suche fortzusetzen. Das Handle sollte beim ersten Aufruf null sein und für nachfolgende Aufrufe unverändert bleiben. Wenn dieser Parameter NULL ist, wird kein Resume-Handle gespeichert.

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
ERROR_ACCESS_DENIED	Der Benutzer besitzt keinen Zugriff auf die angeforderten Informationen.
ERROR_MORE_DATA	Weitere Einträge sind verfügbar. Geben Sie einen ausreichend großen Puffer an, um alle Einträge zu empfangen.
ERROR_INVALID_LEVEL	Der level-Parameter ist ungültig.

Hinweise

Da die NetWkstaUserEnum-Funktion Einträge für Dienst- und Batchanmeldungen sowie für interaktive Anmeldungen auflistet, kann die Funktion Einträge für Benutzer zurückgeben, die sich von einer Arbeitsstation abgemeldet haben. Dies kann beispielsweise der Fall sein, wenn ein Benutzer einen Dienst aufruft, der die Identität des Benutzers angibt. In dieser instance gibt NetWkstaUserEnum einen Eintrag für den Benutzer zurück, bis der Dienst den Identitätswechsel des Benutzers beendet.

Windows Server 2003 und Windows XP: Wenn Sie diese Funktion auf einem Domänencontroller aufrufen, auf dem Active Directory ausgeführt wird, wird der Zugriff basierend auf der ACL für das sicherungsfähige Objekt zugelassen oder verweigert. Um den anonymen Zugriff zu aktivieren, muss der Anonyme Benutzer Mitglied der Gruppe "Pre-Windows 2000-kompatibler Zugriff" sein. Dies liegt daran, dass anonyme Token standardmäßig nicht die Gruppen-SID "Jeder" enthalten. Wenn Sie diese Funktion auf einem Mitgliedsserver oder einer Arbeitsstation aufrufen, können alle authentifizierten Benutzer die Informationen anzeigen. Anonymer Zugriff ist auch zulässig, wenn die Richtlinieneinstellung RestrictAnonymous anonymen Zugriff zulässt. Wenn die Richtlinieneinstellung RestrictAnonymous keinen anonymen Zugriff zulässt, kann nur ein Administrator die Funktion erfolgreich ausführen. Mitglieder der Gruppen "Administratoren" und "Server", "System" und "Druckoperator" können auch Informationen anzeigen. Weitere Informationen zum Einschränken des anonymen Zugriffs finden Sie unter Sicherheitsanforderungen für die Netzwerkverwaltungsfunktionen. Weitere Informationen zu ACLs, ACEs und Zugriffstoken finden Sie unter Access Control Modell.

Windows 2000: 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 allen authentifizierten Benutzern und Mitgliedern der Gruppe " Pre-Windows 2000-kompatibler Zugriff" das Anzeigen der Informationen. Standardmäßig enthält die Gruppe "Pre-Windows 2000 compatible access" (Vor Windows 2000 kompatibler Zugriff) alle Benutzer als Mitglied. Dies ermöglicht den anonymen Zugriff auf die Informationen, wenn das System den anonymen Zugriff zulässt. Wenn Sie diese Funktion auf einem Mitgliedsserver oder einer Arbeitsstation aufrufen, können alle authentifizierten Benutzer die Informationen anzeigen. Anonymer Zugriff ist auch zulässig, wenn die Richtlinieneinstellung RestrictAnonymous anonymen Zugriff zulässt.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie das makro _WIN32_WINNT als 0x0400 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Sie Mithilfe eines Aufrufs der NetWkstaUserEnum-Funktion Informationen zu allen Benutzern auflisten, die derzeit bei einer Arbeitsstation angemeldet sind. Im Beispiel wird NetWkstaUserEnum aufgerufen, wobei die Informationsebene 0 ( WKSTA_USER_INFO_0) angegeben wird. Das Beispiel durchläuft die Einträge und gibt die Namen der Benutzer aus, die bei einer Arbeitsstation angemeldet sind. Schließlich gibt das Codebeispiel den für den Informationspuffer zugeordneten Arbeitsspeicher frei und gibt die Gesamtzahl der aufgezählten Benutzer aus.

#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[])
{
   LPWKSTA_USER_INFO_0 pBuf = NULL;
   LPWKSTA_USER_INFO_0 pTmpBuf;
   DWORD dwLevel = 0;
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwResumeHandle = 0;
   DWORD i;
   DWORD dwTotalCount = 0;
   NET_API_STATUS nStatus;
   LPWSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   fwprintf(stderr, L"\nUsers currently logged on %s:\n", pszServerName);
   //
   // Call the NetWkstaUserEnum function, specifying level 0.
   //
   do // begin do
   {
      nStatus = NetWkstaUserEnum( pszServerName,
                                  dwLevel,
                                  (LPBYTE*)&pBuf,
                                  dwPrefMaxLen,
                                  &dwEntriesRead,
                                  &dwTotalEntries,
                                  &dwResumeHandle);
      //
      // If the call succeeds,
      //
      if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
      {
         if ((pTmpBuf = pBuf) != NULL)
         {
            //
            // Loop through the entries.
            //
            for (i = 0; (i < dwEntriesRead); i++)
            {
               assert(pTmpBuf != NULL);

               if (pTmpBuf == NULL)
               {
                  //
                  // Only members of the Administrators local group
                  //  can successfully execute NetWkstaUserEnum
                  //  locally and on a remote server.
                  //
                  fprintf(stderr, "An access violation has occurred\n");
                  break;
               }
               //
               // Print the user logged on to the workstation. 
               //
               wprintf(L"\t-- %s\n", pTmpBuf->wkui0_username);

               pTmpBuf++;
               dwTotalCount++;
            }
         }
      }
      //
      // Otherwise, indicate a system error.
      //
      else
         fprintf(stderr, "A system error has occurred: %d\n", nStatus);
      //
      // Free the allocated memory.
      //
      if (pBuf != NULL)
      {
         NetApiBufferFree(pBuf);
         pBuf = NULL;
      }
   }
   // 
   // Continue to call NetWkstaUserEnum while 
   //  there are more entries. 
   // 
   while (nStatus == ERROR_MORE_DATA); // end do
   //
   // Check again for allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);
   //
   // Print the final count of workstation users.
   //
   fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);

   return 0;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	lmwksta.h (lm.h einschließen)
Bibliothek	Netapi32.lib
DLL	Netapi32.dll