Funzione DsGetSpnA (ntdsapi.h)

Articolo
11/20/2024

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. Si tratta del 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 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, potrebbe trattarsi di un nome DNS di un record SRV o del nome distinto del punto di connessione del servizio per questa istanza del servizio.

[in] ServiceClass

Puntatore a una stringa con terminazione Null costante 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 possibili valori 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 nella pInstanceNames e pInstancePorts matrici. Se questo valore non è zero, pInstanceNames deve puntare a una matrice di cInstanceNames stringhe e pInstancePorts può essere null o un puntatore a una matrice di cInstanceNames numeri di porta. 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, il componente InstanceName del nome SPN viene impostato per impostazione predefinita sul nome DNS completo del computer locale o sul 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 non èNULL, deve puntare a una matrice di cInstanceNames numeri di porta. 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 è ERROR_SUCCESS.

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

Osservazioni

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 il 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 disambiguare 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, che in genere sono 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista
server minimo supportato	Windows Server 2008
piattaforma di destinazione	Finestre
intestazione	ntdsapi.h
libreria	Ntdsapi.lib
dll	Ntdsapi.dll