LookupAccountNameA-Funktion (winbase.h)

Artikel
03/06/2024

Die LookupAccountName-Funktion akzeptiert den Namen eines Systems und eines Kontos als Eingabe. Es ruft einen Sicherheitsbezeichner (SID ) für das Konto und den Namen der Domäne ab, in der das Konto gefunden wurde.

Die LsaLookupNames-Funktion kann auch Computerkonten abrufen.

Syntax

BOOL LookupAccountNameA(
  [in, optional]  LPCSTR        lpSystemName,
  [in]            LPCSTR        lpAccountName,
  [out, optional] PSID          Sid,
  [in, out]       LPDWORD       cbSid,
  [out, optional] LPSTR         ReferencedDomainName,
  [in, out]       LPDWORD       cchReferencedDomainName,
  [out]           PSID_NAME_USE peUse
);

Parameter

[in, optional] lpSystemName

Ein Zeiger auf eine NULL-Zeichenfolge, die den Namen des Systems angibt. Diese Zeichenfolge kann der Name eines Remotecomputers sein. Wenn diese Zeichenfolge NULL ist, beginnt die Kontonamenübersetzung auf dem lokalen System. Wenn der Name im lokalen System nicht aufgelöst werden kann, versucht diese Funktion, den Namen mithilfe von Domänencontrollern aufzulösen, die vom lokalen System vertrauenswürdig sind. Geben Sie im Allgemeinen nur dann einen Wert für lpSystemName an, wenn sich das Konto in einer nicht vertrauenswürdigen Domäne befindet und der Name eines Computers in dieser Domäne bekannt ist.

[in] lpAccountName

Ein Zeiger auf eine NULL-Zeichenfolge, die den Kontonamen angibt.

Verwenden Sie eine vollqualifizierte Zeichenfolge im format domain_name\user_name, um sicherzustellen, dass LookupAccountName das Konto in der gewünschten Domäne findet.

[out, optional] Sid

Ein Zeiger auf einen Puffer, der die SID-Struktur empfängt, die dem Kontonamen entspricht, auf den der lpAccountName-Parameter verweist. Wenn dieser Parameter NULL ist, muss cbSid null sein.

[in, out] cbSid

Ein Zeiger auf eine Variable. Bei der Eingabe gibt dieser Wert die Größe des Sid-Puffers in Bytes an. Wenn die Funktion fehlschlägt, weil der Puffer zu klein ist oder cbSid null ist, empfängt diese Variable die erforderliche Puffergröße.

[out, optional] ReferencedDomainName

Ein Zeiger auf einen Puffer, der den Namen der Domäne empfängt, in der der Kontoname gefunden wird. Für Computer, die keiner Domäne angehören, empfängt dieser Puffer den Computernamen. Wenn dieser Parameter NULL ist, gibt die Funktion die erforderliche Puffergröße zurück.

[in, out] cchReferencedDomainName

Ein Zeiger auf eine Variable. Bei der Eingabe gibt dieser Wert die Größe des Puffers ReferencedDomainName in TCHARs an. Wenn die Funktion fehlschlägt, weil der Puffer zu klein ist, empfängt diese Variable die erforderliche Puffergröße, einschließlich des beendenden NULL-Zeichens . Wenn der ReferencedDomainName-ParameterNULL ist, muss dieser Parameter 0 sein.

[out] peUse

Ein Zeiger auf einen SID_NAME_USE aufgezählten Typ, der den Typ des Kontos angibt, wenn die Funktion zurückgegeben wird.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero zurück.

Wenn die Funktion fehlschlägt, gibt sie null zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Hinweise

Die LookupAccountName-Funktion versucht, eine SID für den angegebenen Namen zu finden, indem zuerst eine Liste bekannter SIDs überprüft wird. Wenn der Name nicht einer bekannten SID entspricht, überprüft die Funktion integrierte und administrativ definierte lokale Konten. Als Nächstes überprüft die Funktion die primäre Domäne. Wenn der Name dort nicht gefunden wird, werden vertrauenswürdige Domänen überprüft.

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

Zusätzlich zum Suchen nach lokalen Konten, lokalen Domänenkonten und explizit vertrauenswürdigen Domänenkonten kann LookupAccountName den Namen für jedes Konto in jeder Domäne in der Gesamtstruktur suchen.

Hinweis

Der winbase.h-Header definiert LookupAccountName als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (einschließlich Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll