Функция NetSessionEnum (lmshare.h)
Предоставляет сведения о сеансах, установленных на сервере.
Синтаксис
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
Задает уровень информации данных. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Возвращает имя компьютера, на который был установлен сеанс. Параметр bufptr указывает на массив SESSION_INFO_0 структур. |
|
Возвращает имя компьютера, имя пользователя и открытые файлы, каналы и устройства на компьютере. Параметр bufptr указывает на массив SESSION_INFO_1 структур. |
|
В дополнение к сведениям, указанным для уровня 1, возвращается тип клиента и способ установки сеанса пользователем. Параметр bufptr указывает на массив SESSION_INFO_2 структур. |
|
Возвращает имя компьютера, имя пользователя, а также время активного и простоя сеанса. Параметр bufptr указывает на массив SESSION_INFO_10 структур. |
|
Возвращает имя компьютера; имя пользователя; открывать файлы, каналы и устройства на компьютере; и имя транспорта, используемого клиентом. Параметр 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.
Если функция завершается ошибкой, возвращаемое значение может быть одним из следующих кодов ошибок.
| Код возврата | Описание |
|---|---|
|
Пользователь не имеет доступа к запрошенной информации. |
|
Недопустимое значение, указанное для параметра level . |
|
Указанный параметр недопустим. |
|
Доступны дополнительные записи. Укажите достаточно большой буфер для получения всех записей. |
|
Недостаточно памяти. |
|
Сеанс с именем компьютера не существует. |
|
Недопустимое имя компьютера. |
|
Не удалось найти имя пользователя. |
Комментарии
Только члены локальной группы "Администраторы" или "Операторы сервера" могут успешно выполнять функцию NetSessionEnum на уровне 1 или 2.
При программировании для 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 |