dsGetSpnA 函数 (ntdsapi.h)

项目
03/13/2024

DsGetSpn 函数构造一个或多个服务主体名称的数组 (SPN) 。数组中的每个名称都标识服务的实例。可以使用 DsWriteAccountSpn 函数将这些 SPN 注册到目录服务 (DS) 。

语法

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

参数

[in] ServiceType

标识要撰写的 SPN 的格式。 ServiceType 参数可以具有以下值之一。

DS_SPN_DNS_HOST、DS_SPN_DN_HOST、DS_SPN_NB_HOST

SPN 具有以下格式。

ServiceClass/ InstanceName: InstancePort

ServiceName 参数必须为 NULL。这是基于主机的服务的 SPN 格式，该服务提供与其主机计算机标识的服务。 InstancePort 组件是可选的。

DS_SPN_DOMAIN、DS_SPN_NB_DOMAIN

SPN 具有以下格式。

ServiceClass/ InstanceName: InstancePort/ ServiceName

ServiceName 参数必须是域的 DNS 名称或 DN。此格式用于向指定域提供服务的可复制服务。

DS_SPN_SERVICE

SPN 具有以下格式。

ServiceClass/ InstanceName: InstancePort/ ServiceName

ServiceName 参数必须是标识服务实例的规范 DN 或 DNS 名称。例如，它可以是 SRV 记录的 DNS 名称，也可以是此服务实例的服务连接点的可分辨名称。

[in] ServiceClass

指向以 null 结尾的常量字符串的指针，该字符串指定服务的类;例如 http。通常，这可以是服务唯一的任何字符串。

[in, optional] ServiceName

指向以 null 结尾的常量字符串的指针，该字符串指定服务的 DNS 名称或可分辨名称 (DN) 。基于主机的服务不需要 ServiceName。有关详细信息，请参阅 ServiceType 参数的说明，了解 ServiceName 的可能值。

[in] InstancePort

指定服务实例的端口号。如果此值为零，则 SPN 不包含端口号。

[in] cInstanceNames

指定 pInstanceNames 和 pInstancePorts 数组中的元素数。如果此值不为零， 则 pInstanceNames 必须指向 cInstanceNames 字符串数组，并且 pInstancePorts 可以是 NULL ，也可以是指向 cInstanceNames 端口号数组的指针。如果此值为零，DsGetSpn 在 prpszSpn 数组中仅返回一个 SPN，pInstanceNames 和 pInstancePorts 将被忽略。

[in, optional] pInstanceNames

指向以 null 结尾的字符串数组的指针，这些字符串指定 (不用于主机名) 的额外实例名称。如果 cInstanceNames 为零，则忽略此参数。在这种情况下，如果指定了 DS_SPN_NB_HOST 或 DS_SPN_NB_DOMAIN，SPN 的 InstanceName 组件默认为本地计算机的完全限定 DNS 名称或 NetBIOS 名称。

[in, optional] pInstancePorts

指向额外实例端口数组的指针。如果此值为非 NULL，则必须指向 cInstanceNames 端口号数组。如果此值为 NULL，则 SPN 不包含端口号。如果 cInstanceNames 为零，则忽略此参数。

[out] pcSpn

指向接收 prpszSpn 中包含的 SPN 数的变量的指针。

[out] prpszSpn

指向接收指向 SPN 数组的指针的变量的指针。必须使用 DsFreeSpnArray 释放此数组。

返回值

如果函数返回 SPN 数组，则返回值 ERROR_SUCCESS。

如果函数失败，则返回值可能是以下错误代码之一。

注解

为多个主计算机上运行的复制服务的多个实例创建 SPN

将 cInstanceNames 设置为实例数。
在 pInstanceNames 数组中指定主机的名称。

为在同一主机计算机上运行的服务的多个实例创建 SPN

将 cInstanceNames 设置为实例数。
将 pInstanceNames 数组中的每个条目设置为主机的 DNS 名称。
使用 pInstancePorts 参数为每个实例指定唯一端口号数组，以消除 SPN 的歧义。

字符串参数不能包含正斜杠 (/) ，该斜杠用于分隔 SPN 的组件。

具有适当权限（通常是域管理员权限）的应用程序可以调用 DsWriteAccountSpn 函数，以在运行服务的用户或计算机帐户上注册一个或多个 SPN。然后，客户端可以使用 SPN 对服务进行身份验证。

注意

ntdsapi.h 标头将 DsGetSpn 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows Vista
最低受支持的服务器	Windows Server 2008
目标平台	Windows
标头	ntdsapi.h
Library	Ntdsapi.lib
DLL	Ntdsapi.dll