NetFileEnum 函式 (lmshare.h)

發行項
03/05/2024

根據指定的參數，傳回伺服器上部分或所有開啟檔案的相關信息。

語法

NET_API_STATUS NET_API_FUNCTION NetFileEnum(
  [in]      LMSTR      servername,
  [in]      LMSTR      basepath,
  [in]      LMSTR      username,
  [in]      DWORD      level,
  [out]     LPBYTE     *bufptr,
  [in]      DWORD      prefmaxlen,
  [out]     LPDWORD    entriesread,
  [out]     LPDWORD    totalentries,
  [in, out] PDWORD_PTR resume_handle
);

參數

[in] servername

字串的指標，指定要在其中執行函式之遠端伺服器的 DNS 或 NetBIOS 名稱。如果此參數為 NULL，則會使用本機電腦。

如果 已定義_WIN32_WINNT 或 FORCE_UNICODE ，則此字串為 Unicode。

[in] basepath

字串的指標，指定傳回資訊的限定符。如果此參數為 NULL，則會列舉所有開啟的資源。如果此參數不是 NULL，函式只會列舉具有 basepath 參數值作為前置詞的資源。 (前置詞是反斜杠之前的路徑部分。)

如果 已定義_WIN32_WINNT 或 FORCE_UNICODE ，則此字串為 Unicode。

[in] username

指定使用者名稱或連接名稱的字串指標。如果字串以兩個反斜杠開頭 (“\”) ，則表示連接的名稱，例如 “\127.0.0.1” 或 “\ClientName”。反斜杠之後的連接名稱部分與 NetSessionEnum 函式所傳回的會話信息結構中的用戶端名稱相同。如果字串開頭不是兩個反斜杠，則會指出用戶的名稱。如果此參數不是 NULL，其值會作為列舉的限定符。傳回的檔案僅限於具有符合限定符之用戶名稱或連接名稱的檔案。如果此參數為 NULL，則不會使用任何用戶名稱限定符。

Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 此參數是指定使用者名稱的字串指標。如果此參數不是 NULL，其值會作為列舉的限定符。傳回的檔案僅限於具有符合限定符之用戶名稱的檔案。如果此參數為 NULL，則不會使用任何用戶名稱限定符。

如果 已定義_WIN32_WINNT 或 FORCE_UNICODE ，則此字串為 Unicode。

[in] level

指定資料的資訊層級。此參數可以是下列其中一個值。

值	意義
2	傳回檔案標識碼。 bufptr 參數指向FILE_INFO_2 結構的陣列。
3	傳回檔案的相關信息。 bufptr 參數指向FILE_INFO_3 結構的陣列。

[out] bufptr

接收信息的緩衝區位址指標。此數據的格式取決於 level 參數的值。

此緩衝區是由系統所配置，必須使用 NetApiBufferFree 函式釋放。請注意，即使函式因 ERROR_MORE_DATA而失敗，您仍必須釋放緩衝區。

[in] prefmaxlen

指定所傳回數據的慣用最大長度，以位元組為單位。如果您指定 MAX_PREFERRED_LENGTH，函式會配置數據所需的記憶體數量。如果您在此參數中指定另一個值，它可以限制函式傳回的位元組數目。如果緩衝區大小不足以保存所有專案，函式會 傳回ERROR_MORE_DATA。如需詳細資訊，請參閱網路管理功能緩衝區和網路管理函式緩衝區長度。

[out] entriesread

值指標，這個值會接收實際列舉的項目計數。

[out] totalentries

值的指標，這個值會接收可能已從目前繼續位置列舉的項目總數。請注意，應用程式應該只將此值視為提示。

[in, out] resume_handle

值的指標，其中包含用來繼續現有檔案搜尋的繼續句柄。第一次呼叫時，句柄應該是零，後續呼叫則保持不變。如果此參數為 NULL，則不會儲存任何繼續句柄。

傳回值

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

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

傳回碼	Description
ERROR_ACCESS_DENIED	用戶無法存取要求的資訊。
ERROR_INVALID_LEVEL	為 level 參數指定的值無效。
ERROR_MORE_DATA	有更多專案可供使用。指定夠大的緩衝區來接收所有專案。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足。
NERR_BufTooSmall	提供的緩衝區太小。

備註

只有 Administrators 或 Server Operators 本地組的成員才能成功執行 NetFileEnum 函式。

您可以呼叫 NetFileGetInfo 函式來擷取特定開啟伺服器資源的相關信息。

如果您是針對 Active Directory 進行程式設計，您可以呼叫特定 Active Directory 服務介面 (ADSI) 方法來達到相同的功能，方法是呼叫 NetFileEnum。如需詳細資訊，請參閱 IADsResource 和 IADsFileServiceOperations。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	lmshare.h (包含 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll