DsCrackNamesA-Funktion (ntdsapi.h)

Artikel
11/20/2024

Die DsCrackNames--Funktion konvertiert ein Array von Verzeichnisdienstobjektnamen aus einem Format in ein anderes. Die Namenskonvertierung ermöglicht Clientanwendungen die Zuordnung zwischen den mehreren Namen, die zum Identifizieren verschiedener Verzeichnisdienstobjekte verwendet werden. Beispielsweise können Benutzerobjekte durch SAM-Kontonamen (Domain\UserName), 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 entweder vom DSBind- oder DSBindWithCredWithCred-Funktion abgerufen wird. Wenn FlagsDS_NAME_FLAG_SYNTACTICAL_ONLYenthält, kann hDS-NULL-sein.

[in] flags

Enthält einen oder mehrere der DS_NAME_FLAGS Werte, die verwendet werden, um zu bestimmen, wie die Namenssyntax zerbrochen wird.

[in] formatOffered

Enthält einen der DS_NAME_FORMAT Werte, die das Format der Eingabenamen identifiziert.

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

HinweisDS_LIST_NCS in einer veröffentlichten Headerdatei nicht definiert ist. Um diesen Wert zu verwenden, definieren Sie ihn im genauen Format unten.

#ifndef DS_LIST_NCS
    #define DS_LIST_NCS 0xfffffff6
#endif

[in] formatDesired

Enthält einen der DS_NAME_FORMAT Werte, die das Format der Ausgabenamen identifiziert. 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

Zeigen Sie auf ein Array von Zeigern auf null beendete Zeichenfolgen, die Namen enthalten, die konvertiert werden sollen.

[out] ppResult

Zeigen Sie auf einen PDS_NAME_RESULT Wert, der eine DS_NAME_RESULT Struktur empfängt, die die konvertierten Namen enthält. Der Aufrufer muss diesen Speicher freigeben, wenn er nicht mehr benötigt wird, indem DsFreeNameResultaufgerufen wird.

Rückgabewert

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

Bemerkungen

Der Erfolg der Namenskonvertierungsanforderung hängt davon ab, wo der Client gebunden ist. Clients binden an bestimmte Instanzen des Verzeichnisdiensts mit einer variante von DsBind. 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 keine Bindung an einen globalen Katalog und kein Name gefunden wird, aber der Eingabename eindeutig seine Domäne identifiziert und sich diese Domäne in der Gesamtstruktur befindet, identifiziert die Rückgabedaten den DNS-Domänennamen für die Domäne von Interesse. Clients werden erwartet, dass diese Daten verwendet werden, um eine Bindung an den richtigen Domänencontroller oder globalen Katalog herzustellen und DsCrackName s erneut mit dem neuen Bindungshandle aufzurufen.

Der Rückgabewert von DsCrackNames gibt Fehler wie ungültige Parameter oder unzureichenden Arbeitsspeicher an. 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 nicht die Werte der Formatelemente des formatOffered Parameters, der von der DsCrackNames--Funktion mit den ähnlich benannten Formatelementen verwendet wird, wie in der ADS_NAME_TYPE_ENUM Enumeration definiert, die von der IADsNameTranslate Schnittstelle verwendet wird. Die beiden Sätze von Elementformaten sind nicht gleichwertig und können nicht austauschbar sein.

Anmerkung

Der ntdsapi.h-Header definiert DsCrackNames 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 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
mindestens unterstützte Client-	Windows Vista
mindestens unterstützte Server-	Windows Server 2008
Zielplattform-	Fenster
Header-	ntdsapi.h
Library	Ntdsapi.lib
DLL-	Ntdsapi.dll