LsaLookupNames-Funktion (ntsecapi.h)

Artikel
08/25/2023

Die LsaLookupNames-Funktion ruft die Sicherheitsbezeichner (SIDs) ab, die einem Array von Benutzer-, Gruppen- oder lokalen Gruppennamen entsprechen.

Die LsaLookupNames-Funktion wird durch die LsaLookupNames2-Funktion ersetzt. Anwendungen sollten die LsaLookupNames2-Funktion verwenden, um zukünftige Kompatibilität sicherzustellen.

Die LsaLookupNames-Funktion kann auch Computerkonten abrufen.

Syntax

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
);

Parameter

[in] PolicyHandle

Ein Handle für ein Policy-Objekt . Das Handle muss über das POLICY_LOOKUP_NAMES-Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Öffnen eines Richtlinienobjekthandles.

[in] Count

Gibt die Anzahl der Namen im Array Names an. Dies ist auch die Anzahl der im Sids-Array zurückgegebenen Einträge. Dieser Wert muss kleiner oder gleich 1000 sein.

[in] Names

Zeiger auf ein Array von LSA_UNICODE_STRING Strukturen, die die nachzuschlagenden Namen enthalten. Die Zeichenfolgen in diesen Strukturen können die Namen von Benutzer-, Gruppen- oder lokalen Gruppenkonten oder die Namen von Domänen sein. Domänennamen können DNS-Domänennamen oder NetBIOS-Domänennamen sein.

Weitere Informationen zum Format der Namenszeichenfolgen finden Sie unter Hinweise.

[out] ReferencedDomains

Empfängt einen Zeiger auf eine LSA_REFERENCED_DOMAIN_LIST-Struktur . Das Domänenmitglied dieser Struktur ist ein Array, das einen Eintrag für jede Domäne enthält, in der ein Name gefunden wurde. Das DomainIndex-Element jedes Eintrags im Sids-Array ist der Index des Domänenarrayeintrags für die Domäne, in der der Name gefunden wurde.

Wenn Sie mit der Verwendung des zurückgegebenen Zeigers fertig sind, geben Sie den Speicher frei, indem Sie den
LsaFreeMemory-Funktion . Dieser Arbeitsspeicher muss auch dann freigegeben werden, wenn die Funktion mit einem der Fehlercodes STATUS_NONE_MAPPED oder STATUS_SOME_NOT_MAPPED

[out] Sids

Empfängt einen Zeiger auf ein Array von LSA_TRANSLATED_SID Strukturen. Jeder Eintrag im Sids-Array enthält die SID-Informationen für den entsprechenden Eintrag im Array Names .

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion einen der folgenden NTSTATUS-Werte zurück.

Wert	BESCHREIBUNG
STATUS_SOME_NOT_MAPPED	Einige der Namen konnten nicht übersetzt werden. Dies ist ein Rückgabewert auf Informationsebene.
STATUS_SUCCESS	Alle Namen wurden gefunden und erfolgreich übersetzt.

Wenn die Funktion fehlschlägt, ist der Rückgabewert der folgende NTSTATUS-Wert oder einer der Rückgabewerte der LSA-Richtlinienfunktion.

Wert	BESCHREIBUNG
STATUS_NONE_MAPPED	Keiner der Namen wurde übersetzt.
STATUS_TOO_MANY_NAMES	Der Name-Arrayparameter war zu groß.

Verwenden Sie die LsaNtStatusToWinError-Funktion , um den NTSTATUS-Code in einen Windows-Fehlercode zu konvertieren.

Bemerkungen

Warnung

Verwenden Sie vollqualifizierte Kontonamen (z. B. domain_name\user_name) anstelle isolierter Namen (z. B. user_name). Vollqualifizierte Namen sind eindeutig und bieten eine bessere Leistung, wenn die Suche durchgeführt wird. Diese Funktion unterstützt auch vollqualifizierte DNS-Namen (z. B. example.example.com\user_name) und Benutzerprinzipalnamen (UPN) (z. B someone@example.com. ).

Warnung

Weitere Informationen zu den Einschränkungen isolierter Namen finden Sie in der LsaLookupNames2-Dokumentation .

Die LsaLookupNames-Funktion verwendet den folgenden Algorithmus, um Kontonamen zu übersetzen.

So übersetzen Sie Namen

Wenn der Name ein bekannter Name ist, z. B. Local oder Interactive, gibt die Funktion den entsprechenden bekannten Sicherheitsbezeichner (SID) zurück.
Wenn der Name der integrierten Domäne ist, gibt die Funktion die SID dieser Domäne zurück.
Wenn der Name der Kontodomäne ist, gibt die Funktion die SID dieser Domäne zurück.
Wenn der Name der primären Domäne ist, gibt die Funktion die SID dieser Domäne zurück.
Wenn der Name einer der Namen der vertrauenswürdigen Domäne ist, gibt die Funktion die SID dieser Domäne zurück.
Wenn der Name ein Benutzer-, Gruppen- oder lokales Gruppenkonto in der integrierten Domäne ist, gibt die Funktion die SID dieses Kontos zurück.
Wenn der Name ein Benutzer-, Gruppen- oder lokales Gruppenkonto in der Kontodomäne des lokalen Systems ist, gibt die Funktion die SID dieses Kontos zurück.
Wenn der Name im Cache gefunden wird, gibt die Funktion die SID dieses Kontos zurück.
Wenn der Name ein Benutzer, eine Gruppe oder eine lokale Gruppe in der primären Domäne ist, gibt die Funktion die SID dieses Kontos zurück.
Nach der Suche in der primären Domäne sucht die primäre Domäne in jeder ihrer vertrauenswürdigen Domänen.
Andernfalls wird der Name nicht übersetzt.

Neben der Suche nach lokalen Konten, lokalen Domänenkonten und explizit vertrauenswürdigen Domänenkonten kann LsaLookupNames den Namen eines beliebigen Kontos in einer beliebigen Domäne in der Windows-Gesamtstruktur suchen.

Beispiele

Ein Beispiel, das diese Funktion aufruft, finden Sie unter Übersetzen zwischen Namen und SIDs.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ntsecapi.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll