NetDfsGetInfo 函式 （lmdfs.h）
擷取 DFS 命名空間中指定分散式檔案系統 （DFS） 根目錄或連結的相關信息。
語法
NET_API_STATUS NET_API_FUNCTION NetDfsGetInfo(
[in] LPWSTR DfsEntryPath,
[in, optional] LPWSTR ServerName,
[in, optional] LPWSTR ShareName,
[in] DWORD Level,
[out] LPBYTE *Buffer
);
參數
[in] DfsEntryPath
字串的指標，指定 DFS 根目錄或連結的通用命名約定 （UNC） 路徑。
對於連結，字串可以是兩種形式之一。 第一個表單如下所示：
\\ ServerName\DfsName\link_path
其中 ServerName 是裝載獨立 DFS 命名空間的根目標伺服器名稱;DfsName 是 DFS 命名空間的名稱;和 link_path 是 DFS 連結。
第二個表單如下所示：
\\ DomainName\DomDfsname\link_path
其中 DomainName 是裝載網域型 DFS 命名空間的網域名稱;DomDfsname 是 DFS 命名空間的名稱;和 link_path 是 DFS 連結。
若為根目錄，字串可以是兩種形式之一：
\\ ServerName\DfsName
或
\\ DomainName\DomDfsname
其中名稱的值與先前所述的值相同。
這是必要參數。
[in, optional] ServerName
此參數目前會被忽略，且應該 NULL。
[in, optional] ShareName
此參數目前會被忽略，且應該 NULL。
[in] Level
指定要求的信息層級。 此參數可以是下列其中一個值。
1
傳回 DFS 根目錄或 DFS 連結名稱。 Buffer 參數指向 DFS_INFO_1 結構。
2
傳回 DFS 根目錄或 DFS 連結名稱、狀態，以及 DFS 目標的數目。 Buffer 參數指向 DFS_INFO_2 結構。
3
傳回 DFS 根目錄或 DFS 連結名稱、狀態和目標資訊。 Buffer 參數指向 DFS_INFO_3 結構。
4
傳回 DFS 根目錄或 DFS 連結名稱、狀態、GUID、逾時和目標資訊。 Buffer 參數指向 DFS_INFO_4 結構。
5
傳回名稱、狀態、GUID、逾時、屬性旗標、元數據大小，以及 DFS 根目錄下的所有鏈接的目標數目。 Buffer 參數指向 DFS_INFO_5 結構的陣列。
6
傳回名稱、狀態、GUID、逾時、屬性旗標、元數據大小、DFS 目標資訊，以及 DFS 目標清單。 Buffer 參數指向 DFS_INFO_6 結構的陣列。
7
傳回 DFS 元數據 GUID 的版本號碼。 Buffer 參數指向 DFS_INFO_7 結構的陣列。
8
傳回名稱、狀態、GUID、逾時、屬性旗標、元數據大小、目標數目，以及 DFS 根目錄下的所有連結的連結重新分析點安全性描述元。 Buffer 參數會指向 DFS_INFO_8 結構的陣列。
9
傳回名稱、狀態、GUID、逾時、屬性旗標、元數據大小、DFS 目標資訊、連結重新分析點安全性描述元，以及根或連結的 DFS 目標清單。 Buffer 參數指向 DFS_INFO_9 結構的陣列。
50
傳回現有 DFS 命名空間的 DFS 元數據版本和功能。 Buffer 參數指向 DFS_INFO_50 結構。
100
傳回有關 DFS 根或 DFS 連結的批注。 Buffer 參數指向 DFS_INFO_100 結構。
150
傳回 DFS 連結重新分析點的安全性描述元。 Buffer 參數指向 DFS_INFO_150 結構。
[out] Buffer
接收所要求信息結構的緩衝區位址指標。 此數據的格式取決於 Level 參數的值。 這個緩衝區是由系統配置，而且必須使用 netApiBufferFree 函式 釋放。 如需詳細資訊，請參閱 網路管理功能緩衝區 和 網路管理功能緩衝區長度。
傳回值
如果函式成功，則傳回值會 NERR_Success。
如果函式失敗，傳回值就是系統錯誤碼。 如需錯誤碼的清單，請參閱 系統錯誤碼。
言論
使用 NetDfsGetInfo 函式不需要特殊群組成員資格。
呼叫 NetDfsGetInfo 函式的應用程式，可能會間接導致本機 DFS 命名空間伺服器服務函式呼叫，以從該網域的 PDC 模擬器主機執行相關命名空間元數據的完整同步處理。 即使已針對該命名空間設定根延展性模式，也會發生此完整同步處理。 為了避免這種副作用，如果意圖只是擷取特定 DFSN 用戶端電腦所使用的實體 UNC 路徑名稱，對應指定的 DFS 命名空間路徑， 接著，其中一個替代方法是使用 WDK API ZwQueryInformationFile，傳遞 FileNetworkPhysicalNameInformation 作為 fileInformationClass 參數的 FileInformationClass，並將呼叫端配置 FILE_NETWORK_PHYSICAL_NAME_INFORMATION 結構的地址傳遞為 FileInformation 參数。 如需呼叫 WDK API 的詳細資訊，請參閱 WDK。
例子
下列程式代碼範例示範如何使用呼叫 netDfsGetInfo 函式來擷取 DFS 連結的相關信息。 範例會呼叫 NetDfsGetInfo，並指定資訊層級 3 （DFS_INFO_3）。 如果呼叫成功，範例會列印 DFS 連結的相關信息，包括連結所參考之每個目標的名稱和狀態。 最後，程式代碼範例會釋放配置給資訊緩衝區的記憶體。
#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>
#pragma comment(lib, "Netapi32.lib")
void wmain(int argc, wchar_t *argv[ ])
{
PDFS_INFO_3 pData;
PDFS_STORAGE_INFO ps;
DWORD er = 0, tr = 0, res, j;
//
// Check command line arguments.
//
if (argc<2)
wprintf(L"Syntax: %s DfsEntryPath\n", argv[0]);
else
{
//
// Call the NetDfsGetInfo function, specifying level 3.
//
res = NetDfsGetInfo(argv[1], NULL, NULL, 3, (LPBYTE *) &pData);
//
// If the call succeeds, print the data.
//
if(res==0)
{
printf("%-30S Storages: %u\nComment: %S\n", pData->EntryPath, pData->NumberOfStorages, pData->Comment);
ps = pData->Storage;
//
// Loop through each target.
//
for(j = 1; j <= pData->NumberOfStorages;j++)
{
//
// Print the status (Offline/Online) and the name
// of each target referenced by the DFS link.
//
printf(" %S ", (ps->State == DFS_STORAGE_STATE_OFFLINE) ? TEXT("Offline"): TEXT("Online "));
printf("\\\\%S\\%S\n", ps->ServerName, ps->ShareName);
ps++;
}
//
// Free the allocated memory.
//
NetApiBufferFree(pData);
}
else
printf("Error: %u\n", res);
}
return;
}
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows Vista |
| 支援的最低伺服器 | Windows Server 2008 |
| 目標平臺 | 窗戶 |
| 標頭 | lmdfs.h （包括 LmDfs.h、Lm.h） |
| 連結庫 | Netapi32.lib |
| DLL | Netapi32.dll |