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) を指定する場合、このパラメーターはサーバーの名前です。
他のすべてのレベルでは、文字列は次の 4 つの形式のいずれかで指定できます。
Servername\DfsName
or
Servername\DfsName\link_path
ここで 、ServerName はスタンドアロン DFS 名前空間をホストするルート ターゲット サーバーの名前です。 Dfsname は DFS 名前空間の名前です。と link_path は DFS リンクです。
文字列には、次の形式を指定することもできます。
Domainname\DomainName\DomDfsName
or
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
名前、コメント、状態、 GUID、タイムアウト、ターゲットの数、DFS ルートの各ターゲットとルート下のすべてのリンクに関する情報を返します。 Buffer パラメーターは、DFS_INFO_4構造体の配列を指します。
5
DFS ルートとルート下のすべてのリンクの名前、状態、 GUID、タイムアウト、プロパティ フラグ、メタデータ サイズ、ターゲットの数を返します。 Buffer パラメーターは、DFS_INFO_5構造体の配列を指します。
6
名前、状態、 GUID、タイムアウト、プロパティ フラグ、メタデータ サイズ、ルートまたはリンクの DFS ターゲット情報、および DFS ターゲットの一覧を返します。 Buffer パラメーターは、DFS_INFO_6構造体の配列を指します。
8
DFS ルートとルート下のすべてのリンクの名前、状態、 GUID、タイムアウト、プロパティ フラグ、メタデータ サイズ、ターゲットの数、リンクの再解析ポイントのセキュリティ記述子を返します。 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
この関数の 1 回の呼び出しで返すことができるデータよりも多くのデータが使用可能な場合に列挙を続行するために使用されるハンドルを含む値へのポインター。 最初の呼び出しではハンドルを 0 にし、後続の呼び出しでは変更せずに残す必要があります。 詳細については、「解説」を参照してください。
戻り値
関数が成功した場合、戻り値は NERR_Success。
これ以上エントリを列挙できない場合、戻り値は ERROR_NO_MORE_ITEMS。
関数が失敗した場合、戻り値はシステム エラー コードです。 エラー コードの一覧については、「 システム エラー コード」を参照してください。
解説
NetDfsEnum 関数を使用するために特別なグループ メンバーシップは必要ありません。
列挙を開始するには、ResumeHandle パラメーターを 0 に設定して NetDfsEnum 関数を呼び出します。 列挙操作を続行するには、前の NetDfsEnum 呼び出しによって返された ResumeHandle を使用してこの関数を呼び出します。 この関数が ERROR_NO_MORE_ITEMSを返さない場合、この API の後続の呼び出しは残りのリンクを返します。 ERROR_NO_MORE_ITEMSが返されると、使用可能なすべての DFS リンクが取得されます。
NetDfsEnum 関数は、情報構造体バッファーに必要なメモリを割り当てます。 PrefMaxLen パラメーターに量を指定すると、関数から返されるメモリが制限されます。 ただし、 NetDfsEnum 関数が割り当てるメモリの実際のサイズは、指定した量を超える場合があります。 詳細については、「 ネットワーク管理機能のバッファー長」を参照してください。
DFS 名前空間が同時に更新される可能性があるため、呼び出し元は列挙操作を再開するときに返される結果の完全性または一意性を想定しないでください。
例
次のコード サンプルでは、 NetDfsEnum 関数を呼び出して、名前付き DFS ルート内の DFS リンクを一覧表示する方法を示します。 このサンプルでは、情報レベル 3 ( DFS_INFO_3) を指定して NetDfsEnum を呼び出します。 このサンプル コードでは、エントリをループ処理し、取得したデータと、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 を含む) |
| Library | Netapi32.lib |
| [DLL] | Netapi32.dll |