Funzione DsGetSpnA (ntdsapi.h)

Articolo
03/08/2023

La funzione DsGetSpn costruisce una matrice di uno o più nomi di entità servizio (SPN). Ogni nome nella matrice identifica un'istanza di un servizio. Questi NOMI SPN possono essere registrati con il servizio directory usando la funzione DsWriteAccountSpn .

Sintassi

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

Parametri

[in] ServiceType

Identifica il formato dei nomi SPN da comporre. Il parametro ServiceType può avere uno dei valori seguenti.

DS_SPN_DNS_HOST, DS_SPN_DN_HOST, DS_SPN_NB_HOST

I nomi SPN hanno il formato seguente.

ServiceClass/ InstanceName: InstancePort

Il parametro ServiceName deve essere NULL. Questo è il formato SPN per un servizio basato su host, che fornisce servizi identificati con il computer host. Il componente InstancePort è facoltativo.

DS_SPN_DOMAIN, DS_SPN_NB_DOMAIN

I nomi SPN hanno il formato seguente.

ServiceClass/ InstanceName: InstancePort/ ServiceName

Il parametro ServiceName deve essere il nome DNS o il DN di un dominio. Questo formato viene usato per un servizio replicabile che fornisce servizi al dominio specificato.

DS_SPN_SERVICE

I nomi SPN hanno il formato seguente.

ServiceClass/ InstanceName: InstancePort/ ServiceName

Il parametro ServiceName deve essere un nome DN o DNS canonico che identifica un'istanza del servizio. Ad esempio, può essere un nome DNS di un record SRV o il nome distinto del punto di connessione del servizio per questa istanza del servizio.

[in] ServiceClass

Puntatore a una stringa costante con terminazione Null che specifica la classe del servizio; ad esempio http. In genere, può trattarsi di qualsiasi stringa univoca per il servizio.

[in, optional] ServiceName

Puntatore a una stringa costante con terminazione Null che specifica il nome DNS o il nome distinto (DN) del servizio. ServiceName non è necessario per un servizio basato su host. Per altre informazioni, vedere la descrizione del parametro ServiceType per i valori possibili di ServiceName.

[in] InstancePort

Specifica il numero di porta dell'istanza del servizio. Se questo valore è zero, il nome SPN non include un numero di porta.

[in] cInstanceNames

Specifica il numero di elementi nelle matrici pInstanceNames e pInstancePorts . Se questo valore non è zero, pInstanceNames deve puntare a una matrice di stringhe cInstanceNames e pInstancePorts può essere NULL o un puntatore a una matrice di numeri di porta cInstanceNames . Se questo valore è zero, DsGetSpn restituisce un solo nome SPN nella matrice prpszSpn e pInstanceNames e pInstancePorts vengono ignorati .

[in, optional] pInstanceNames

Puntatore a una matrice di stringhe con terminazione Null che specificano nomi di istanza aggiuntivi (non usati per i nomi host). Questo parametro viene ignorato se cInstanceNames è zero. In tal caso, per impostazione predefinita, il componente InstanceName del nome SPN corrisponde al nome DNS completo del computer locale o al nome NetBIOS se viene specificato DS_SPN_NB_HOST o DS_SPN_NB_DOMAIN .

[in, optional] pInstancePorts

Puntatore a una matrice di porte di istanza aggiuntive. Se questo valore è diverso da NULL, deve puntare a una matrice di numeri di porta cInstanceNames . Se questo valore è NULL, i nomi SPN non includono un numero di porta. Questo parametro viene ignorato se cInstanceNames è zero.

[out] pcSpn

Puntatore a una variabile che riceve il numero di nomi SPN contenuti in prpszSpn.

[out] prpszSpn

Puntatore a una variabile che riceve un puntatore a una matrice di nomi SPN. Questa matrice deve essere liberata con DsFreeSpnArray.

Valore restituito

Se la funzione restituisce una matrice di nomi SPN, il valore restituito viene ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti.

Commenti

Per creare nomi SPN per più istanze di un servizio replicato in esecuzione in più computer host

Impostare cInstanceNames sul numero di istanze.
Specificare i nomi dei computer host nella matrice pInstanceNames .

Per creare nomi SPN per più istanze di un servizio in esecuzione nello stesso computer host

Impostare cInstanceNames sul numero di istanze.
Impostare ogni voce nella matrice pInstanceNames sul nome DNS del computer host.
Usare il parametro pInstancePorts per specificare una matrice di numeri di porta univoci per ogni istanza per evitare ambiguità tra i nomi SPN.

I parametri stringa non possono includere la barra (/), utilizzata per separare i componenti del nome SPN.

Un'applicazione con i privilegi appropriati, in genere quelli di un amministratore di dominio, può chiamare la funzione DsWriteAccountSpn per registrare uno o più nomi SPN nell'account utente o computer in cui è in esecuzione il servizio. I client possono quindi usare i nomi SPN per autenticare il servizio.

Nota

L'intestazione ntdsapi.h definisce DsGetSpn come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	ntdsapi.h
Libreria	Ntdsapi.lib
DLL	Ntdsapi.dll