NetSessionEnum 函式 (lmshare.h)

發行項
03/14/2023

提供伺服器上建立之會話的相關資訊。

語法

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

參數

[in] servername

字串的指標，指定函式執行所在遠端伺服器的 DNS 或 NetBIOS 名稱。如果此參數為 Null，則會使用本機電腦。

[in] UncClientName

字串的指標，指定要傳回信息的電腦會話名稱。如果此參數為 Null， NetSessionEnum 會傳回伺服器上所有電腦會話的資訊。

[in] username

字串的指標，指定要傳回信息的使用者名稱。如果此參數為 Null， NetSessionEnum 會傳回所有使用者的資訊。

[in] level

指定資料的資訊層級。此參數可以是下列其中一個值。

值	意義
0	傳回建立會話的電腦名稱稱。 bufptr參數指向SESSION_INFO_0結構的陣列。
1	傳回電腦的名稱、使用者名稱，以及開啟電腦上的檔案、管道和裝置。 bufptr參數指向SESSION_INFO_1結構的陣列。
2	除了層級 1 所指出的資訊之外，還傳回用戶端的類型，以及使用者建立會話的方式。 bufptr參數指向SESSION_INFO_2結構的陣列。
10	傳回電腦的名稱、使用者的名稱，以及會話的作用中和閒置時間。 bufptr參數指向SESSION_INFO_10結構的陣列。
502	傳回電腦的名稱;使用者的名稱;開啟電腦上的檔案、管道和裝置;以及用戶端正在使用的傳輸名稱。 bufptr參數指向SESSION_INFO_502結構的陣列。

[out] bufptr

接收資料的緩衝區指標。此資料的格式取決於 level 參數的值。

此緩衝區是由系統所配置，而且必須使用 NetApiBufferFree 函式釋放。請注意，即使函式失敗 且ERROR_MORE_DATA，您也必須釋放緩衝區。

[in] prefmaxlen

指定所傳回資料的慣用最大長度，以位元組為單位。如果您指定 MAX_PREFERRED_LENGTH，函式會配置資料所需的記憶體數量。如果您在此參數中指定另一個值，它可以限制函式傳回的位元組數目。如果緩衝區大小不足而無法保存所有專案，函式會傳回 ERROR_MORE_DATA。如需詳細資訊，請參閱網路管理功能緩衝區和網路管理功能緩衝區長度。

[out] entriesread

值指標，這個值會接收實際列舉的專案計數。

[out] totalentries

值的指標，這個值會接收可能已從目前繼續位置列舉的專案總數。請注意，應用程式應該只將此值視為提示。

[in, out] resume_handle

值的指標，其中包含用來繼續現有會話搜尋的繼續控制碼。第一次呼叫時，控制碼應該是零，後續呼叫則保持不變。如果 resume_handle 為 Null，則不會儲存任何繼續控制碼。

傳回值

如果函式成功，傳回值 會NERR_Success。

如果函式失敗，傳回值可以是下列其中一個錯誤碼。

傳回碼	描述
ERROR_ACCESS_DENIED	使用者無法存取要求的資訊。
ERROR_INVALID_LEVEL	為 level 參數指定的值無效。
ERROR_INVALID_PARAMETER	指定的參數無效。
ERROR_MORE_DATA	有更多專案可供使用。指定足夠的緩衝區來接收所有專案。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足。
NERR_ClientNameNotFound	會話不存在於電腦名稱稱中。
NERR_InvalidComputer	電腦名稱稱無效。
NERR_UserNotFound	找不到使用者名稱。

備註

只有系統管理員或伺服器操作員本機群組的成員才能在層級 1 或層級 2 成功執行 NetSessionEnum 函式。

如果您是針對 Active Directory 進行程式設計，您可以呼叫特定 Active Directory 服務介面 (ADSI) 方法來達成相同的功能，方法是呼叫網路管理會話函式。如需詳細資訊，請參閱 IADsSession 和 IADsFileServiceOperations。

範例

下列程式碼範例示範如何使用 對 NetSessionEnum 函式的呼叫來擷取目前會話的相關資訊。此範例會呼叫 NetSessionEnum，並指定資訊層級 10 ( SESSION_INFO_10) 。範例會迴圈查看專案，並列印擷取的資訊。最後，程式碼會列印列舉的會話總數，並釋放配置給資訊緩衝區的記憶體。

#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;
}

需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	lmshare.h (包括 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll