DsMakeSpnA, fonction (dsparse.h)

Article
11/20/2024

La fonction DsMakeSpn construit un nom de principal de service (SPN) qui identifie une instance de service.

Une application cliente utilise cette fonction pour composer un SPN, qu’elle utilise pour authentifier l’instance de service. Par exemple, le client peut passer un SPN dans le paramètre pszTargetName de la fonction InitializeSecurityContext.

Syntaxe

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

Paramètres

[in] ServiceClass

Pointeur vers une chaîne constante terminée par null qui spécifie la classe du service. Ce paramètre peut être n’importe quelle chaîne unique à ce service ; soit le nom du protocole, par exemple, ldap, soit la forme de chaîne d’un GUID sont acceptables.

[in] ServiceName

Pointeur vers une chaîne constante terminée par null qui spécifie le nom DNS, le nom NetBIOS ou le nom unique (DN). Ce paramètre ne doit pas êtreNULL.

Pour plus d’informations sur la façon dont les paramètres ServiceName, InstanceName et InstancePort sont utilisés pour composer un SPN, consultez la section Remarques suivantes.

[in, optional] InstanceName

Pointeur vers une chaîne constante terminée par null qui spécifie le nom DNS ou l’adresse IP de l’hôte pour une instance du service.

Si ServiceName spécifie le nom DNS ou NetBIOS de l’ordinateur hôte du service, le paramètre InstanceName doit être NULL.

Si ServiceName spécifie un nom de domaine DNS, le nom d’un enregistrement SRV DNS ou un nom unique, tel que le nom DN d’un point de connexion de service, le paramètre InstanceName doit spécifier le nom DNS ou NetBIOS de l’ordinateur hôte du service.

[in] InstancePort

Numéro de port d’une instance du service. Utilisez 0 pour le port par défaut. Si ce paramètre est égal à zéro, le SPN n’inclut pas de numéro de port.

[in, optional] Referrer

Pointeur vers une chaîne constante terminée par null qui spécifie le nom DNS de l’hôte qui a donné une référence d’adresse IP. Ce paramètre est ignoré, sauf si le paramètre ServiceName spécifie une adresse IP.

[in, out] pcSpnLength

Pointeur vers une variable qui contient la longueur, en caractères, de la mémoire tampon qui recevra le nouveau SPN construit. Cette valeur peut être 0 pour demander la taille finale de la mémoire tampon à l’avance.

Le paramètre pcSpnLength reçoit également la longueur réelle du SPN créé, y compris le caractère null de fin.

[out] pszSpn

Pointeur vers une chaîne terminée par null qui reçoit le SPN construit. Cette mémoire tampon doit être la longueur spécifiée par pcSpnLength. Le paramètre pszSpn peut être NULL pour demander la taille finale de la mémoire tampon à l’avance.

Valeur de retour

Si la fonction retourne un 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

Le format du SPN produit par la fonction DsMakeSpn dépend des paramètres d’entrée. Il existe deux formats de base. Les deux formats commencent par la chaîne ServiceClass suivie d’un nom d’ordinateur hôte et d’un composant InstancePort facultatif.

Remarque Ce format est utilisé par les services basés sur l’hôte.

Pour produire un SPN avec le format «<ServiceClass>/<hôte>»

Définissez le paramètre ServiceName sur le nom DNS de l’ordinateur hôte pour l’instance de service. Il s’agit du composant hôte du SPN.
Définissez les paramètres InstanceName et Referrer sur NULL.
Définissez le paramètre instancePort
sur zéro. Si InstancePort n’est pas zéro, le spN a le format suivant :
```
<service class>/<host>:<instance port>/<referrer>
```

Remarque Ce format est utilisé par les services réplicables.

Pour produire un SPN avec le format «<ServiceClass>/<>hôte :<InstancePort>»

Définissez le paramètre InstanceName sur le nom DNS de l’ordinateur hôte pour l’instance de service. Il s’agit du composant hôte.
Définissez le paramètre ServiceName sur une chaîne qui identifie une instance du service. Par exemple, il peut s’agir du nom unique du point de connexion de service pour cette instance de service.
Définissez le paramètre de référence sur NULL.
Définissez le paramètre instancePort
sur zéro. Si InstancePort n’est pas zéro, le spN a le format suivant :
```
<service class>/<host>:<instance port>/<service name>
```

Le paramètre Référence n’est utilisé que si le paramètre ServiceName spécifie l’adresse IP de l’ordinateur hôte du service. Dans ce cas, référent spécifie le nom DNS de l’ordinateur qui a donné l’adresse IP en tant que référence. Le SPN a le format suivant :

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

où le composant hôte est la chaîne InstanceName ou la chaîne ServiceName si nom_instance est NULL et que le composant InstancePort est facultatif.

Les paramètres de chaîne ne peuvent pas inclure le caractère de barre oblique (/), car il est utilisé pour séparer les composants du SPN.

Note

L’en-tête dsparse.h définit DsMakeSpn comme 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	dsparse.h (include Ntdsapi.h)
bibliothèque	Ntdsapi.lib
DLL	Ntdsapi.dll

Voir aussi

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

InitializeSecurityContext

Partager via