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
);
parameters
[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
指向接收数据的缓冲区的指针。 此数据的格式取决于 级别 参数的值。
此缓冲区由系统分配，必须使用 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。
如果函数失败，则返回值可能是以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
用户无权访问请求的信息。 |
|
为 级别 参数指定的值无效。 |
|
指定的参数无效。 |
|
有更多条目可用。 指定一个足够大的缓冲区来接收所有条目。 |
|
可用内存不足。 |
|
不存在具有计算机名称的会话。 |
|
计算机名无效。 |
|
找不到用户名。 |
注解
只有管理员或服务器操作员本地组的成员才能在级别 1 或级别 2 上成功执行 NetSessionEnum 函数。
如果要对 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 |
| 标头 | lmshare.h (包括 Lm.h) |
| Library | Netapi32.lib |
| DLL | Netapi32.dll |