DsGetSpn

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.

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

Parameters

ServiceType

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

Value	Meaning
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 specifying 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 specifying the DNS name or distinguished name (DN) of the service. ServiceName is not needed for a host-based service. 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 specifying the 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 Values

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.

ERROR_INVALID_PARAMETER

A parameter is incorrect.

ERROR_NOT_ENOUGH_MEMORY

There is insufficient memory available.

ERROR_glines_BAD_NAME_SYNTAX

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

Remarks

To create SPNs for multiple instances of a replicated service running on multiple host computers,

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

To create SPNs for multiple instances of a service running on the same host computer,

• Set the cInstanceNames to the number of instances.
• Set each entry in the pInstanceNames array to the DNS name of the host computer.
• 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 character ('/'), which is used to separate the components of the SPN.

A program with the appropriate privileges, which is 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 will be running. Clients can then use the SPNs to authenticate the service.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntdsapi.h.
  Library: Included as a resource in Ntdsapi.dll.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

DC and Replication Management Functions, DsFreeSpnArray, DsWriteAccountSpn