Exporter (0) Imprimer
Développer tout
EN
Ce contenu n’est pas disponible dans votre langue. Voici la version anglaise.

DsGetSpn function

The DsGetSpn function constructs an array of one or more service principal names (SPNs). Each name in the array identifies an instance of a service. These SPNs may be registered with the directory service (DS) using the DsWriteAccountSpn function.

Syntax


DWORD DsGetSpn(
  _In_      DS_SPN_NAME_TYPE ServiceType,
  _In_      LPCTSTR ServiceClass,
  _In_opt_  LPCTSTR ServiceName,
  _In_      USHORT InstancePort,
  _In_      USHORT cInstanceNames,
  _In_opt_  LPCTSTR *pInstanceNames,
  _In_opt_  const USHORT *pInstancePorts,
  _Out_     DWORD *pcSpn,
  _Out_     LPTSTR **prpszSpn
);

Parameters

ServiceType [in]

Identifies the format of the SPNs to compose. The ServiceType parameter can have one of the following values.

ValueMeaning
DS_SPN_DNS_HOST, DS_SPN_DN_HOST, DS_SPN_NB_HOST

The SPNs have the following format.


ServiceClass/ InstanceName: InstancePort

The ServiceName parameter must be NULL. This is the SPN format for a host-based service, which provides services identified with its host computer. The InstancePort component is optional.

DS_SPN_DOMAIN, DS_SPN_NB_DOMAIN

The SPNs have the following format.


ServiceClass/ InstanceName: InstancePort/ ServiceName

The ServiceName parameter must be the DNS name or DN of a domain. This format is used for a replicable service that provides services to the specified domain.

DS_SPN_SERVICE

The SPNs have the following format.


ServiceClass/ InstanceName: InstancePort/ ServiceName

The ServiceName parameter must be a canonical DN or DNS name that identifies an instance of the service. For example, it could be a DNS name of a SRV record, or the distinguished name of the service connection point for this service instance.

 

ServiceClass [in]

Pointer to a constant null-terminated string that specifies the class of the service; for example, http. Generally, this can be any string that is unique to the service.

ServiceName [in, optional]

Pointer to a constant null-terminated string that specifies the DNS name or distinguished name (DN) of the service. ServiceName is not required for a host-based service. For more information, see the description of the ServiceType parameter for the possible values of ServiceName.

InstancePort [in]

Specifies the port number of the service instance. If this value is zero, the SPN does not include a port number.

cInstanceNames [in]

Specifies the number of elements in the pInstanceNames and pInstancePorts arrays. If this value is zero, pInstanceNames must point to an array of cInstanceNames strings, and pInstancePorts can be either NULL or a pointer to an array of cInstanceNames port numbers. If this value is zero, DsGetSpn returns only one SPN in the prpszSpn array and pInstanceNames and pInstancePorts are ignored.

pInstanceNames [in, optional]

Pointer to an array of null-terminated strings that specify extra instance names (not used for host names). This parameter is ignored if cInstanceNames is zero. In that case, the InstanceName component of the SPN defaults to the fully qualified DNS name of the local computer or the NetBIOS name if DS_SPN_NB_HOST or DS_SPN_NB_DOMAIN is specified.

pInstancePorts [in, optional]

Pointer to an array of extra instance ports. If this value is non-NULL, it must point to an array of cInstanceNames port numbers. If this value is NULL, the SPNs do not include a port number. This parameter is ignored if cInstanceNames is zero.

pcSpn [out]

Pointer to a variable that receives the number of SPNs contained in prpszSpn.

prpszSpn [out]

Pointer to a variable that receives a pointer to an array of SPNs. This array must be freed with DsFreeSpnArray.

Return value

If the function returns an array of SPNs, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following error codes.

Return codeDescription
ERROR_INVALID_PARAMETER

A parameter is incorrect.

ERROR_NOT_ENOUGH_MEMORY

There is insufficient memory available.

ERROR_DS_BAD_NAME_SYNTAX

The ServiceName parameter does not contain a valid name for a service.

 

Remarks

ms675993.wedge(en-us,VS.85).gifTo create SPNs for multiple instances of a replicated service running on multiple host computers

  1. Set cInstanceNames to the number of instances.
  2. Specify the names of the host computers in the pInstanceNames array.

ms675993.wedge(en-us,VS.85).gifTo create SPNs for multiple instances of a service running on the same host computer

  1. Set the cInstanceNames to the number of instances.
  2. Set each entry in the pInstanceNames array to the DNS name of the host computer.
  3. Use the pInstancePorts parameter to specify an array of unique port numbers for each instance to disambiguate the SPNs.

String parameters cannot include the forward slash (/), which is used to separate the components of the SPN.

An application with the appropriate privileges, which are usually those of a domain administrator, can call the DsWriteAccountSpn function to register one or more SPNs on the user or computer account where the service is running. Clients can then use the SPNs to authenticate the service.

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Header

Ntdsapi.h

Library

Ntdsapi.lib

DLL

Ntdsapi.dll

Unicode and ANSI names

DsGetSpnW (Unicode) and DsGetSpnA (ANSI)

See also

DsFreeSpnArray
DsWriteAccountSpn
Domain Controller and Replication Management Functions

 

 

Microsoft réalise une enquête en ligne pour recueillir votre opinion sur le site Web de MSDN. Si vous choisissez d’y participer, cette enquête en ligne vous sera présentée lorsque vous quitterez le site Web de MSDN.

Si vous souhaitez y participer,
Afficher:
© 2014 Microsoft