DsGetSpnA, fonction (ntdsapi.h)

La fonction DsGetSpn construit un tableau d’un ou plusieurs noms de principaux de service (SPN). Chaque nom du tableau identifie une 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 le nom 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 DN ou DNS canonique qui identifie une instance du service. Par exemple, il peut s’agir d’un nom DNS d’un enregistrement SRV ou du nom unique du point de connexion de service pour cette instance de service.

[in] ServiceClass

Pointeur vers une chaîne constante terminée par 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 unique au service.

[in, optional] ServiceName

Pointeur vers une chaîne constante terminée par null qui spécifie le nom DNS ou le nom unique (DN) du service. ServiceName n’est pas nécessaire 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 de l’instance de service. 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 zéro, pInstanceNames doit pointer vers un tableau de chaînes cInstanceNames et pInstancePorts peut être NULL ou un pointeur vers un tableau de cInstanceNames numéros de port. Si cette valeur est égale à zéro, DsGetSpn ne retourne qu’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 d’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 est défini par défaut sur 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 d’instance supplémentaires. Si cette valeur n’est pasnull, elle doit pointer vers un tableau de cInstanceNames numéros de port. Si cette valeur est NULL, les noms de principal du service 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 SPN. Ce tableau doit être libéré avec DsFreeSpnArray.

Valeur de retour

Si la fonction retourne un tableau de SPN, 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 spN pour plusieurs instances d’un service répliqué s’exécutant sur plusieurs ordinateurs hôtes

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

Pour créer des SPN pour plusieurs instances d’un service s’exécutant sur le même ordinateur hôte

1. Définissez les cInstanceNames sur le nombre d’instances.
2. Définissez chaque entrée dans le tableau pInstanceNames le nom DNS de l’ordinateur hôte.
3. 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 (/), utilisée pour séparer les composants du SPN.

Une application disposant des privilèges appropriés, 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 en cours d’exécution. Les clients peuvent ensuite utiliser les SPN pour authentifier le service.

Note

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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista
serveur minimum pris en charge	Windows Server 2008
plateforme cible	Windows
d’en-tête	ntdsapi.h
bibliothèque	Ntdsapi.lib
DLL	Ntdsapi.dll

Voir aussi

fonctions de gestion du contrôleur de domaine et de la réplication

DsFreeSpnArray

DsWriteAccountSpn