LookupAccountSidA-Funktion (winbase.h)

Artikel
03/03/2024

Die LookupAccountSid-Funktion akzeptiert eine Sicherheits-ID (SID) als Eingabe. Es ruft den Namen des Kontos für diese SID und den Namen der ersten Domäne ab, in der diese SID gefunden wurde.

Syntax

BOOL LookupAccountSidA(
  [in, optional]  LPCSTR        lpSystemName,
  [in]            PSID          Sid,
  [out, optional] LPSTR         Name,
  [in, out]       LPDWORD       cchName,
  [out, optional] LPSTR         ReferencedDomainName,
  [in, out]       LPDWORD       cchReferencedDomainName,
  [out]           PSID_NAME_USE peUse
);

Parameter

[in, optional] lpSystemName

Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Zielcomputer angibt. Diese Zeichenfolge kann der Name eines Remotecomputers sein. Wenn dieser Parameter NULL ist, beginnt die Übersetzung des Kontonamens im lokalen System. Wenn der Name auf dem lokalen System nicht aufgelöst werden kann, versucht diese Funktion, den Namen mithilfe von Domänencontrollern aufzulösen, die vom lokalen System als vertrauenswürdig eingestuft werden. 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] Sid

Ein Zeiger auf die SID , die gesucht werden soll.

[out, optional] Name

Ein Zeiger auf einen Puffer, der eine NULL-endende Zeichenfolge empfängt, die den Kontonamen enthält, der dem lpSid-Parameter entspricht.

[in, out] cchName

Gibt bei der Eingabe die Größe des puffers lpName in TCHARs an. Wenn die Funktion fehlschlägt, weil der Puffer zu klein ist oder cchName null ist, empfängt cchName die erforderliche Puffergröße, einschließlich des abschließenden NULL-Zeichens .

[out, optional] ReferencedDomainName

Ein Zeiger auf einen Puffer, der eine NULL-endende Zeichenfolge empfängt, die den Namen der Domäne enthält, in der der Kontoname gefunden wurde.

Auf einem Server ist der Domänenname, der für die meisten Konten in der Sicherheitsdatenbank des lokalen Computers zurückgegeben wird, der Name der Domäne, für die der Server ein Domänencontroller ist.

Auf einer Arbeitsstation ist der Domänenname, der für die meisten Konten in der Sicherheitsdatenbank des lokalen Computers zurückgegeben wird, der Name des Computers ab dem letzten Start des Systems (umgekehrte Schrägstriche sind ausgeschlossen). Wenn sich der Name des Computers ändert, wird der alte Name weiterhin als Domänenname zurückgegeben, bis das System neu gestartet wird.

Einige Konten sind vom System vordefiniert. Der für diese Konten zurückgegebene Domänenname lautet BUILTIN.

[in, out] cchReferencedDomainName

Gibt bei der Eingabe die Größe des Puffers lpReferencedDomainName in TCHARs an. Wenn die Funktion fehlschlägt, weil der Puffer zu klein ist oder cchReferencedDomainName null ist, empfängt cchReferencedDomainName die erforderliche Puffergröße, einschließlich des abschließenden NULL-Zeichens .

[out] peUse

Ein Zeiger auf eine Variable, die einen SID_NAME_USE Wert empfängt, der den Typ des Kontos angibt.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion ungleich null zurück.

Wenn die Funktion fehlschlägt, wird null zurückgegeben. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die LookupAccountSid-Funktion versucht, einen Namen für die angegebene SID zu finden, indem zuerst eine Liste bekannter SIDs überprüft wird. Wenn die angegebene SID 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. Sicherheits-IDs, die von der primären Domäne nicht erkannt werden, werden anhand der vertrauenswürdigen Domänen überprüft, die ihren SID-Präfixen entsprechen.

Wenn die Funktion keinen Kontonamen für die SID finden kann, gibt GetLastError ERROR_NONE_MAPPED zurück. Dies kann auftreten, wenn ein Netzwerktimeout verhindert, dass die Funktion den Namen findet. Sie tritt auch für SIDs auf, die keinen entsprechenden Kontonamen haben, z. B . eine Anmelde-SID , die eine Anmeldesitzung identifiziert.

Zusätzlich zur Suche nach SIDs für lokale Konten, lokale Domänenkonten und explizit vertrauenswürdige Domänenkonten kann LookupAccountSid SIDs für jedes Konto in einer beliebigen Domäne in der Gesamtstruktur suchen, einschließlich SIDs, die nur im SIDhistory-Feld eines Kontos in der Gesamtstruktur angezeigt werden. Das SIDhistory-Feld speichert ehemalige SIDs eines Kontos, das aus einer anderen Domäne verschoben wurde. Um eine SID zu suchen, fragt LookupAccountSid den globalen Katalog der Gesamtstruktur ab.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Suchen nach einer SID in einem Zugriffstoken.

Hinweis

Der winbase.h-Header definiert LookupAccountSid als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, 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 (Windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll