NetServerTransportEnum 函数 (lmserver.h)
NetServerTransportEnum 函数提供有关由服务器管理的传输协议的信息。
语法
NET_API_STATUS NET_API_FUNCTION NetServerTransportEnum(
[in] LMSTR servername,
[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] level
指定数据的信息级别。 此参数的取值可为下列值之一:
值 | 含义 |
---|---|
|
返回有关传输协议的信息,包括网络上的名称、地址和位置。 bufptr 参数指向SERVER_TRANSPORT_INFO_0结构的数组。 |
|
返回有关传输协议的信息,包括名称、地址、网络位置和域。 bufptr 参数指向SERVER_TRANSPORT_INFO_1结构的数组。 |
[out] bufptr
指向接收数据的缓冲区的指针。 此数据的格式取决于 级别 参数的值。 此缓冲区由系统分配,必须使用 NetApiBufferFree 函数释放。 请注意,即使函数失败并出现ERROR_MORE_DATA,也必须释放缓冲区。
[in] prefmaxlen
指定返回数据的首选最大长度(以字节为单位)。 如果指定MAX_PREFERRED_LENGTH,函数将分配数据所需的内存量。 如果在此参数中指定另一个值,它可以限制函数返回的字节数。 如果缓冲区大小不足以容纳所有条目,则函数将返回ERROR_MORE_DATA。 有关详细信息,请参阅 网络管理功能缓冲区 和 网络管理功能缓冲区长度。
[out] entriesread
指向接收实际枚举的元素计数的值的指针。
[out] totalentries
指向一个值的指针,该值接收可能从当前恢复位置枚举的条目总数。 请注意,应用程序应仅将此值视为提示。
[in, out] resume_handle
指向包含用于继续现有服务器传输搜索的恢复句柄的值的指针。 第一次调用时,句柄应为零,后续调用应保持不变。 如果此参数为 NULL,则不存储任何恢复句柄。
返回值
如果函数成功,则返回值NERR_Success。
如果函数失败,则返回值可能是以下错误代码之一。
返回代码 | 说明 |
---|---|
|
为 级别 参数指定的值无效。 |
|
有更多条目可用。 指定一个足够大的缓冲区来接收所有条目。 |
|
可用内存不足。 |
|
提供的缓冲区太小。 |
注解
只有经过身份验证的用户才能成功调用此函数。Windows XP/2000: 成功执行此函数不需要任何特殊组成员身份。
示例
下面的代码示例演示如何使用对 NetServerTransportEnum 函数的调用来检索有关服务器管理的传输协议的信息。 此示例调用 NetServerTransportEnum,将信息级别指定为 0 ( SERVER_TRANSPORT_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[])
{
LPSERVER_TRANSPORT_INFO_0 pBuf = NULL;
LPSERVER_TRANSPORT_INFO_0 pTmpBuf;
DWORD dwLevel = 0;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwResumeHandle = 0;
DWORD dwTotalCount = 0;
NET_API_STATUS nStatus;
LPTSTR pszServerName = NULL;
DWORD i;
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 = (LPTSTR) argv[1];
//
// Call the NetServerTransportEnum function; specify level 0.
//
do // begin do
{
nStatus = NetServerTransportEnum(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;
// process access errors.
//
for (i = 0; i < dwEntriesRead; i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
//
// Print the transport protocol name.
//
wprintf(L"\tTransport: %s\n", pTmpBuf->svti0_transportname);
pTmpBuf++;
dwTotalCount++;
}
}
}
//
// Otherwise, indicate a system error.
//
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
{
NetApiBufferFree(pBuf);
pBuf = NULL;
}
//
// Continue to call NetServerTransportEnum 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 transports enumerated.
//
fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);
return 0;
}
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
目标平台 | Windows |
标头 | lmserver.h (包括 Lm.h) |
Library | Netapi32.lib |
DLL | Netapi32.dll |