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.

[out] bufptr

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

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

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

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

[out] totalentries

Zeiger auf einen Wert, der die Gesamtanzahl von Einträgen empfängt, die aus der aktuellen Fortsetzenposition aufgezählt worden sein könnten. Beachten Sie, dass Anwendungen diesen Wert nur als Hinweis betrachten sollten.

[in, out] resume_handle

Zeiger auf einen Wert, der ein Resume-Handle enthält, das verwendet wird, um eine vorhandene Sitzungssuche fortzusetzen. Das Handle sollte beim ersten Aufruf 0 sein und für nachfolgende Aufrufe unverändert bleiben. Wenn resume_handleNULL 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.

Hinweise

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 ADSI-Methoden (Active Directory Service Interface) aufrufen, um dieselbe Funktionalität zu erzielen, die Sie durch aufrufen der Netzwerkverwaltungssitzungsfunktionen erreichen können. Weitere Informationen finden Sie unter IADsSession und IADsFileServiceOperations.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Sie Mithilfe eines Aufrufs der NetSessionEnum-Funktion Informationen zu aktuellen Sitzungen abrufen. Im Beispiel wird NetSessionEnum aufgerufen, wobei die Informationsebene 10 (SESSION_INFO_10) angegeben wird. Das Beispiel durchläuft die Einträge und gibt die abgerufenen Informationen aus. Schließlich gibt der Code die Gesamtzahl der aufgezählten Sitzungen aus und gibt den für den Informationspuffer 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[])
{
   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

Weitere Informationen

NetSessionGetInfo

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung

SESSION_INFO_0

SESSION_INFO_1

SESSION_INFO_10

SESSION_INFO_2

SESSION_INFO_502

Sitzungsfunktionen