NetDfsEnum 函式 (lmdfs.h)
列舉伺服器所裝載之命名空間的分散式檔案系統 (DFS) 命名空間，或伺服器所裝載之命名空間的 DFS 連結。
語法
NET_API_STATUS NET_API_FUNCTION NetDfsEnum(
[in] LPWSTR DfsName,
[in] DWORD Level,
[in] DWORD PrefMaxLen,
[out] LPBYTE *Buffer,
[out] LPDWORD EntriesRead,
[in, out] LPDWORD ResumeHandle
);
參數
[in] DfsName
指定 DFS 根目錄或連結之 UNC) 路徑 (通用命名慣例的字串指標。
當您指定資訊層級 200 (DFS_INFO_200) 時，此參數是網域的名稱。 當您指定資訊層級 300 (DFS_INFO_300) 時，此參數是伺服器的名稱。
對於所有其他層級，字串可以是下列四種形式之一：
ServerName\DfsName
或
ServerName\DfsName\link_path
其中 ServerName 是裝載獨立 DFS 命名空間之根目標伺服器的名稱; Dfsname 是 DFS 命名空間的名稱;和 link_path 是 DFS 連結。
字串也可以是下列形式：
DomainName\DomainName\DomDfsName
或
DomainName\DomDfsName\link_path
其中 DomainName 是裝載網域型 DFS 根目錄的功能變數名稱; DomDfsName 是 DFS 命名空間的名稱;和 link_path 是 DFS 連結。
您可以在字串前面加上反斜線 (\) ，但並非必要。 此為必要參數。
[in] Level
指定要求的資訊層級。 此參數可以是下列其中一個值。
1
傳回 DFS 根目錄的名稱，以及根底下的所有連結。 Buffer參數指向DFS_INFO_1結構的陣列。
2
傳回 DFS 根目錄和根底下所有連結的名稱、批註、狀態和目標數目。 Buffer參數指向DFS_INFO_2結構的陣列。
3
傳回 DFS 根目錄的每個目標名稱、批註、狀態、目標數目，以及根目錄下所有連結的相關資訊。 Buffer參數會指向DFS_INFO_3結構的陣列。
4
傳回 DFS 根目錄和根下所有連結的名稱、批註、狀態、 GUID、逾時、目標數目，以及每個目標的相關資訊。 Buffer參數會指向DFS_INFO_4結構的陣列。
5
傳回 DFS 根目錄和根下所有連結的名稱、狀態、 GUID、逾時、屬性旗標、中繼資料大小和目標數目。 Buffer參數指向DFS_INFO_5結構的陣列。
6
傳回根或連結的名稱、狀態、 GUID、逾時、屬性旗標、中繼資料大小、DFS 目標資訊，以及 DFS 目標清單。 Buffer參數會指向DFS_INFO_6結構的陣列。
8
傳回名稱、狀態、 GUID、逾時、屬性旗標、中繼資料大小、目標數目，以及 DFS 根目錄的連結重新分析點安全性描述元，以及根目錄下的所有連結。 Buffer參數會指向DFS_INFO_8結構的陣列。
9
傳回名稱、狀態、 GUID、逾時、屬性旗標、中繼資料大小、DFS 目標資訊、連結重新分析點安全性描述元，以及根或連結的 DFS 目標清單。 Buffer參數會指向DFS_INFO_9結構的陣列。
200
傳回網域中網域型 DFS 命名空間的清單。 Buffer參數會指向DFS_INFO_200結構的陣列。
300
傳回伺服器所裝載的獨立和網域型 DFS 命名空間。 Buffer參數會指向DFS_INFO_300結構的陣列。
[in] PrefMaxLen
指定資訊結構緩衝區中這個函式應該傳回的位元組數目。 如果此參數 MAX_PREFERRED_LENGTH，函式會配置資料所需的記憶體數量。 如需詳細資訊，請參閱接下來的＜備註＞一節。 如果您指定層級 200 或層級 300，則會忽略此參數。
[out] Buffer
接收所要求資訊結構的緩衝區指標。 此資料的格式取決於 Level 參數的值。 此緩衝區是由系統所配置，必須使用 NetApiBufferFree 函式釋放。
[out] EntriesRead
值指標，這個值會接收回應中傳回的實際專案數。
[in, out] ResumeHandle
值指標，這個值包含當可用的資料比在單一呼叫這個函式中傳回的資料還多時，用來繼續列舉的控制碼。 第一次呼叫時，控制碼應該是零，後續呼叫則保持不變。 如需詳細資訊，請參閱接下來的＜備註＞一節。
傳回值
如果函式成功，傳回值會 NERR_Success。
如果沒有其他專案可供列舉，傳回值會 ERROR_NO_MORE_ITEMS。
如果函式失敗，則傳回值是系統錯誤碼。 如需錯誤碼的清單，請參閱 系統錯誤碼。
備註
使用 NetDfsEnum 函式不需要特殊群組成員資格。
呼叫 NetDfsEnum 函式，並將 ResumeHandle 參數設定為零，以開始列舉。 若要繼續列舉作業，請使用先前呼叫NetDfsEnum所傳回的ResumeHandle呼叫這個函式。 如果此函式未傳回 ERROR_NO_MORE_ITEMS，後續對此 API 的呼叫將會傳回其餘的連結。 傳回 ERROR_NO_MORE_ITEMS 之後，就會擷取所有可用的 DFS 連結。
NetDfsEnum函式會配置資訊結構緩衝區所需的記憶體。 如果您在 PrefMaxLen 參數中指定數量，它會限制函式傳回的記憶體。 不過， NetDfsEnum 函式配置的實際記憶體大小可以大於您指定的數量。 如需詳細資訊，請參閱 網路管理函式緩衝區長度。
由於可能會同時更新 DFS 命名空間，呼叫端不應假設繼續列舉作業時傳回的結果完整性或唯一性。
範例
下列程式碼範例示範如何使用 對 NetDfsEnum 函式的呼叫，列出具名 DFS 根目錄中的 DFS 連結。 此範例會呼叫 NetDfsEnum，並指定資訊層級 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, p;
PDFS_STORAGE_INFO ps;
DWORD er = 0, hResume = 0, res, i, j;
if(argc < 2)
wprintf(L"Syntax: %s \\\\DfsName\n", argv[0]);
else
{
//
// Call the NetDfsEnum function, specifying level 3.
//
res = NetDfsEnum(argv[1], 3, MAX_PREFERRED_LENGTH, (LPBYTE *) &pData, &er, &hResume);
// Call NetDfsEnum until all available entries are returned.
// NetDfsEnum will return ERROR_NO_MORE_ITEMS when all entries
// have been obtained.
while (res == ERROR_SUCCESS)
{
p = pData;
//
// Loop through the entries; print the data.
//
for(i = 1; i <= er; i++)
{
printf("%-30S%u\n", p->EntryPath, p->NumberOfStorages);
ps = p->Storage;
//
// Loop through each target.
//
for(j = 1; j <= p->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++;
}
p++;
}
// Free the allocated buffer.
//
NetApiBufferFree(pData);
res = NetDfsEnum(argv[1], 3, MAX_PREFERRED_LENGTH, (LPBYTE *) &pData, &er, &hResume);
}
if (res == ERROR_NO_MORE_ITEMS)
{
// the last of the entries have been processed.
res = ERROR_SUCCESS;
printf("Enumeration done\n");
}
else
{
// an error occurred.
printf("Error: %u\n", res);
}
}
return;
}
需求
| 最低支援的用戶端 | Windows Vista |
| 最低支援的伺服器 | Windows Server 2008 |
| 目標平台 | Windows |
| 標頭 | lmdfs.h (包括 LmDfs.h、Lm.h) |
| 程式庫 | Netapi32.lib |
| Dll | Netapi32.dll |