Funzione DsMakeSpnA (dsparse.h)

Articolo
08/23/2023

La funzione DsMakeSpn costruisce un nome dell'entità servizio (SPN) che identifica un'istanza del servizio.

Un'applicazione client usa questa funzione per comporre un nome SPN, che usa per autenticare l'istanza del servizio. Ad esempio, il client può passare un NOME SPN nel parametro pszTargetName della funzione InitializeSecurityContext .

Sintassi

DSPARSE DWORD DsMakeSpnA(
  [in]           LPCSTR ServiceClass,
  [in]           LPCSTR ServiceName,
  [in, optional] LPCSTR InstanceName,
  [in]           USHORT InstancePort,
  [in, optional] LPCSTR Referrer,
  [in, out]      DWORD  *pcSpnLength,
  [out]          LPSTR  pszSpn
);

Parametri

[in] ServiceClass

Puntatore a una stringa costante con terminazione Null che specifica la classe del servizio. Questo parametro può essere qualsiasi stringa univoca per tale servizio; Il nome del protocollo, ad esempio ldap, o il formato stringa di un GUID sono accettabili.

[in] ServiceName

Puntatore a una stringa costante con terminazione Null che specifica il nome DNS, il nome NetBIOS o il nome distinto (DN). Questo parametro deve essere diverso da NULL.

Per altre informazioni sull'utilizzo dei parametri ServiceName, InstanceName e InstancePort per comporre un nome SPN, vedere la sezione Osservazioni seguente.

[in, optional] InstanceName

Puntatore a una stringa costante con terminazione Null che specifica il nome DNS o l'indirizzo IP dell'host per un'istanza del servizio.

Se ServiceName specifica il nome DNS o NetBIOS del computer host del servizio, il parametro InstanceName deve essere NULL.

Se ServiceName specifica un nome di dominio DNS, il nome di un record DNS SRV o un nome distinto, ad esempio il nome DN di un punto di connessione del servizio, il parametro InstanceName deve specificare il nome DNS o NetBIOS del computer host del servizio.

[in] InstancePort

Numero di porta per un'istanza del servizio. Usare 0 per la porta predefinita. Se questo parametro è zero, il nome SPN non include un numero di porta.

[in, optional] Referrer

Puntatore a una stringa costante con terminazione Null che specifica il nome DNS dell'host che ha assegnato una segnalazione di indirizzo IP. Questo parametro viene ignorato a meno che il parametro ServiceName non specifichi un indirizzo IP.

[in, out] pcSpnLength

Puntatore a una variabile che contiene la lunghezza, in caratteri, del buffer che riceverà il nuovo SPN costruito. Questo valore può essere 0 per richiedere in anticipo la dimensione finale del buffer.

Il parametro pcSpnLength riceve anche la lunghezza effettiva del nome SPN creato, incluso il carattere null di terminazione.

[out] pszSpn

Puntatore a una stringa con terminazione Null che riceve il nome SPN costruito. Questo buffer deve essere la lunghezza specificata da pcSpnLength. Il parametro pszSpn può essere NULL per richiedere in anticipo la dimensione finale del buffer.

Valore restituito

Se la funzione restituisce un nome SPN, il valore restituito è ERROR_SUCCESS. Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti.

Commenti

Il formato del nome SPN prodotto dalla funzione DsMakeSpn dipende dai parametri di input. Esistono due formati di base. Entrambi i formati iniziano con la stringa ServiceClass seguita da un nome computer host e da un componente InstancePort facoltativo.

Nota Questo formato viene usato dai servizi basati su host.

Per produrre un nome SPN con il formato "<ServiceClass>/<host>"

Impostare il parametro ServiceName sul nome DNS del computer host per l'istanza del servizio. Si tratta del componente host del nome SPN.
Impostare i parametri InstanceName e Referrer su NULL.
Impostare il parametro InstancePort su zero. Se InstancePort è diverso da zero, il nome SPN ha il formato seguente:
```
<service class>/<host>:<instance port>/<referrer>
```

Nota Questo formato viene usato dai servizi replicabili.

Per produrre un nome SPN con il formato "<ServiceClass>/<host>:<InstancePort>"

Impostare il parametro InstanceName sul nome DNS del computer host per l'istanza del servizio. Si tratta del componente host.
Impostare il parametro ServiceName su una stringa che identifica un'istanza del servizio. Ad esempio, potrebbe essere il nome distinto del punto di connessione del servizio per questa istanza del servizio.
Impostare il parametro Referrer su NULL.
Impostare il parametro InstancePort su zero. Se InstancePort è diverso da zero, il nome SPN ha il formato seguente:
```
<service class>/<host>:<instance port>/<service name>
```

Il parametro Referrer viene usato solo se il parametro ServiceName specifica l'indirizzo IP del computer host del servizio. In questo caso, Referrer specifica il nome DNS del computer che ha assegnato l'indirizzo IP come riferimento. Il nome SPN ha il formato seguente:

<service class>/<host>:<instance port>/<referrer>

dove il componente host è la stringa InstanceName o la stringa ServiceName se InstanceName è NULL e il componente InstancePort è facoltativo.

I parametri stringa non possono includere il carattere barra (/), perché viene usato per separare i componenti del nome SPN.

Nota

L'intestazione dsparse.h definisce DsMakeSpn 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	dsparse.h (include Ntdsapi.h)
Libreria	Ntdsapi.lib
DLL	Ntdsapi.dll

Vedi anche

Funzioni di gestione del controller di dominio e della replica

InitializeSecurityContext

Condividi tramite