NetServerEnum 関数 (lmserver.h)
NetServerEnum 関数は、ドメインに表示される指定された種類のすべてのサーバーを一覧表示します。
構文
NET_API_STATUS NET_API_FUNCTION NetServerEnum(
[in, optional] LMCSTR servername,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in] DWORD servertype,
[in, optional] LMCSTR domain,
[in, out, optional] LPDWORD resume_handle
);
パラメーター
[in, optional] servername
予約; は NULL である必要があります。
[in] level
要求されたデータの情報レベル。 このパラメーターには、次の値のいずれかを指定できます。
| 値 | 意味 |
|---|---|
|
サーバー名とプラットフォーム情報を返します。 bufptr パラメーターは、SERVER_INFO_100構造体の配列を指します。 |
|
サーバー名、型、および関連データを返します。 bufptr パラメーターは、SERVER_INFO_101構造体の配列を指します。 |
[out] bufptr
データを受信するバッファーへのポインター。 このデータの形式は 、level パラメーターの値によって異なります。 このバッファーはシステムによって割り当てられ、 NetApiBufferFree 関数を使用して解放する必要があります。 関数がERROR_MORE_DATAで失敗した場合でも、バッファーを解放する必要があることに注意してください。
[in] prefmaxlen
返されるデータの推奨される最大長 (バイト単位)。 MAX_PREFERRED_LENGTHを指定すると、データに必要なメモリ量が関数によって割り当てられます。 このパラメーターに別の値を指定すると、関数から返されるバイト数を制限できます。 バッファー サイズが不十分で、すべてのエントリを保持するには、関数は ERROR_MORE_DATAを返します。 詳細については、「 ネットワーク管理機能バッファー 」および「 ネットワーク管理機能バッファーの長さ」を参照してください。
[out] entriesread
実際に列挙された要素の数を受け取る値へのポインター。
[out] totalentries
ネットワーク上の可視サーバーとワークステーションの合計数を受け取る値へのポインター。 アプリケーションでは、この値をヒントとしてのみ考慮する必要があることに注意してください。
[in] servertype
列挙から返すサーバー エントリをフィルター処理する値。 このパラメーターには、 Lmserver.h ヘッダー ファイルで定義されている次の値の組み合わせを指定できます。
[in, optional] domain
サーバーの一覧を返すドメインの名前を指定する定数文字列へのポインター。 ドメイン名は NetBIOS ドメイン名 (microsoft など) である必要があります。 NetServerEnum 関数は、DNS スタイルの名前 (たとえば、microsoft.com) をサポートしていません。
このパラメーターが NULL の場合、プライマリ ドメインは暗黙的に指定されます。
[in, out, optional] resume_handle
予約;は 0 に設定する必要があります。
戻り値
関数が成功した場合、戻り値はNERR_Success。
関数が失敗した場合、戻り値には次のいずれかのエラー コードを指定できます。
| リターン コード/値 | Description |
|---|---|
|
アクセスが拒否されました。 |
|
パラメーターが正しくありません。 |
|
その他のエントリを使用できます。 すべてのエントリを受信するのに十分な大きさのバッファーを指定します。 |
|
ブラウザー サーバーが見つかりません。 |
|
要求はサポートされていません。 |
|
サーバーからデータが返されない状態でリモート エラーが発生しました。 |
|
サーバー サービスが開始されていません。 |
|
サービスは開始されていません。 |
|
ワークステーション サービスが開始されていません。 ローカル ワークステーション サービスは、ダウンレベルのリモート サーバーとの通信に使用されます。 |
注釈
NetServerEnum 関数は、ドメインに表示される、指定した種類のすべてのサーバーを一覧表示するために使用されます。 たとえば、アプリケーションは NetServerEnum を呼び出して、すべてのドメイン コントローラーのみ、または SQL Server のインスタンスのみを実行するすべてのサーバーを一覧表示できます。
アプリケーションは、 servertype パラメーター内のさまざまなサーバーの種類のビット マスクを組み合わせて、いくつかの型を一覧表示します。 たとえば、 の値SV_TYPE_WORKSTATION |SVTYPE_SERVER (0x00000003) は、SV_TYPE_WORKSTATION (0x00000001) とSV_TYPE_SERVER (0x00000002) のビット マスクを結合します。
特定のサーバーに関する詳細情報が必要な場合は、 WNetEnumResource 関数を呼び出します。
NetServerEnum 関数を正常に実行するために特別なグループ メンバーシップは必要ありません。
SV_TYPE_LOCAL_LIST_ONLY値を指定すると、 NetServerEnum 関数は、ブラウザーが内部的に維持するサーバーの一覧を返します。 これは、マスター ブラウザー (または過去にマスター ブラウザーであったコンピューター) でのみ意味を持ちます。 マスター ブラウザーは、現在、ネットワーク上のサーバーまたはワークステーションにできるコンピューターを決定する権限を持つコンピューターです。
servertype パラメーターで指定された型に一致するサーバーが見つからない場合、NetServerEnum 関数は bufptr パラメーターを NULL として返し、entriesread パラメーターと totalentries パラメーターが指す DWORD 値は 0 に設定されます。
NetServerEnum 関数は、インストールおよび実行されているブラウザー サービスによって異なります。 ブラウザー サーバーが見つからない場合、 NetServerEnum はERROR_NO_BROWSER_SERVERS_FOUNDで失敗します。
Active Directory のプログラミングを行っている場合は、特定の Active Directory サービス インターフェイス (ADSI) メソッドを呼び出して、ネットワーク管理サーバー関数を呼び出すことで実現できるのと同じ機能を実現できる場合があります。 詳細については、「 IADsComputer」を参照してください。
例
次のコード サンプルは、 NetServerEnum 関数を呼び出してドメインに表示されるすべてのサーバーを一覧表示する方法を示しています。 このサンプルでは、情報レベル 101 ( SERVER_INFO_101) を指定して NetServerEnum を呼び出します。 サーバーが見つかった場合、サンプル コードはエントリをループ処理し、取得したデータを出力します。 サーバーがドメイン コントローラーの場合、サーバーはプライマリ ドメイン コントローラー (PDC) またはバックアップ ドメイン コントローラー (BDC) として識別されます。 このサンプルでは、使用可能なエントリの合計数と、実際に列挙されたエントリの数に関するヒントも出力されます。すべてのエントリが列挙されていない場合は、ユーザーに警告します。 最後に、このサンプルでは、情報バッファーに割り当てられたメモリを解放します。
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t * argv[])
{
LPSERVER_INFO_101 pBuf = NULL;
LPSERVER_INFO_101 pTmpBuf;
DWORD dwLevel = 101;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwTotalCount = 0;
DWORD dwServerType = SV_TYPE_SERVER; // all servers
DWORD dwResumeHandle = 0;
NET_API_STATUS nStatus;
LPWSTR pszServerName = NULL;
LPWSTR pszDomainName = NULL;
DWORD i;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [DomainName]\n", argv[0]);
exit(1);
}
// The request is not for the primary domain.
//
if (argc == 2)
pszDomainName = argv[1];
//
// Call the NetServerEnum function to retrieve information
// for all servers, specifying information level 101.
//
nStatus = NetServerEnum(pszServerName,
dwLevel,
(LPBYTE *) & pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
dwServerType,
pszDomainName,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA)) {
if ((pTmpBuf = pBuf) != NULL) {
//
// Loop through the entries and
// print the data for all server types.
//
for (i = 0; i < dwEntriesRead; i++) {
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL) {
fprintf(stderr, "An access violation has occurred\n");
break;
}
printf("\tPlatform: %d\n", pTmpBuf->sv101_platform_id);
wprintf(L"\tName: %s\n", pTmpBuf->sv101_name);
printf("\tVersion: %d.%d\n",
pTmpBuf->sv101_version_major,
pTmpBuf->sv101_version_minor);
printf("\tType: %d", pTmpBuf->sv101_type);
//
// Check to see if the server is a domain controller;
// if so, identify it as a PDC or a BDC.
//
if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_CTRL)
wprintf(L" (PDC)");
else if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_BAKCTRL)
wprintf(L" (BDC)");
printf("\n");
//
// Also print the comment associated with the server.
//
wprintf(L"\tComment: %s\n\n", pTmpBuf->sv101_comment);
pTmpBuf++;
dwTotalCount++;
}
// Display a warning if all available entries were
// not enumerated, print the number actually
// enumerated, and the total number available.
if (nStatus == ERROR_MORE_DATA) {
fprintf(stderr, "\nMore entries available!!!\n");
fprintf(stderr, "Total entries: %d", dwTotalEntries);
}
printf("\nEntries enumerated: %d\n", dwTotalCount);
} else {
printf("No servers were found\n");
printf("The buffer (bufptr) returned was NULL\n");
printf(" entriesread: %d\n", dwEntriesRead);
printf(" totalentries: %d\n", dwEntriesRead);
}
} else
fprintf(stderr, "NetServerEnum failed with error: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | lmserver.h (include Lm.h) |
| Library | Netapi32.lib |
| [DLL] | Netapi32.dll |