NetConnectionEnum 函数 (lmshare.h)

项目
08/24/2023

列出与服务器上的共享资源建立的所有连接或从特定计算机建立的所有连接。如果有多个用户使用此连接，则可以为同一连接获取多个结构，但具有不同的用户名。

语法

NET_API_STATUS NET_API_FUNCTION NetConnectionEnum(
  [in]      LMSTR   servername,
  [in]      LMSTR   qualifier,
  [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，则使用本地计算机。

如果定义了 _WIN32_WINNT 或 FORCE_UNICODE ，则此字符串为 Unicode。

[in] qualifier

指向字符串的指针，该字符串指定相关连接的共享名称或计算机名称。如果它是共享名称，则会列出与该共享名称建立的所有连接。例如，如果它是计算机名称 (，则它以两个反斜杠字符) 开头， NetConnectionEnum 会列出从该计算机到指定服务器的所有连接。

如果定义了 _WIN32_WINNT 或 FORCE_UNICODE ，则此字符串为 Unicode。

[in] level

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

值	含义
0	返回连接标识符。 bufptr 参数是指向CONNECTION_INFO_0结构的数组的指针。
1	返回连接标识符和连接信息。 bufptr 参数是指向CONNECTION_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。

如果函数失败，则返回值为系统错误代码。有关错误代码的列表，请参阅系统错误代码。

注解

需要管理员、服务器或打印操作员或 Power 用户组成员身份才能成功执行 NetConnectionEnum 函数。

示例

以下代码示例演示如何通过调用 NetConnectionEnum 函数列出与共享资源建立的连接。此示例调用 NetConnectionEnum，指定信息级别 1 (CONNECTION_INFO_1) 。如果有要返回的条目，它将打印 coni1_username 和 coni1_netname 成员的值。如果没有要返回的条目，该示例将打印相应的消息。最后，代码示例释放为信息缓冲区分配的内存。

#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <lm.h>
#include <stdio.h>
#pragma comment(lib, "Netapi32.lib")

void wmain(int argc, wchar_t *argv[ ])
{
   DWORD res, i, er = 0, tr = 0, resume = 0;
   PCONNECTION_INFO_1 p,b;
   LPTSTR lpszServer = NULL, lpszShare = NULL;

   if(argc<2)
      wprintf(L"Syntax: %s [ServerName] ShareName | \\\\ComputerName\n", argv[0]);
   else
   {
      //
      // The server is not the default local computer.
      //
      if(argc>2)
         lpszServer=argv[1];
      //
      // ShareName is always the last argument.
      //
      lpszShare=argv[argc - 1];
      //
      // Call the NetConnectionEnum function,
      //  specifying information level 1.
      //
      res=NetConnectionEnum(lpszServer, lpszShare, 1, (LPBYTE *) &p, MAX_PREFERRED_LENGTH, &er, &tr, &resume);
      //
      // If no error occurred,
      //
      if(res == 0)
      {
         //
         // If there were any results,
         //
         if(er>0)
         {
            b=p;
            //
            // Loop through the entries; print user name and network name.
            //
            for(i=0;i<er;i++)
            {
               printf("%S\t%S\n", b->coni1_username,b->coni1_netname);
               b++;
            }
            // Free the allocated buffer.
            //
            NetApiBufferFree(p);
         }
         // Otherwise, print a message depending on whether 
         //  the qualifier parameter was a computer (\\ComputerName)
         //  or a share (ShareName).
         //
         else
         {
            if(lpszShare[0]=='\\')  
               printf("No connection to %S from %S\n", 
                  (lpszServer == NULL)?TEXT("LocalMachine"):lpszServer, lpszShare);
            else                       
               printf("No one connected to %S\\%S\n",
                  (lpszServer == NULL)?TEXT("\\\\LocalMachine"):lpszServer,lpszShare);
         }        
      }
      //
      // Otherwise, print the error.
      //
      else
         printf("Error: %d\n",res);
   }
   return;
}

要求


最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	lmshare.h (包括 Lm.h)
Library	Netapi32.lib
DLL	Netapi32.dll