Функция 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	Не удалось найти имя пользователя.

При программировании для 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
Header	lmshare.h (включая Lm.h)
Библиотека	Netapi32.lib
DLL	Netapi32.dll