DsGetSpnA-Funktion (ntdsapi.h)

Artikel
03/06/2024

Die DsGetSpn-Funktion erstellt ein Array aus mindestens einem Dienstprinzipalnamen (Service Principal Names, SPNs). Jeder Name im Array identifiziert eine instance eines Diensts. Diese SPNs können mithilfe der DsWriteAccountSpn-Funktion beim Verzeichnisdienst (DsWriteAccountSpn ) registriert werden.

Syntax

NTDSAPI DWORD DsGetSpnA(
  [in]           DS_SPN_NAME_TYPE ServiceType,
  [in]           LPCSTR           ServiceClass,
  [in, optional] LPCSTR           ServiceName,
  [in]           USHORT           InstancePort,
  [in]           USHORT           cInstanceNames,
  [in, optional] LPCSTR           *pInstanceNames,
  [in, optional] const USHORT     *pInstancePorts,
  [out]          DWORD            *pcSpn,
  [out]          LPSTR            **prpszSpn
);

Parameter

[in] ServiceType

Gibt das Format der zu erstellenden SPNs an. Der ServiceType-Parameter kann einen der folgenden Werte aufweisen.

DS_SPN_DNS_HOST, DS_SPN_DN_HOST, DS_SPN_NB_HOST

Die SPNs haben das folgende Format.

ServiceClass/ InstanceName: InstancePort

Der ServiceName-Parameter muss NULL sein. Dies ist das SPN-Format für einen hostbasierten Dienst, der Dienste bereitstellt, die mit dem Hostcomputer identifiziert werden. Die InstancePort-Komponente ist optional.

DS_SPN_DOMAIN, DS_SPN_NB_DOMAIN

Die SPNs haben das folgende Format.

ServiceClass/ InstanceName: InstancePort/ ServiceName

Der ServiceName-Parameter muss der DNS-Name oder DN einer Domäne sein. Dieses Format wird für einen replizierbaren Dienst verwendet, der Dienste für die angegebene Domäne bereitstellt.

DS_SPN_SERVICE

Die SPNs haben das folgende Format.

ServiceClass/ InstanceName: InstancePort/ ServiceName

Der ServiceName-Parameter muss ein kanonischer DN oder DNS-Name sein, der eine instance des Diensts identifiziert. Es kann sich z. B. um einen DNS-Namen eines SRV-Eintrags oder um den distinguished Name des Dienstverbindungspunkts für diesen Dienst instance.

[in] ServiceClass

Zeiger auf eine konstante null-beendete Zeichenfolge, die die Klasse des Diensts angibt; Beispiel: http. Im Allgemeinen kann dies eine beliebige Zeichenfolge sein, die für den Dienst eindeutig ist.

[in, optional] ServiceName

Zeiger auf eine konstante NULL-beendete Zeichenfolge, die den DNS-Namen oder distinguished Name (DN) des Diensts angibt. ServiceName ist für einen hostbasierten Dienst nicht erforderlich. Weitere Informationen finden Sie in der Beschreibung des ServiceType-Parameters für die möglichen Werte von ServiceName.

[in] InstancePort

Gibt die Portnummer des Diensts instance an. Wenn dieser Wert 0 ist, enthält der SPN keine Portnummer.

[in] cInstanceNames

Gibt die Anzahl der Elemente in den Arrays pInstanceNames und pInstancePorts an. Wenn dieser Wert nicht 0 ist, muss pInstanceNames auf ein Array von cInstanceNames-Zeichenfolgen verweisen, und pInstancePorts kann entweder NULL oder ein Zeiger auf ein Array von cInstanceNames-Portnummern sein. Wenn dieser Wert 0 ist, gibt DsGetSpn nur einen SPN im prpszSpn-Array zurück, und pInstanceNames und pInstancePorts werden ignoriert.

[in, optional] pInstanceNames

Zeiger auf ein Array von NULL-beendeten Zeichenfolgen, die zusätzliche instance Namen angeben (nicht für Hostnamen verwendet). Dieser Parameter wird ignoriert, wenn cInstanceNames null ist. In diesem Fall verwendet die Instanzname-Komponente des SPN standardmäßig den vollqualifizierten DNS-Namen des lokalen Computers oder den NetBIOS-Namen, wenn DS_SPN_NB_HOST oder DS_SPN_NB_DOMAIN angegeben ist.

[in, optional] pInstancePorts

Zeiger auf ein Array mit zusätzlichen instance Ports. Wenn dieser Wert nicht NULL ist, muss er auf ein Array von cInstanceNames-Portnummern verweisen. Wenn dieser Wert NULL ist, enthalten die SPNs keine Portnummer. Dieser Parameter wird ignoriert, wenn cInstanceNames null ist.

[out] pcSpn

Zeiger auf eine Variable, die die Anzahl der in prpszSpn enthaltenen SPNs empfängt.

[out] prpszSpn

Zeiger auf eine Variable, die einen Zeiger auf ein Array von SPNs empfängt. Dieses Array muss mit DsFreeSpnArray freigegeben werden.

Rückgabewert

Wenn die Funktion ein Array von SPNs zurückgibt, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes sein.

Hinweise

So erstellen Sie SPNs für mehrere Instanzen eines replizierten Diensts, der auf mehreren Hostcomputern ausgeführt wird

Legen Sie cInstanceNames auf die Anzahl der Instanzen fest.
Geben Sie die Namen der Hostcomputer im pInstanceNames-Array an.

So erstellen Sie SPNs für mehrere Instanzen eines Diensts, der auf demselben Hostcomputer ausgeführt wird

Legen Sie cInstanceNames auf die Anzahl der Instanzen fest.
Legen Sie jeden Eintrag im pInstanceNames-Array auf den DNS-Namen des Hostcomputers fest.
Verwenden Sie den pInstancePorts-Parameter, um ein Array eindeutiger Portnummern für jede instance anzugeben, um die SPNs zu unterscheiden.

Zeichenfolgenparameter dürfen keinen Schrägstrich (/) enthalten, der zum Trennen der Komponenten des SPN verwendet wird.

Eine Anwendung mit den entsprechenden Berechtigungen, die in der Regel denen eines Domänenadministrators entsprechen, kann die DsWriteAccountSpn-Funktion aufrufen, um einen oder mehrere SPNs für das Benutzer- oder Computerkonto zu registrieren, in dem der Dienst ausgeführt wird. Clients können dann die SPNs verwenden, um den Dienst zu authentifizieren.

Hinweis

Der ntdsapi.h-Header definiert DsGetSpn 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