Fonction DsGetSpnA (ntdsapi.h)

Article
08/25/2023

La fonction DsGetSpn construit un tableau d’un ou plusieurs noms de principal de service (SPN). Chaque nom dans le tableau identifie un instance d’un service. Ces SPN peuvent être inscrits auprès du service d’annuaire (DS) à l’aide de la fonction DsWriteAccountSpn .

Syntaxe

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

Paramètres

[in] ServiceType

Identifie le format des SPN à composer. Le paramètre ServiceType peut avoir l’une des valeurs suivantes.

DS_SPN_DNS_HOST, DS_SPN_DN_HOST DS_SPN_NB_HOST

Les SPN ont le format suivant.

ServiceClass/ InstanceName: InstancePort

Le paramètre ServiceName doit être NULL. Il s’agit du format SPN d’un service basé sur l’hôte, qui fournit des services identifiés avec son ordinateur hôte. Le composant InstancePort est facultatif.

DS_SPN_DOMAIN, DS_SPN_NB_DOMAIN

Les SPN ont le format suivant.

ServiceClass/ InstanceName: InstancePort/ ServiceName

Le paramètre ServiceName doit être le nom DNS ou DN d’un domaine. Ce format est utilisé pour un service réplicable qui fournit des services au domaine spécifié.

DS_SPN_SERVICE

Les SPN ont le format suivant.

ServiceClass/ InstanceName: InstancePort/ ServiceName

Le paramètre ServiceName doit être un nom de domaine ou DNS canonique qui identifie un instance du service. Par exemple, il peut s’agir du nom DNS d’un enregistrement SRV ou du nom unique du point de connexion de service pour ce service instance.

[in] ServiceClass

Pointeur vers une chaîne constante terminée par un caractère Null qui spécifie la classe du service ; par exemple, http. En règle générale, il peut s’agir de n’importe quelle chaîne propre au service.

[in, optional] ServiceName

Pointeur vers une chaîne constante terminée par un caractère Null qui spécifie le nom DNS ou le nom unique (DN) du service. ServiceName n’est pas requis pour un service basé sur l’hôte. Pour plus d’informations, consultez la description du paramètre ServiceType pour connaître les valeurs possibles de ServiceName.

[in] InstancePort

Spécifie le numéro de port du service instance. Si cette valeur est égale à zéro, le SPN n’inclut pas de numéro de port.

[in] cInstanceNames

Spécifie le nombre d’éléments dans les tableaux pInstanceNames et pInstancePorts . Si cette valeur n’est pas égale à zéro, pInstanceNames doit pointer vers un tableau de chaînes cInstanceNames , et pInstancePorts peut être NULL ou un pointeur vers un tableau de numéros de port cInstanceNames . Si cette valeur est égale à zéro, DsGetSpn retourne un seul SPN dans le tableau prpszSpn et pInstanceNames et pInstancePorts sont ignorés .

[in, optional] pInstanceNames

Pointeur vers un tableau de chaînes terminées par null qui spécifient des noms de instance supplémentaires (non utilisés pour les noms d’hôte). Ce paramètre est ignoré si cInstanceNames est égal à zéro. Dans ce cas, le composant InstanceName du SPN utilise par défaut le nom DNS complet de l’ordinateur local ou le nom NetBIOS si DS_SPN_NB_HOST ou DS_SPN_NB_DOMAIN est spécifié.

[in, optional] pInstancePorts

Pointeur vers un tableau de ports instance supplémentaires. Si cette valeur n’est pas NULL, elle doit pointer vers un tableau de numéros de port cInstanceNames . Si cette valeur est NULL, les SPN n’incluent pas de numéro de port. Ce paramètre est ignoré si cInstanceNames est égal à zéro.

[out] pcSpn

Pointeur vers une variable qui reçoit le nombre de SPN contenus dans prpszSpn.

[out] prpszSpn

Pointeur vers une variable qui reçoit un pointeur vers un tableau de noms de principal de service. Ce tableau doit être libéré avec DsFreeSpnArray.

Valeur retournée

Si la fonction retourne un tableau de noms de principal de service, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour peut être l’un des codes d’erreur suivants.

Remarques

Pour créer des noms de principal de service pour plusieurs instances d’un service répliqué s’exécutant sur plusieurs ordinateurs hôtes

Définissez cInstanceNames sur le nombre d’instances.
Spécifiez les noms des ordinateurs hôtes dans le tableau pInstanceNames .

Pour créer des noms de principal de service pour plusieurs instances d’un service exécuté sur le même ordinateur hôte

Définissez cInstanceNames sur le nombre d’instances.
Définissez chaque entrée du tableau pInstanceNames sur le nom DNS de l’ordinateur hôte.
Utilisez le paramètre pInstancePorts pour spécifier un tableau de numéros de port uniques pour chaque instance afin de lever l’ambiguïté des spN.

Les paramètres de chaîne ne peuvent pas inclure la barre oblique (/), qui est utilisée pour séparer les composants du SPN.

Une application disposant des privilèges appropriés, qui sont généralement ceux d’un administrateur de domaine, peut appeler la fonction DsWriteAccountSpn pour inscrire un ou plusieurs SPN sur le compte d’utilisateur ou d’ordinateur sur lequel le service est exécuté. Les clients peuvent ensuite utiliser les SPN pour authentifier le service.

Notes

L’en-tête ntdsapi.h définit DsGetSpn en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	ntdsapi.h
Bibliothèque	Ntdsapi.lib
DLL	Ntdsapi.dll