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

接收數據的緩衝區指標。此數據的格式取決於 level 參數的值。如需詳細資訊，請參閱網路管理功能緩衝區。

此緩衝區是由系統所配置，必須使用 NetApiBufferFree 函式釋放。

傳回值

如果函式成功，傳回值會NERR_Success。

如果函式失敗，傳回值可以是下列其中一個錯誤碼。

傳回碼	Description
ERROR_ACCESS_DENIED	用戶無法存取要求的資訊。
ERROR_INVALID_LEVEL	為 level 參數指定的值無效。
ERROR_INVALID_PARAMETER	指定的參數無效。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足。
NERR_NetNameNotFound	共用名不存在。

備註

此函式僅適用於SMB) 共用 (伺服器消息塊。對於其他類型的共用，例如分散式文件系統 (DFS) 或 WebDAV 共用，請使用支援所有類型的共用的 Windows 網路 (WNet) 函式。

對於 (本機登入計算機的使用者) ，不需要特殊群組成員資格才能執行 NetShareGetInfo 函式。對於非互動式使用者，需要系統管理員、Power User、列印操作員或伺服器操作員群組成員資格，才能在層級 2、502 和 503 成功執行 NetShareEnum 函式。層級 0 或層級 1 呼叫不需要特殊群組成員資格。

Windows Server 2003 和 Windows XP： 對於所有使用者，需要系統管理員、Power User、列印操作員或伺服器操作員群組成員資格，才能在層級 2 和 502 成功執行 NetShareGetInfo 函式。

如果您是針對 Active Directory 進行程式設計，您可以呼叫特定 Active Directory 服務介面 (ADSI) 方法來達到相同的功能，方法是呼叫網路管理共用函式。如需詳細資訊，請參閱 IADsFileShare。

如果為 level 參數指定 503，則SHARE_INFO_503結構shi503_servername成員中指定的遠端伺服器必須使用 NetServerTransportAddEx 函式系結至傳輸通訊協定。在 NetServerTransportAddEx 的呼叫中，必須為 level 參數指定 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)
程式庫	Netapi32.lib
Dll	Netapi32.dll