Функция NetWkstaUserEnum (lmwksta.h)

Статья
03/14/2023

Функция 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.

Если функция завершается сбоем, возвращаемое значение может быть одним из следующих кодов ошибок.

Код возврата	Описание
ERROR_ACCESS_DENIED	У пользователя нет доступа к запрошенной информации.
ERROR_MORE_DATA	Доступны дополнительные записи. Укажите достаточно большой буфер для получения всех записей.
ERROR_INVALID_LEVEL	Недопустимый параметр level .

Обратите внимание, что так как функция NetWkstaUserEnum перечисляет записи для входа в службу и пакет, а также для интерактивных входов, функция может возвращать записи для пользователей, которые вышли из рабочей станции. Это может произойти, например, когда пользователь вызывает службу, которая олицетворяет пользователя. В этом экземпляре NetWkstaUserEnum возвращает запись для пользователя, пока служба не прекратит олицетворение пользователя.

Windows Server 2003 и Windows XP: Если вы вызываете эту функцию на контроллере домена под управлением Active Directory, доступ разрешен или запрещен на основе списка управления доступом для защищаемого объекта. Чтобы включить анонимный доступ, пользователь Anonymous должен входить в группу "Доступ, совместимый с Windows 2000". Это связано с тем, что анонимные маркеры по умолчанию не включают идентификатор безопасности группы "Все". Если вы вызываете эту функцию на рядовом сервере или рабочей станции, все пользователи, прошедшие проверку подлинности, смогут просматривать сведения. Анонимный доступ также разрешен, если параметр политики RestrictAnonymous разрешает анонимный доступ. Если параметр политики RestrictAnonymous не разрешает анонимный доступ, только администратор может успешно выполнить функцию. Члены локальных групп "Администраторы", "Сервер", "Системный" и "Оператор печати" также могут просматривать сведения. Дополнительные сведения об ограничении анонимного доступа см. в разделе Требования к безопасности для функций управления сетью. Дополнительные сведения о списках управления доступом, ACE и маркерах доступа см. в разделе модель контроль доступа.

Windows 2000: Если вы вызываете эту функцию на контроллере домена под управлением Active Directory, доступ разрешен или запрещен на основе списка управления доступом (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
Header	lmwksta.h (включая Lm.h)
Библиотека	Netapi32.lib
DLL	Netapi32.dll