NetServerTransportEnum 函数 (lmserver.h)

项目
02/28/2024

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

指定数据的信息级别。此参数的取值可为下列值之一：

值	含义
0	返回有关传输协议的信息，包括网络上的名称、地址和位置。 bufptr 参数指向SERVER_TRANSPORT_INFO_0结构的数组。
1	返回有关传输协议的信息，包括名称、地址、网络位置和域。 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。

如果函数失败，则返回值可能是以下错误代码之一。

返回代码	说明
ERROR_INVALID_LEVEL	为级别参数指定的值无效。
ERROR_MORE_DATA	有更多条目可用。指定一个足够大的缓冲区来接收所有条目。
ERROR_NOT_ENOUGH_MEMORY	可用内存不足。
NERR_BufTooSmall	提供的缓冲区太小。

注解

只有经过身份验证的用户才能成功调用此函数。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