NetQueryDisplayInformation 関数 (lmaccess.h)
NetQueryDisplayInformation 関数は、ユーザー アカウント、コンピューター、またはグループ アカウントの情報を返します。 この関数を呼び出して、ユーザー インターフェイスに表示するアカウント情報をすばやく列挙します。
構文
NET_API_STATUS NET_API_FUNCTION NetQueryDisplayInformation(
[in] LPCWSTR ServerName,
[in] DWORD Level,
[in] DWORD Index,
[in] DWORD EntriesRequested,
[in] DWORD PreferredMaximumLength,
[out] LPDWORD ReturnedEntryCount,
[out] PVOID *SortedBuffer
);
パラメーター
[in] ServerName
関数を実行するリモート サーバーの DNS または NetBIOS 名を指定する定数文字列へのポインター。 このパラメーターが NULL の場合は、ローカル コンピューターが使用されます。
[in] Level
データの情報レベルを指定します。 このパラメーターには、次の値のいずれかを指定できます。
| 値 | 説明 |
|---|---|
|
ユーザー アカウント情報を返します。 SortedBuffer パラメーターは、NET_DISPLAY_USER構造体の配列を指します。 |
|
個々のコンピューター情報を返します。 SortedBuffer パラメーターは、NET_DISPLAY_MACHINE構造体の配列を指します。 |
|
グループ アカウント情報を返します。 SortedBuffer パラメーターは、NET_DISPLAY_GROUP構造体の配列を指します。 |
[in] Index
情報を取得する最初のエントリのインデックスを指定します。 最初の表示情報エントリから始まるアカウント情報を取得するには、0 を指定します。 詳細については、「解説」を参照してください。
[in] EntriesRequested
情報を取得するエントリの最大数を指定します。 Windows 2000 以降では、 NetQueryDisplayInformation を呼び出すたびに最大 100 個のオブジェクトが返されます。
[in] PreferredMaximumLength
SortedBuffer パラメーターで返されるシステム割り当てバッファーの推奨最大サイズをバイト単位で指定します。 このパラメーターは、MAX_PREFERRED_LENGTHに設定することをお勧めします。
[out] ReturnedEntryCount
SortedBuffer パラメーターで返されるバッファー内のエントリの数を受け取る値へのポインター。 このパラメーターが 0 の場合、指定したサイズのインデックスを持つエントリはありません。 関数の戻り値がNERR_SuccessまたはERROR_MORE_DATAの場合、エントリが返される場合があります。
[out] SortedBuffer
要求された情報の並べ替えられたリストを指定するシステム割り当てバッファーへのポインターを受け取るバッファーへのポインター。 このデータの形式は 、Level パラメーターの値によって異なります。 このバッファーはシステムによって割り当てられるため、 NetApiBufferFree 関数を使用して解放する必要があります。 関数が ERROR_MORE_DATA で失敗した場合でも、バッファーを解放する必要があることに注意してください。 詳細については、次の「戻り値」セクションとトピック「 ネットワーク管理機能バッファー 」および「 ネットワーク管理機能バッファーの長さ」を参照してください。
戻り値
関数が成功した場合、戻り値はNERR_Success。
関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。
| リターン コード | 説明 |
|---|---|
|
ユーザーには、要求された情報へのアクセス権がありません。 |
|
Level パラメーターは無効な値を指定します。 |
|
その他のエントリを使用できます。 つまり、 SortedBuffer パラメーターで返される最後のエントリは、使用できる最後のエントリではありません。 追加のエントリを取得するには、SortedBuffer の最後のエントリのnext_index メンバーで返される値に Index パラメーターを設定して、NetQueryDisplayInformation を再度呼び出します。 NetQueryDisplayInformation を追加で呼び出してより多くのデータを取得する以外は、任意の目的で next_index メンバーの値を使用しないでください。 |
解説
Active Directory を実行しているドメイン コントローラーでこの関数を呼び出すと、 セキュリティ保護可能なオブジェクトのアクセス制御リスト (ACL) に基づいてアクセスが許可または拒否されます。 既定の ACL では、"Pre-Windows 2000 互換アクセス" グループのすべての認証済みユーザーとメンバーに情報の表示が許可されます。 メンバー サーバーまたはワークステーションでこの関数を呼び出すと、すべての認証済みユーザーが情報を表示できます。 これらのプラットフォームでの匿名アクセスと匿名アクセスの制限については、「 ネットワーク管理機能のセキュリティ要件」を参照してください。 ACL、ACE、およびアクセス トークンの詳細については、「存取控制 モデル」を参照してください。
NetQueryDisplayInformation 関数は、呼び出し元が読み取りアクセス権を持つ情報のみを返します。 呼び出し元は、Domain オブジェクトへのリスト コンテンツ アクセス権と、システム コンテナーにある SAM サーバー オブジェクトに対する SAM ドメイン全体のアクセス権を列挙する必要があります。
NetQueryDisplayInformation 関数と NetGetDisplayInformationIndex 関数は、ユーザー アカウントとグループ アカウントを列挙するための効率的なメカニズムを提供します。 可能な場合は、NetUserEnum 関数または NetGroupEnum 関数の代わりに、これらの関数を使用します。
信頼しているドメインまたはメンバー コンピューター アカウントを列挙するには、 NetUserEnum を呼び出し、必要なアカウント情報を取得するための適切なフィルター値を指定します。 信頼されたドメインを列挙するには、 LsaEnumerateTrustedDomains または LsaEnumerateTrustedDomainsEx 関数を 呼び出します。
この関数によって返されるエントリの数は、ルート ドメイン オブジェクトにあるセキュリティ記述子によって異なります。 API は、ユーザーのアクセス特権に応じて、最初の 100 エントリまたはドメイン内のエントリのセット全体を返します。 この動作を制御するために使用される ACE は "SAM-Enumerate-Entire-Domain" であり、既定では認証済みユーザーに付与されます。 管理者は、ユーザーがドメイン全体を列挙できるように、この設定を変更できます。
NetQueryDisplayInformation を呼び出すたびに、最大 100 個のオブジェクトが返されます。 NetQueryDisplayInformation 関数を呼び出してドメイン アカウント情報を列挙すると、パフォーマンスの面でコストがかかる場合があります。 Active Directory 用のプログラミングを行う場合は、 IDirectorySearch インターフェイスのメソッドを使用して、ドメインに対してページクエリを行うことができます。 詳細については、「 IDirectorySearch::SetSearchPreference 」および 「IDirectorySearch::ExecuteSearch」を参照してください。 信頼されたドメインを列挙するには、 LsaEnumerateTrustedDomainsEx 関数を 呼び出します。
例
次のコード サンプルは、 NetQueryDisplayInformation 関数の呼び出しを使用してグループ アカウント情報を返す方法を示しています。 ユーザーがサーバー名を指定した場合、最初に MultiByteToWideChar 関数を呼び出して名前を Unicode に変換します。 このサンプルでは NetQueryDisplayInformation を呼び出し、情報レベル 3 (NET_DISPLAY_GROUP) を指定してグループ アカウント情報を取得します。 返すエントリがある場合、サンプルはデータを返し、グループ情報を出力します。 最後に、コード サンプルでは、情報バッファーに割り当てられたメモリを解放します。
#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <stdio.h>
#include <lm.h>
#pragma comment(lib, "netapi32.lib")
void main( int argc, char *argv[ ] )
{
PNET_DISPLAY_GROUP pBuff, p;
DWORD res, dwRec, i = 0;
//
// You can pass a NULL or empty string
// to retrieve the local information.
//
TCHAR szServer[255]=TEXT("");
if(argc > 1)
//
// Check to see if a server name was passed;
// if so, convert it to Unicode.
//
MultiByteToWideChar(CP_ACP, 0, argv[1], -1, szServer, 255);
do // begin do
{
//
// Call the NetQueryDisplayInformation function;
// specify information level 3 (group account information).
//
res = NetQueryDisplayInformation(szServer, 3, i, 1000, MAX_PREFERRED_LENGTH, &dwRec, (PVOID*) &pBuff);
//
// If the call succeeds,
//
if((res==ERROR_SUCCESS) || (res==ERROR_MORE_DATA))
{
p = pBuff;
for(;dwRec>0;dwRec--)
{
//
// Print the retrieved group information.
//
printf("Name: %S\n"
"Comment: %S\n"
"Group ID: %u\n"
"Attributes: %u\n"
"--------------------------------\n",
p->grpi3_name,
p->grpi3_comment,
p->grpi3_group_id,
p->grpi3_attributes);
//
// If there is more data, set the index.
//
i = p->grpi3_next_index;
p++;
}
//
// Free the allocated memory.
//
NetApiBufferFree(pBuff);
}
else
printf("Error: %u\n", res);
//
// Continue while there is more data.
//
} while (res==ERROR_MORE_DATA); // end do
return;
}
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | lmaccess.h (include Lm.h) |
| Library | Netapi32.lib |
| [DLL] | Netapi32.dll |