NetSessionEnum-Funktion (lmshare.h)

Stellt Informationen zu Sitzungen bereit, die auf einem Server eingerichtet wurden.

Syntax

NET_API_STATUS NET_API_FUNCTION NetSessionEnum(
  [in]      LMSTR   servername,
  [in]      LMSTR   UncClientName,
  [in]      LMSTR   username,
  [in]      DWORD   level,
  [out]     LPBYTE  *bufptr,
  [in]      DWORD   prefmaxlen,
  [out]     LPDWORD entriesread,
  [out]     LPDWORD totalentries,
  [in, out] LPDWORD resume_handle
);

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] UncClientName

Zeiger auf eine Zeichenfolge, die den Namen der Computersitzung angibt, für die Informationen zurückgegeben werden sollen. Wenn dieser Parameter NULL ist, gibt NetSessionEnum Informationen für alle Computersitzungen auf dem Server zurück.

[in] username

Zeiger auf eine Zeichenfolge, die den Namen des Benutzers angibt, für den Informationen zurückgegeben werden sollen. Wenn dieser Parameter NULL ist, gibt NetSessionEnum Informationen für alle Benutzer zurück.

[in] level

Gibt die Informationsebene der Daten an. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert Bedeutung
0
Geben Sie den Namen des Computers zurück, auf dem die Sitzung eingerichtet wurde. Der Bufptr-Parameter verweist auf ein Array von SESSION_INFO_0 Strukturen.
1
Geben Sie den Namen des Computers, den Namen des Benutzers zurück, und öffnen Sie Dateien, Rohre und Geräte auf dem Computer. Der Bufptr-Parameter verweist auf ein Array von SESSION_INFO_1 Strukturen.
2
Geben Sie zusätzlich zu den informationen, die für Ebene 1 angegeben sind, den Clienttyp und die Art der Einrichtung der Sitzung zurück. Der Bufptr-Parameter verweist auf ein Array von SESSION_INFO_2 Strukturen.
10
Geben Sie den Namen des Computers, den Namen des Benutzers und aktive und leerlaufzeiten für die Sitzung zurück. Der Bufptr-Parameter verweist auf ein Array von SESSION_INFO_10 Strukturen.
502
Geben Sie den Namen des Computers zurück; Name des Benutzers; Öffnen sie Dateien, Rohre und Geräte auf dem Computer; und der Name des Transports, den der Client verwendet. Der Bufptr-Parameter verweist auf ein Array von SESSION_INFO_502 Strukturen.

[out] bufptr

Zeiger auf den Puffer, der die Daten empfängt. Das Format dieser Daten hängt vom Wert des Levelparameters ab.

Dieser Puffer wird vom System zugewiesen und muss mithilfe der NetApiBufferFree-Funktion freigegeben werden. Beachten Sie, dass Sie den Puffer freigeben müssen, auch 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, weist die Funktion die für die Daten erforderliche Speichermenge zu. Wenn Sie einen anderen Wert in diesem Parameter angeben, kann sie die Anzahl der Bytes einschränken, die die Funktion zurückgibt. Wenn die Puffergröße nicht ausreicht, um alle Einträge zu speichern, gibt die Funktion ERROR_MORE_DATA zurück. Weitere Informationen finden Sie unter Network Management Function Buffers and Network Management Function Buffers.

[out] entriesread

Zeiger auf einen Wert, der die Anzahl der Elemente erhält, die tatsächlich aufgezählt wurden.

[out] totalentries

Zeiger auf einen Wert, der die Gesamtanzahl der Einträge empfängt, die aus der aktuellen Lebenslaufposition aufgezählt werden konnten. Beachten Sie, dass Anwendungen diesen Wert nur als Hinweis betrachten sollten.

[in, out] resume_handle

Zeiger auf einen Wert, der einen Lebenslaufhandpunkt enthält, der verwendet wird, um eine vorhandene Sitzungssuche fortzusetzen. Der Handle sollte für den ersten Anruf null sein und für nachfolgende Anrufe unverändert bleiben. Wenn resume_handleNULL ist, wird kein Lebenslaufhandpunkt gespeichert.

Rückgabewert

Wenn die Funktion erfolgreich verläuft, 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 hat keinen Zugriff auf die angeforderten Informationen.
ERROR_INVALID_LEVEL
Der für den Levelparameter angegebene Wert ist ungültig.
ERROR_INVALID_PARAMETER
Der angegebene Parameter ist ungültig.
ERROR_MORE_DATA
Weitere Einträge sind verfügbar. Geben Sie einen großen Puffer an, um alle Einträge zu empfangen.
ERROR_NOT_ENOUGH_MEMORY
Unzureichender Arbeitsspeicher ist verfügbar.
NERR_ClientNameNotFound
Eine Sitzung ist nicht mit dem Computernamen vorhanden.
NERR_InvalidComputer
Der Computername ist ungültig.
NERR_UserNotFound
Der Benutzername konnte nicht gefunden werden.

Bemerkungen

Nur Mitglieder der lokalen Gruppe "Administratoren" oder "Serveroperatoren" können die NetSessionEnum-Funktion auf Ebene 1 oder Ebene 2 erfolgreich ausführen.

Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte Active Directory Service Interface (ADSI)-Methoden aufrufen, um dieselbe Funktionalität zu erzielen, die Sie erreichen können, indem Sie die Netzwerkverwaltungssitzungsfunktionen aufrufen. Weitere Informationen finden Sie unter IADsSession and IADsFileServiceOperations.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Informationen zu aktuellen Sitzungen mithilfe eines Aufrufs der NetSessionEnum-Funktion abgerufen werden. Das Beispiel ruft NetSessionEnum auf, wobei die Informationsstufe 10 ( SESSION_INFO_10) angegeben wird. Das Beispiel durchläuft die Einträge und druckt die abgerufenen Informationen. Schließlich druckt der Code die Gesamtanzahl der aufgezählten Sitzungen und gibt den für den Informationspuffer zugewiesenen Speicher 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[])
{
   LPSESSION_INFO_10 pBuf = NULL;
   LPSESSION_INFO_10 pTmpBuf;
   DWORD dwLevel = 10;
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwResumeHandle = 0;
   DWORD i;
   DWORD dwTotalCount = 0;
   LPTSTR pszServerName = NULL;
   LPTSTR pszClientName = NULL;
   LPTSTR pszUserName = NULL;
   NET_API_STATUS nStatus;
   //
   // Check command line arguments.
   //
   if (argc > 4)
   {
      wprintf(L"Usage: %s [\\\\ServerName] [\\\\ClientName] [UserName]\n", argv[0]);
      exit(1);
   }

   if (argc >= 2)
      pszServerName = argv[1];

   if (argc >= 3)
      pszClientName = argv[2];

   if (argc == 4)
      pszUserName = argv[3];
   //
   // Call the NetSessionEnum function, specifying level 10.
   //
   do // begin do
   {
      nStatus = NetSessionEnum(pszServerName,
                               pszClientName,
                               pszUserName,
                               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)
               {
                  fprintf(stderr, "An access violation has occurred\n");
                  break;
               }
               //
               // Print the retrieved data. 
               //
               wprintf(L"\n\tClient: %s\n", pTmpBuf->sesi10_cname);
               wprintf(L"\tUser:   %s\n", pTmpBuf->sesi10_username);
               printf("\tActive: %d\n", pTmpBuf->sesi10_time);
               printf("\tIdle:   %d\n", pTmpBuf->sesi10_idle_time);

               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 NetSessionEnum while 
   //  there are more entries. 
   // 
   while (nStatus == ERROR_MORE_DATA); // end do

   // Check again for an allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);
   //
   // Print the final count of sessions enumerated.
   //
   fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);

   return 0;
}

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP [Nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Nur Desktop-Apps]
Zielplattform Windows
Kopfzeile lmshare.h (include Lm.h)
Bibliothek Netapi32.lib
DLL Netapi32.dll

Weitere Informationen

NetSessionGetInfo

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung

SESSION_INFO_0

SESSION_INFO_1

SESSION_INFO_10

SESSION_INFO_2

SESSION_INFO_502

Sitzungsfunktionen