DsCrackNamesA-Funktion (ntdsapi.h)

Artikel
08/25/2023

Die DsCrackNames-Funktion konvertiert ein Array von Verzeichnisdienstobjektnamen aus einem Format in ein anderes. Mit der Namenskonvertierung können Clientanwendungen mehrere Namen zuordnen, die zum Identifizieren verschiedener Verzeichnisdienstobjekte verwendet werden. Benutzerobjekte können beispielsweise durch SAM-Kontonamen (Domänenbenutzername\), Benutzerprinzipalname (UserName@Domain.com) oder Distinguished Name identifiziert werden.

Syntax

NTDSAPI DWORD DsCrackNamesA(
  [in]  HANDLE           hDS,
  [in]  DS_NAME_FLAGS    flags,
  [in]  DS_NAME_FORMAT   formatOffered,
  [in]  DS_NAME_FORMAT   formatDesired,
  [in]  DWORD            cNames,
  [in]  const LPCSTR     *rpNames,
  [out] PDS_NAME_RESULTA *ppResult
);

Parameter

[in] hDS

Enthält ein Verzeichnisdiensthandle, das von der FUNKTION DSBind oder DSBindWithCred abgerufen wurde. Wenn FlagsDS_NAME_FLAG_SYNTACTICAL_ONLY enthalten, kann hDSNULL sein.

[in] flags

Enthält mindestens einen der DS_NAME_FLAGS-Werte , mit dem bestimmt wird, wie die Namenssyntax geknackt wird.

[in] formatOffered

Enthält einen der DS_NAME_FORMAT-Werte , der das Format der Eingabenamen angibt.

Der DS_LIST_NCS-Wert kann auch für diesen Parameter übergeben werden. Dies bewirkt , dass DsCrackNames die distinguished Names aller Benennungskontexte in der aktuellen Gesamtstruktur zurückgibt. Der parameter formatDesired wird ignoriert. cNames muss mindestens eins sein, und alle Zeichenfolgen in rpNames müssen eine Länge größer als 0 Zeichen haben. Der Inhalt der rpNames-Zeichenfolgen wird ignoriert.

Beachten SieDS_LIST_NCS in einer veröffentlichten Headerdatei nicht definiert ist. Um diesen Wert zu verwenden, definieren Sie ihn im genauen Format, das unten gezeigt wird.

#ifndef DS_LIST_NCS
    #define DS_LIST_NCS 0xfffffff6
#endif

[in] formatDesired

Enthält einen der DS_NAME_FORMAT-Werte , der das Format der Ausgabenamen angibt. Der DS_SID_OR_SID_HISTORY_NAME Wert wird nicht unterstützt.

[in] cNames

Enthält die Anzahl der Elemente im rpNames-Array .

[in] rpNames

Zeiger auf ein Array von Zeigern auf NULL-beendete Zeichenfolgen, die namen enthalten, die konvertiert werden sollen.

[out] ppResult

Zeiger auf einen PDS_NAME_RESULT-Wert , der eine DS_NAME_RESULT-Struktur empfängt, die die konvertierten Namen enthält. Der Aufrufer muss diesen Arbeitsspeicher freigeben, wenn er nicht mehr benötigt wird, indem er DsFreeNameResult aufruft.

Rückgabewert

Gibt einen Win32-Fehlerwert, einen RPC-Fehlerwert oder einen der folgenden Werte zurück.

Hinweise

Der Erfolg der Namenskonvertierungsanforderung hängt davon ab, wo der Client gebunden ist. Clients binden mithilfe einer Variante von DsBind an bestimmte Instanzen des Verzeichnisdiensts. Wenn sie an einen globalen Katalog gebunden ist, ist der Bereich der Namenszuordnung die gesamte Gesamtstruktur. Wenn sie nicht an einen globalen Katalog gebunden ist, ist der Bereich der Namenszuordnung die Domäne, die nicht von einem globalen Katalog für diesen Domänencontroller abgedeckt wird. Wenn nicht an einen globalen Katalog gebunden und kein Name gefunden wird, aber der Eingabename die Domäne eindeutig identifiziert und sich diese Domäne in der Gesamtstruktur befindet, identifizieren die Rückgabedaten den DNS-Domänennamen für die domäne von Interesse. Es wird erwartet, dass Clients diese Daten verwenden, um an den richtigen Domänencontroller oder globalen Katalog zu binden und DsCrackNames mit dem neuen Bindungshandle erneut aufzurufen.

Der Rückgabewert von DsCrackNames gibt Fehler an, z. B. ungültige Parameter oder unzureichender Arbeitsspeicher. Probleme beim Konvertieren einzelner Namen werden jedoch im status Member der DS_NAME_RESULT_ITEM Struktur gemeldet, die für jeden Eingabenamen zurückgegeben wird.

Hinweis Verwechseln Sie die Werte der Formatelemente des formatOffered-Parameters , der von der DsCrackNames-Funktion verwendet wird, nicht mit den ähnlich benannten Formatelementen, die in der ADS_NAME_TYPE_ENUM Enumeration definiert sind, die von der IADsNameTranslate-Schnittstelle verwendet wird. Die beiden Sätze von Elementformaten sind nicht gleichwertig und nicht austauschbar.

Hinweis

Der ntdsapi.h-Header definiert DsCrackNames 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 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 Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	ntdsapi.h
Bibliothek	Ntdsapi.lib
DLL	Ntdsapi.dll