NetShareGetInfo 函数 (lmshare.h)

项目
03/13/2024

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

语法

NET_API_STATUS NET_API_FUNCTION NetShareGetInfo(
  [in]  LMSTR  servername,
  [in]  LMSTR  netname,
  [in]  DWORD  level,
  [out] LPBYTE *bufptr
);

参数

[in] servername

指向字符串的指针，该字符串指定要对其执行函数的远程服务器的 DNS 或 NetBIOS 名称。如果此参数为 NULL，则使用本地计算机。

[in] netname

指向一个字符串的指针，该字符串指定要为其返回信息的共享的名称。

[in] level

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

值	含义
0	返回共享名称。 bufptr 参数指向SHARE_INFO_0结构。
1	返回有关共享资源的信息，包括资源的名称和类型以及与资源关联的注释。 bufptr 参数指向SHARE_INFO_1结构。
2	返回有关共享资源的信息，包括资源名称、类型和权限、密码以及连接数。 bufptr 参数指向SHARE_INFO_2结构。
501	返回资源的名称和类型，以及与资源关联的注释。 bufptr 参数指向SHARE_INFO_501结构。
502	返回有关共享资源的信息，包括资源名称、类型和权限、连接数以及其他相关信息。 bufptr 参数指向SHARE_INFO_502结构。
503	指定有关共享资源的信息，包括资源的名称、类型和权限、连接数以及其他相关信息。 buf 参数指向SHARE_INFO_503结构。如果此结构的 shi503_servername 成员为“”，则没有配置的服务器名称。 Windows Server 2003 和 Windows XP：* 不支持此信息级别。
1005	返回一个值，该值指示共享是否为 Dfs 树结构中的根卷。 bufptr 参数指向SHARE_INFO_1005结构。

[out] bufptr

指向接收数据的缓冲区的指针。此数据的格式取决于级别参数的值。有关详细信息，请参阅网络管理功能缓冲区。

此缓冲区由系统分配，必须使用 NetApiBufferFree 函数释放。

返回值

如果函数成功，则返回值NERR_Success。

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

返回代码	说明
ERROR_ACCESS_DENIED	用户无权访问请求的信息。
ERROR_INVALID_LEVEL	为级别参数指定的值无效。
ERROR_INVALID_PARAMETER	指定的参数无效。
ERROR_NOT_ENOUGH_MEMORY	可用内存不足。
NERR_NetNameNotFound	共享名称不存在。

注解

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

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

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

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

如果为级别参数指定了 503，则SHARE_INFO_503结构的 shi503_servername 成员中指定的远程服务器必须已使用 NetServerTransportAddEx 函数绑定到传输协议。在调用 NetServerTransportAddEx 时，必须为级别参数指定 2 或 3，并且 必须在 传输协议的 SERVER_TRANSPORT_INFO_2 结构中指定 SVTI2_SCOPED_NAME 标志。

示例

以下代码示例演示如何使用对 NetShareGetInfo 函数的调用来检索有关特定共享资源的信息。此示例调用 NetShareGetInfo，指定信息级别 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;
   NET_API_STATUS res;
   LPTSTR   lpszServer = NULL, lpszShare;
   //
   // Check command line arguments.
   //
   switch(argc)
   {
   case 3:
      lpszServer = lpszArgv[2];
   case 2:
      lpszShare = lpszArgv[1];
      break;
   default:
      printf("Usage: NetShareGetInfo sharename <servername>\n");
      return;
   }
   //
   // Call the NetShareGetInfo function, specifying level 502.
   //
   if((res = NetShareGetInfo (lpszServer,lpszShare,502,(LPBYTE *) &BufPtr)) == ERROR_SUCCESS)
   {
      //
      // Print the retrieved data.
      //
      printf("%S\t%S\t%u\n",BufPtr->shi502_netname, BufPtr->shi502_path, BufPtr->shi502_current_uses);
      //
      // Validate the value of the 
      //  shi502_security_descriptor member.
      //
      if (IsValidSecurityDescriptor(BufPtr->shi502_security_descriptor))
         printf("It has a valid Security Descriptor.\n");
      else
         printf("It does not have a valid Security Descriptor.\n");
      //
      // Free the allocated memory.
      //
      NetApiBufferFree(BufPtr);
   }
   else 
      printf("Error: %ld\n",res);
   return;
}

要求

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