Fungsi DsGetSpnA (ntdsapi.h)

Artikel
08/25/2023

Fungsi DsGetSpn membangun array dari satu atau beberapa nama perwakilan layanan (SPN). Setiap nama dalam array mengidentifikasi instans layanan. SPN ini dapat didaftarkan dengan layanan direktori (DS) menggunakan fungsi DsWriteAccountSpn .

Sintaks

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

Parameter

[in] ServiceType

Mengidentifikasi format SPN yang akan disusupi. Parameter ServiceType dapat memiliki salah satu nilai berikut.

DS_SPN_DNS_HOST, DS_SPN_DN_HOST, DS_SPN_NB_HOST

SPN memiliki format berikut.

ServiceClass/ InstanceName: InstancePort

Parameter ServiceName harus NULL. Ini adalah format SPN untuk layanan berbasis host, yang menyediakan layanan yang diidentifikasi dengan komputer host-nya. Komponen InstancePort bersifat opsional.

DS_SPN_DOMAIN, DS_SPN_NB_DOMAIN

SPN memiliki format berikut.

ServiceClass/ InstanceName: InstancePort/ ServiceName

Parameter ServiceName harus berupa nama DNS atau DN domain. Format ini digunakan untuk layanan yang dapat direplikasi yang menyediakan layanan ke domain yang ditentukan.

DS_SPN_SERVICE

SPN memiliki format berikut.

ServiceClass/ InstanceName: InstancePort/ ServiceName

Parameter ServiceName harus berupa nama DN atau DNS kanonis yang mengidentifikasi instans layanan. Misalnya, itu bisa menjadi nama DNS rekaman SRV, atau nama khusus titik koneksi layanan untuk instans layanan ini.

[in] ServiceClass

Penunjuk ke string konstanta yang dihentikan null yang menentukan kelas layanan; misalnya, http. Umumnya, ini bisa menjadi string apa pun yang unik untuk layanan.

[in, optional] ServiceName

Penunjuk ke string konstanta yang dihentikan null yang menentukan nama DNS atau nama khusus (DN) layanan. ServiceName tidak diperlukan untuk layanan berbasis host. Untuk informasi selengkapnya, lihat deskripsi parameter ServiceType untuk kemungkinan nilai ServiceName.

[in] InstancePort

Menentukan nomor port instans layanan. Jika nilai ini nol, SPN tidak menyertakan nomor port.

[in] cInstanceNames

Menentukan jumlah elemen dalam array pInstanceNames dan pInstancePorts . Jika nilai ini bukan nol, pInstanceNames harus menunjuk ke array string cInstanceNames , dan pInstancePorts dapat berupa NULL atau penunjuk ke array nomor port cInstanceNames . Jika nilai ini nol, DsGetSpn hanya mengembalikan satu SPN dalam array prpszSpn dan pInstanceNames dan pInstancePorts yang diabaikan.

[in, optional] pInstanceNames

Penunjuk ke array string yang dihentikan null yang menentukan nama instans tambahan (tidak digunakan untuk nama host). Parameter ini diabaikan jika cInstanceNames adalah nol. Dalam hal ini, komponen InstanceName dari SPN default ke nama DNS komputer lokal yang sepenuhnya memenuhi syarat atau nama NetBIOS jika DS_SPN_NB_HOST atau DS_SPN_NB_DOMAIN ditentukan.

[in, optional] pInstancePorts

Arahkan ke array port instans tambahan. Jika nilai ini bukan NULL, nilai harus menunjuk ke array nomor port cInstanceNames . Jika nilai ini NULL, SPN tidak menyertakan nomor port. Parameter ini diabaikan jika cInstanceNames adalah nol.

[out] pcSpn

Pointer ke variabel yang menerima jumlah SPN yang terkandung dalam prpszSpn.

[out] prpszSpn

Penunjuk ke variabel yang menerima penunjuk ke array SPN. Array ini harus dikosongkan dengan DsFreeSpnArray.

Nilai kembali

Jika fungsi mengembalikan array SPN, nilai yang dikembalikan ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan bisa menjadi salah satu kode kesalahan berikut.

Keterangan

Untuk membuat SPN untuk beberapa instans layanan yang direplikasi yang berjalan di beberapa komputer host

Atur cInstanceNames ke jumlah instans.
Tentukan nama komputer host dalam array pInstanceNames .

Untuk membuat SPN untuk beberapa instans layanan yang berjalan di komputer host yang sama

Atur cInstanceNames ke jumlah instans.
Atur setiap entri dalam array pInstanceNames ke nama DNS komputer host.
Gunakan parameter pInstancePorts untuk menentukan array nomor port unik untuk setiap instans untuk membedakan SPN.

Parameter string tidak dapat menyertakan garis miring (/), yang digunakan untuk memisahkan komponen SPN.

Aplikasi dengan hak istimewa yang sesuai, yang biasanya merupakan aplikasi dari administrator domain, dapat memanggil fungsi DsWriteAccountSpn untuk mendaftarkan satu atau beberapa SPN pada akun pengguna atau komputer tempat layanan berjalan. Klien kemudian dapat menggunakan SPN untuk mengautentikasi layanan.

Catatan

Header ntdsapi.h mendefinisikan DsGetSpn sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Server minimum yang didukung	Windows Server 2008
Target Platform	Windows
Header	ntdsapi.h
Pustaka	Ntdsapi.lib
DLL	Ntdsapi.dll