LsaLookupNames 関数 (ntsecapi.h)

[アーティクル]
03/08/2023

LsaLookupNames 関数は、ユーザー、グループ、またはローカルグループ名の配列に対応するセキュリティ識別子 (SID) を取得します。

LsaLookupNames 関数は LsaLookupNames2 関数に置き換えられます。アプリケーションでは、今後の互換性を確保するために LsaLookupNames2 関数を使用する必要があります。

LsaLookupNames 関数は、コンピューターアカウントを取得することもできます。

構文

NTSTATUS LsaLookupNames(
  [in]  LSA_HANDLE                  PolicyHandle,
  [in]  ULONG                       Count,
  [in]  PLSA_UNICODE_STRING         Names,
  [out] PLSA_REFERENCED_DOMAIN_LIST *ReferencedDomains,
  [out] PLSA_TRANSLATED_SID         *Sids
);

パラメーター

[in] PolicyHandle

Policy オブジェクトへのハンドル。ハンドルには、POLICY_LOOKUP_NAMESアクセス権が必要です。詳細については、「ポリシーオブジェクトハンドルを開く」を参照してください。

[in] Count

Names 配列内の名前の数を指定 します 。これは Sids 配列で返されるエントリの数でもあります。この値は 1000 以下である必要があります。

[in] Names

参照する名前を含む LSA_UNICODE_STRING 構造体の配列へのポインター。これらの構造体の文字列には、ユーザー、グループ、またはローカルグループアカウントの名前、またはドメインの名前を指定できます。ドメイン名には、DNS ドメイン名または NetBIOS ドメイン名を指定できます。

名前文字列の形式の詳細については、「解説」を参照してください。

[out] ReferencedDomains

LSA_REFERENCED_DOMAIN_LIST構造体へのポインターを受け取ります。この構造体の Domains メンバーは、名前が見つかった各ドメインのエントリを含む配列です。 Sids 配列内の各エントリの DomainIndex メンバーは、名前が見つかったドメインの Domains 配列エントリのインデックスです。

返されたポインターの使用が完了したら、を呼び出してメモリを解放します。
LsaFreeMemory 関数。このメモリは、STATUS_NONE_MAPPEDまたはSTATUS_SOME_NOT_MAPPEDのいずれかのエラーコードで関数が失敗した場合でも解放する必要があります

[out] Sids

LSA_TRANSLATED_SID構造体の配列へのポインターを受け取ります。 Sids 配列の各エントリには、Names 配列内の対応するエントリの SID 情報が含まれています。

戻り値

関数が成功した場合、関数は次のいずれかの NTSTATUS 値を返します。

値	説明
STATUS_SOME_NOT_MAPPED	一部の名前を翻訳できませんでした。これは情報レベルの戻り値です。
STATUS_SUCCESS	すべての名前が見つかり、正常に翻訳されました。

関数が失敗した場合、戻り値は次の NTSTATUS 値または LSA ポリシー関数の戻り値のいずれかになります。

値	説明
STATUS_NONE_MAPPED	どの名前も翻訳されませんでした。
STATUS_TOO_MANY_NAMES	Names 配列パラメーターが大きすぎます。

LsaNtStatusToWinError 関数を使用して、NTSTATUS コードを Windows エラーコードに変換します。

解説

警告

独立した名前 (たとえば、user_name) ではなく、完全修飾アカウント名 (たとえば、domain_name\user_name) を使用します。完全修飾名は明確であり、検索を実行するとパフォーマンスが向上します。この関数では、完全修飾 DNS 名 (たとえば、example.example.com\user_name) とユーザープリンシパル名 (UPN) もサポートされます (例: someone@example.com)。

警告

分離名の制限事項の詳細については、 LsaLookupNames2 のドキュメントを参照してください。

LsaLookupNames 関数は、次のアルゴリズムを使用してアカウント名を変換します。

名前を翻訳するには

名前が Local や Interactive などの既知の名前の場合、関数は対応する既知のセキュリティ識別子 (SID) を返します。
名前が組み込みドメインの名前である場合、関数はそのドメインの SID を返します。
名前がアカウントドメインの名前の場合、関数はそのドメインの SID を返します。
名前がプライマリドメインの名前の場合、関数はそのドメインの SID を返します。
名前が信頼されたドメインの名前の 1 つである場合、関数はそのドメインの SID を返します。
名前が組み込みドメインのユーザー、グループ、またはローカルグループアカウントである場合、関数はそのアカウントの SID を返します。
名前がローカルシステムのアカウントドメイン内のユーザー、グループ、またはローカルグループアカウントである場合、関数はそのアカウントの SID を返します。
キャッシュに名前が見つかった場合、関数はそのアカウントの SID を返します。
名前がプライマリドメイン内のユーザー、グループ、またはローカルグループである場合、関数はそのアカウントの SID を返します。
プライマリドメインを調べた後、プライマリドメインは各信頼されたドメインを検索します。
それ以外の場合、名前は変換されません。

LsaLookupNames は、ローカルアカウント、ローカルドメインアカウント、明示的に信頼されたドメインアカウントを検索するだけでなく、Windows フォレスト内の任意のドメイン内の任意のアカウントの名前を検索できます。

例

この関数を呼び出す例については、「名前と SID 間の変換」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	ntsecapi.h
Library	Advapi32.lib
[DLL]	Advapi32.dll