NetUserGetLocalGroups 関数 (lmaccess.h)
NetUserGetLocalGroups 関数は、指定したユーザーが属するローカル グループの一覧を取得します。
構文
NET_API_STATUS NET_API_FUNCTION NetUserGetLocalGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[in] DWORD flags,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries
);
パラメーター
[in] servername
関数を実行するリモート サーバーの DNS または NetBIOS 名を指定する定数文字列へのポインター。 このパラメーターが NULL の場合は、ローカル コンピューターが使用されます。
[in] username
ローカル グループ メンバーシップ情報を返すユーザーの名前を指定する定数文字列へのポインター。 文字列が DomainName UserName\ という形式の場合、そのドメインでユーザー名が見つかると想定されます。 文字列が UserName 形式の場合、 servernameパラメーターで 指定されたサーバーでユーザー名が見つかると想定されます。 詳細については、「解説」を参照してください。
[in] level
データの情報レベル。 このパラメーターには、次の値を指定できます。
| 値 | 説明 |
|---|---|
|
ユーザーが属しているローカル グループの名前を返します。 bufptr パラメーターは、LOCALGROUP_USERS_INFO_0構造体の配列を指します。 |
[in] flags
操作に影響を与えるフラグのビットマスク。 現時点では、定義されている値のみが LG_INCLUDE_INDIRECTされています。 このビットが設定されている場合、関数は、ユーザーが間接的にメンバーであるローカル グループの名前も返します (つまり、ユーザー自体が 1 つ以上のローカル グループのメンバーであるグローバル グループのメンバーシップを持っています)。
[out] bufptr
データを受信するバッファーへのポインター。 このデータの形式は、 level パラメーターの値によって異なります。 このバッファーはシステムによって割り当てられ、 NetApiBufferFree 関数を使用して解放する必要があります。 関数が ERROR_MORE_DATA で失敗した場合でも、バッファーを解放する必要があることに注意してください。
[in] prefmaxlen
返されるデータの推奨される最大長 (バイト単位)。 このパラメーター にMAX_PREFERRED_LENGTH を指定した場合、関数はデータに必要なメモリ量を割り当てます。 このパラメーターに別の値を指定すると、関数から返されるバイト数を制限できます。 バッファー サイズが不十分で、すべてのエントリを保持できる場合、関数は ERROR_MORE_DATAを返します。 詳細については、「 ネットワーク管理機能バッファー 」および「 ネットワーク管理機能バッファーの長さ」を参照してください。
[out] entriesread
実際に列挙された要素の数を受け取る値へのポインター。
[out] totalentries
列挙された可能性のあるエントリの合計数を受け取る値へのポインター。
戻り値
関数が成功した場合、戻り値はNERR_Success。
関数が失敗した場合、戻り値には次のいずれかのエラー コードを指定できます。
| リターン コード | 説明 |
|---|---|
|
ユーザーは、要求された情報へのアクセス権を持っていません。 このエラーは、 servername パラメーターの末尾に空白がある場合にも返されます。 |
|
システム コール レベルが正しくありません。 level パラメーターが 0 として指定されていない場合、このエラーが返されます。 |
|
パラメーターが正しくありません。 flags パラメーターに LG_INCLUDE_INDIRECT 以外の値が含まれている場合、このエラーが返されます。 |
|
その他のエントリを使用できます。 すべてのエントリを受信するのに十分な大きさのバッファーを指定します。 |
|
操作を完了するために使用できるメモリが不足していました。 |
|
ドメイン コントローラーが見つかりませんでした。 |
|
ユーザーが見つかりませんでした。 このエラーは、 ユーザー名 が見つからなかった場合に返されます。 |
|
RPC サーバーが利用できません。 このエラーは、 servername パラメーターが見つからなかった場合に返されます。 |
解説
Active Directory のプログラミングを行う場合は、特定の Active Directory サービス インターフェイス (ADSI) メソッドを呼び出して、ネットワーク管理ユーザー関数を呼び出すことで実現できるのと同じ機能を実現できる場合があります。 詳細については、「 IADsUser と IADsComputer」を参照してください。
Active Directory を実行しているドメイン コントローラーでこの関数を呼び出すと、 セキュリティ保護可能なオブジェクトのアクセス制御リスト (ACL) に基づいてアクセスが許可または拒否されます。 既定の ACL では、"Pre-Windows 2000 互換アクセス" グループのすべての認証済みユーザーとメンバーに情報の表示が許可されます。 メンバー サーバーまたはワークステーションでこの関数を呼び出すと、すべての認証済みユーザーが情報を表示できます。 これらのプラットフォームでの匿名アクセスと匿名アクセスの制限については、「 ネットワーク管理機能のセキュリティ要件」を参照してください。 ACL、ACE、およびアクセス トークンの詳細については、「存取控制 モデル」を参照してください。
Domain オブジェクトのセキュリティ記述子は、この関数のアクセスチェックを実行するために使用されます。 呼び出し元には、Domain オブジェクトに対する読み取りプロパティアクセス許可が必要です。
指定したユーザーが属するグローバル グループの一覧を取得するには、 NetUserGetGroups 関数を呼び出します。
ユーザー アカウント名は 20 文字に制限され、グループ名は 256 文字に制限されます。 さらに、アカウント名をピリオドで終えることはできません。また、コンマまたは"、/、、[、]、:、|<>、+、=、;、?、*のいずれかの印刷可能な文字を含めることはできません。 名前には、印刷できない 1 から 31 の範囲の文字を含めることもできます。
例
次のコード サンプルは、 NetUserGetLocalGroups 関数の呼び出しを使用して、ユーザーが属するローカル グループの一覧を取得する方法を示しています。 このサンプルでは、情報レベル 0 (LOCALGROUP_USERS_INFO_0) を指定して NetUserGetLocalGroups を呼び出します。 このサンプルでは、エントリをループ処理し、ユーザーがメンバーシップを持つ各ローカル グループの名前を出力します。 使用可能なすべてのエントリが列挙されていない場合は、実際に列挙されたエントリの数と使用可能なエントリの合計数も出力されます。 最後に、コード サンプルでは、情報バッファーに割り当てられたメモリを解放します。
#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[])
{
LPLOCALGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
DWORD dwFlags = LG_INCLUDE_INDIRECT ;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
NET_API_STATUS nStatus;
if (argc != 3)
{
fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
exit(1);
}
//
// Call the NetUserGetLocalGroups function
// specifying information level 0.
//
// The LG_INCLUDE_INDIRECT flag specifies that the
// function should also return the names of the local
// groups in which the user is indirectly a member.
//
nStatus = NetUserGetLocalGroups(argv[1],
argv[2],
dwLevel,
dwFlags,
(LPBYTE *) &pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPLOCALGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nLocal group(s):\n");
//
// Loop through the entries and
// print the names of the local groups
// to which the user belongs.
//
for (i = 0; i < dwEntriesRead; i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
wprintf(L"\t-- %s\n", pTmpBuf->lgrui0_name);
pTmpBuf++;
dwTotalCount++;
}
}
//
// If all available entries were
// not enumerated, print the number actually
// enumerated and the total number available.
//
if (dwEntriesRead < dwTotalEntries)
fprintf(stderr, "\nTotal entries: %d", dwTotalEntries);
//
// Otherwise, just print the total.
//
printf("\nEntries enumerated: %d\n", dwTotalCount);
}
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated memory.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | lmaccess.h (include Lm.h) |
| Library | Netapi32.lib |
| [DLL] | Netapi32.dll |