NetShareEnum 函式 (lmshare.h)
擷取伺服器上每個共用資源的相關資訊。
您也可以使用 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
指定資料的資訊層級。 此參數可以是下列其中一個值。
| 值 | 意義 |
|---|---|
|
傳回共用名稱。 bufptr參數指向SHARE_INFO_0結構的陣列。 |
|
傳回共用資源的相關資訊，包括資源的名稱和類型，以及與資源相關聯的批註。
bufptr參數指向SHARE_INFO_1結構的陣列。 |
|
傳回共用資源的相關資訊，包括資源的名稱、類型和許可權、密碼，以及連線數目。 bufptr參數指向SHARE_INFO_2結構的陣列。 |
|
傳回共用資源的相關資訊，包括資源的名稱、類型和許可權、連線數目和其他相關資訊。 bufptr參數指向SHARE_INFO_502結構的陣列。 不會傳回來自不同範圍的共用。 如需範圍的詳細資訊，請參閱 NetServerTransportAddEx 函式檔的一節。 |
|
傳回共用資源的相關資訊，包括資源的名稱、類型和許可權、連線數目和其他相關資訊。 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 |