NetWkstaUserEnum 函数 (lmwksta.h)

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

指向接收数据的缓冲区的指针。 此数据的格式取决于 级别 参数的值。 此缓冲区由系统分配,必须使用 NetApiBufferFree 函数释放。 请注意,即使函数因ERROR_MORE_DATA而失败,也必须释放缓冲区。

[in] prefmaxlen

指定返回数据的首选最大长度(以字节为单位)。 如果指定MAX_PREFERRED_LENGTH,函数将分配数据所需的内存量。 如果在此参数中指定另一个值,它可以限制函数返回的字节数。 如果缓冲区大小不足以容纳所有条目,则函数将返回ERROR_MORE_DATA。 有关详细信息,请参阅 网络管理功能缓冲区网络管理功能缓冲区长度

[out] entriesread

指向一个值的指针,该值接收实际枚举的元素计数。

[out] totalentries

指向一个值的指针,该值接收可能从当前恢复位置枚举的条目总数。 请注意,应用程序应仅将此值视为提示。

[in, out] resumehandle

指向包含用于继续现有搜索的恢复句柄的值的指针。 第一次调用时,句柄应为零,后续调用应保持不变。 如果此参数为 NULL,则不存储任何恢复句柄。

返回值

如果函数成功,则返回值NERR_Success。

如果函数失败,则返回值可能是以下错误代码之一。

返回代码 说明
ERROR_ACCESS_DENIED
用户无权访问请求的信息。
ERROR_MORE_DATA
有更多条目可用。 指定一个足够大的缓冲区来接收所有条目。
ERROR_INVALID_LEVEL
级别参数无效。

注解

请注意,由于 NetWkstaUserEnum 函数列出了服务和批量登录以及交互式登录的条目,因此该函数可以为已注销工作站的用户返回条目。 例如,当用户调用模拟用户的服务时,可能会发生这种情况。 在此实例中, NetWkstaUserEnum 为用户返回一个条目,直到服务停止模拟用户为止。

Windows Server 2003 和 Windows XP: 如果在运行 Active Directory 的域控制器上调用此函数,则会根据安全对象的 ACL 允许或拒绝访问。 若要启用匿名访问,匿名用户必须是“Windows 2000 前兼容访问”组的成员。 这是因为默认情况下,匿名令牌不包括 Everyone 组 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 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 lmwksta.h (包括 Lm.h)
Library Netapi32.lib
DLL Netapi32.dll

另请参阅

NetWkstaGetInfo

NetWkstaSetInfo

网络管理功能

网络管理概述

WKSTA_USER_INFO_0

WKSTA_USER_INFO_1

工作站和工作站用户函数