DsGetSpnA 函式 (ntdsapi.h)

發行項
02/29/2024

DsGetSpn 函式會建構一或多個服務主體名稱的陣列， (SPN) 。陣列中的每個名稱都會識別服務的實例。這些SPN可以使用 DsWriteAccountSpn 函式，向目錄服務註冊 (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。如需詳細資訊，請參閱 ServiceName 可能值之 ServiceType 參數的描述。

[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
程式庫	Ntdsapi.lib
Dll	Ntdsapi.dll