NetWkstaUserEnum 函式 (lmwksta.h)

發行項
02/28/2024

NetWkstaUserEnum 函式會列出目前登入工作站之所有用戶的相關信息。此清單包含互動式、服務和批次登入。

語法

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

參數

[in] servername

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

[in] level

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

值	意義
0	傳回目前登入工作站的用戶名稱。 bufptr 參數指向WKSTA_USER_INFO_0結構的陣列。
1	傳回工作站存取之目前用戶和網域的名稱。 bufptr 參數指向WKSTA_USER_INFO_1結構的陣列。

[out] bufptr

接收數據的緩衝區指標。此數據的格式取決於 level 參數的值。此緩衝區是由系統所配置，而且必須使用 NetApiBufferFree 函式釋放。請注意，即使函式因ERROR_MORE_DATA而失敗，您也必須釋放緩衝區。

[in] prefmaxlen

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

[out] entriesread

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

[out] totalentries

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

[in, out] resumehandle

值的指標，其中包含用來繼續現有搜尋的繼續句柄。第一次呼叫時，句柄應該是零，後續呼叫則保持不變。如果此參數為 NULL，則不會儲存任何繼續句柄。

傳回值

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

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

傳回碼	Description
ERROR_ACCESS_DENIED	用戶無法存取要求的資訊。
ERROR_MORE_DATA	有更多專案可供使用。指定足夠的緩衝區來接收所有專案。
ERROR_INVALID_LEVEL	level 參數無效。

備註

請注意，由於 NetWkstaUserEnum 函式會列出服務和批次登入的專案，以及用於互動式登錄，因此函式可以傳回已註銷工作站的用戶專案。例如，當使用者呼叫模擬用戶的服務時，可能會發生這種情況。在此實例中， NetWkstaUserEnum 會傳回用戶的專案，直到服務停止模擬用戶為止。

Windows Server 2003 和 Windows XP： 如果您在執行 Active Directory 的域控制器上呼叫此函式，則會根據安全性實體物件的 ACL 來允許或拒絕存取。若要啟用匿名存取，使用者 Anonymous 必須是「Windows 2000 前相容存取」群組的成員。這是因為匿名令牌預設不包含所有人群組 SID。如果您在成員伺服器或工作站上呼叫此函式，所有已驗證的使用者都可以檢視資訊。如果 RestrictAnonymous 原則設定允許匿名存取，也允許匿名存取。如果 RestrictAnonymous 原則設定不允許匿名存取，則只有系統管理員可以成功執行函式。系統管理員和伺服器、系統和列印操作員本地組的成員也可以檢視資訊。如需限制匿名存取的詳細資訊，請參閱網路管理功能的安全性需求。如需 ACL、ACE 和存取令牌的詳細資訊，請參閱存取控制模型。

Windows 2000： 如果您在執行 Active Directory 的域控制器上呼叫此函式，則會根據安全性實體對象的訪問控制清單 (ACL) ，允許或拒絕存取。默認 ACL 允許所有已驗證的使用者和「 Windows 2000 相容存取」群組的成員檢視資訊。根據預設，「Windows 2000 前相容存取」群組包含「所有人」作為成員。如果系統允許匿名存取，這可讓匿名存取資訊。如果您在成員伺服器或工作站上呼叫此函式，所有已驗證的使用者都可以檢視資訊。如果 RestrictAnonymous 原則設定允許匿名存取，也允許匿名存取。

若要編譯使用此函式的應用程式，請將_WIN32_WINNT宏定義為0x0400或更新版本。如需詳細資訊，請參閱使用 Windows 標頭。

範例

下列程式代碼範例示範如何使用 NetWkstaUserEnum 函式呼叫，列出目前登入工作站之所有使用者的相關信息。此範例會呼叫 NetWkstaUserEnum，並指定資訊層級 0 ( WKSTA_USER_INFO_0) 。此範例會迴圈查看專案，並列印登入工作站的用戶名稱。最後，程式代碼範例會釋放配置給資訊緩衝區的記憶體，並列印列舉的用戶總數。

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	lmwksta.h (include Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll