NetShareEnum 函数 (lmshare.h)

项目
08/24/2023

检索有关服务器上每个共享资源的信息。

还可以使用 WNetEnumResource 函数检索资源信息。但是， WNetEnumResource 不枚举隐藏的共享或连接到共享的用户。

语法

NET_API_STATUS NET_API_FUNCTION NetShareEnum(
  [in]      LMSTR   servername,
  [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] level

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

值	含义
0	返回共享名称。 bufptr 参数指向SHARE_INFO_0结构的数组。
1	返回有关共享资源的信息，包括资源的名称和类型以及与资源关联的注释。 bufptr 参数指向SHARE_INFO_1结构的数组。
2	返回有关共享资源的信息，包括资源名称、类型和权限、密码以及连接数。 bufptr 参数指向SHARE_INFO_2结构的数组。
502	返回有关共享资源的信息，包括资源名称、类型和权限、连接数以及其他相关信息。 bufptr 参数指向SHARE_INFO_502结构的数组。不会返回不同范围的共享。有关范围的详细信息，请参阅 NetServerTransportAddEx 函数文档的“备注”部分。
503	返回有关共享资源的信息，包括资源名称、类型和权限、连接数以及其他相关信息。 bufptr 参数指向SHARE_INFO_503结构的数组。返回来自所有范围的共享。如果此结构的 shi503_servername 成员为“”，则没有配置的服务器名称，并且 NetShareEnum* 函数枚举所有无作用域名称的共享。 Windows Server 2003 和 Windows XP：不支持此信息级别。

[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。

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

注解

此函数仅适用于 SMB) 共享 (服务器消息块。对于其他类型的共享（例如分布式文件系统 (DFS) 或 WebDAV 共享），请使用支持所有类型的共享的 Windows 网络 (WNet) 函数。

对于本地登录到计算机) 的交互式用户 (用户，执行 NetShareEnum 函数不需要特殊的组成员身份。对于非交互式用户，需要管理员、Power User、打印操作员或服务器操作员组成员身份才能在级别 2、502 和 503 上成功执行 NetShareEnum 函数。级别 0 或级别 1 调用不需要特殊组成员身份。

Windows Server 2022： 对于非交互式用户，需要管理员、访问控制协助操作员或服务器操作员组成员身份才能在级别 2、502 和 503 上成功执行 NetShareEnum 函数。

Windows Server 2003 和 Windows XP： 对于所有用户，需要管理员、Power User、打印操作员或服务器操作员组成员身份才能在级别 2 和 502 上成功执行 NetShareEnum 函数。

若要检索指示共享是否为 DFS 树结构中的根卷的值，必须调用 NetShareGetInfo 函数并指定信息级别 1005。

如果要对 Active Directory 进行编程，则可以调用某些 Active Directory 服务接口 (ADSI) 方法来实现通过调用网络管理共享函数可以实现的相同功能。有关详细信息，请参阅 IADsFileShare。

示例

下面的代码示例演示如何使用对 NetShareEnum 函数的调用来检索有关服务器上每个共享资源的信息。此示例调用 NetShareEnum，指定信息级别 502 (SHARE_INFO_502) 。如果调用成功，代码将循环访问条目并输出有关每个共享的信息。此示例还调用 IsValidSecurityDescriptor 函数来验证 shi502_security_descriptor 成员。最后，代码示例释放为信息缓冲区分配的内存。

#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <stdio.h>
#include <lm.h>

#pragma comment(lib, "Netapi32.lib")
#pragma comment(lib, "Advapi32.lib")

void wmain( int argc, TCHAR *lpszArgv[ ])
{
   PSHARE_INFO_502 BufPtr,p;
   NET_API_STATUS res;
   LPTSTR   lpszServer = NULL;
   DWORD er=0,tr=0,resume=0, i;

   switch(argc)
   {
   case 2:
      lpszServer = lpszArgv[1];
      break;
   default:
      printf("Usage: NetShareEnum <servername>\n");
      return;
   }
   //
   // Print a report header.
   //
   printf("Share:              Local Path:                   Uses:   Descriptor:\n");
   printf("---------------------------------------------------------------------\n");
   //
   // Call the NetShareEnum function; specify level 502.
   //
   do // begin do
   {
      res = NetShareEnum (lpszServer, 502, (LPBYTE *) &BufPtr, MAX_PREFERRED_LENGTH, &er, &tr, &resume);
      //
      // If the call succeeds,
      //
      if(res == ERROR_SUCCESS || res == ERROR_MORE_DATA)
      {
         p=BufPtr;
         //
         // Loop through the entries;
         //  print retrieved data.
         //
         for(i=1;i<=er;i++)
         {
            printf("%-20S%-30S%-8u",p->shi502_netname, p->shi502_path, p->shi502_current_uses);
            //
            // Validate the value of the 
            //  shi502_security_descriptor member.
            //
            if (IsValidSecurityDescriptor(p->shi502_security_descriptor))
               printf("Yes\n");
            else
               printf("No\n");
            p++;
         }
         //
         // Free the allocated buffer.
         //
         NetApiBufferFree(BufPtr);
      }
      else 
         printf("Error: %ld\n",res);
   }
   // Continue to call NetShareEnum while 
   //  there are more entries. 
   // 
   while (res==ERROR_MORE_DATA); // end do
   return;
}

要求


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