NetShareEnum 函式 (lmshare.h)

發行項
03/14/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
);

參數

[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

接收資料的緩衝區指標。此資料的格式取決於 level 參數的值。

此緩衝區是由系統所配置，必須使用 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)
程式庫	Netapi32.lib
Dll	Netapi32.dll