Fungsi NetJoinDomain (lmjoin.h)

Artikel
08/24/2023

Fungsi NetJoinDomain menggabungkan komputer ke grup kerja atau domain.

Sintaks

NET_API_STATUS NET_API_FUNCTION NetJoinDomain(
  [in] LPCWSTR lpServer,
  [in] LPCWSTR lpDomain,
  [in] LPCWSTR lpMachineAccountOU,
  [in] LPCWSTR lpAccount,
  [in] LPCWSTR lpPassword,
  [in] DWORD   fJoinOptions
);

Parameter

[in] lpServer

Penunjuk ke string konstanta yang menentukan nama DNS atau NetBIOS komputer untuk menjalankan operasi gabungan domain. Jika parameter ini NULL, komputer lokal akan digunakan.

[in] lpDomain

Penunjuk ke string karakter yang dihentikan null konstanta yang menentukan nama domain atau grup kerja yang akan digabungkan.

Secara opsional, Anda dapat menentukan pengendali domain pilihan untuk melakukan operasi gabungan. Dalam hal ini, string harus berupa DomainName\MachineName, di mana DomainName adalah nama domain untuk bergabung, dan MachineName adalah nama pengendali domain untuk melakukan gabungan.

[in] lpMachineAccountOU

Secara opsional menentukan penunjuk ke string karakter yang dihentikan null konstan yang berisi nama format RFC 1779 unit organisasi (OU) untuk akun komputer. Jika Anda menentukan parameter ini, string harus berisi jalur lengkap, misalnya, OU=testOU,DC=domain,DC=Domain,DC=com. Jika tidak, parameter ini harus NULL.

[in] lpAccount

Penunjuk ke string karakter yang dihentikan null konstanta yang menentukan nama akun yang akan digunakan saat menyambungkan ke pengontrol domain. String harus menentukan nama domain NetBIOS dan akun pengguna (misalnya, REDMOND\user) atau nama prinsipal pengguna (UPN) pengguna dalam bentuk nama login gaya Internet (misalnya, "someone@example.com"). Jika parameter ini NULL, konteks pemanggil akan digunakan.

[in] lpPassword

Jika parameter lpAccount menentukan nama akun, parameter ini harus menunjuk ke kata sandi yang akan digunakan saat menyambungkan ke pengendali domain. Jika tidak, parameter ini harus NULL.

Anda dapat menentukan kata sandi akun komputer lokal daripada kata sandi pengguna untuk gabungan yang tidak aman. Untuk informasi selengkapnya, lihat deskripsi bendera NETSETUP_MACHINE_PWD_PASSED yang dijelaskan dalam parameter fJoinOptions .

[in] fJoinOptions

Sekumpulan bendera bit yang menentukan opsi gabungan. Parameter ini dapat berupa satu atau beberapa nilai berikut yang ditentukan dalam file header Lmjoin.h .

Nilai	Makna
NETSETUP_JOIN_DOMAIN 0x00000001	Menggabungkan komputer ke domain. Jika nilai ini tidak ditentukan, gabungkan komputer ke grup kerja.
NETSETUP_ACCT_CREATE 0x00000002	Membuat akun di domain.
NETSETUP_WIN9X_UPGRADE 0x00000010	Operasi gabungan terjadi sebagai bagian dari peningkatan.
NETSETUP_DOMAIN_JOIN_IF_JOINED 0x00000020	Memperbolehkan bergabung ke domain baru meskipun komputer sudah bergabung ke domain.
NETSETUP_JOIN_UNSECURE 0x00000040	Melakukan gabungan yang tidak aman. Opsi ini meminta gabungan domain ke akun yang telah dibuat sebelumnya tanpa mengautentikasi dengan kredensial pengguna domain. Opsi ini dapat digunakan bersama dengan opsi NETSETUP_MACHINE_PWD_PASSED . Dalam hal ini, lpPassword adalah kata sandi dari akun komputer yang telah dibuat sebelumnya. Sebelum Windows Vista dengan SP1 dan Windows Server 2008, gabungan yang tidak aman tidak mengautentikasi ke pengendali domain. Semua komunikasi dilakukan menggunakan sesi null (tidak diautentikasi). Dimulai dengan Windows Vista dengan SP1 dan Windows Server 2008, nama akun komputer dan kata sandi digunakan untuk mengautentikasi ke pengendali domain.
NETSETUP_MACHINE_PWD_PASSED 0x00000080	Menunjukkan bahwa parameter lpPassword menentukan kata sandi akun komputer lokal daripada kata sandi pengguna. Bendera ini hanya valid untuk gabungan yang tidak aman, yang harus Anda tunjukkan dengan juga mengatur bendera NETSETUP_JOIN_UNSECURE. Jika Anda mengatur bendera ini, maka setelah operasi gabungan berhasil, kata sandi komputer akan diatur ke nilai lpPassword, jika nilai tersebut adalah kata sandi komputer yang valid.
NETSETUP_DEFER_SPN_SET 0x00000100	Menunjukkan bahwa nama prinsipal layanan (SPN) dan properti DnsHostName pada objek komputer tidak boleh diperbarui saat ini. Biasanya, properti ini diperbarui selama operasi gabungan. Sebagai gantinya, properti ini harus diperbarui selama panggilan berikutnya ke fungsi NetRenameMachineInDomain . Properti ini selalu diperbarui selama operasi ganti nama. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
NETSETUP_JOIN_DC_ACCOUNT 0x00000200	Izinkan domain bergabung jika akun yang ada adalah pengendali domain. Catatan Bendera ini didukung pada Windows Vista dan yang lebih baru.
NETSETUP_JOIN_WITH_NEW_NAME 0x00000400	Gabungkan komputer target yang ditentukan dalam parameter lpServer dengan nama baru yang dikueri dari registri pada komputer yang ditentukan dalam parameter lpServer . Opsi ini digunakan jika SetComputerNameEx telah dipanggil sebelum me-reboot komputer. Nama komputer baru tidak akan berlaku hingga reboot. Dengan opsi ini, pemanggil menginstruksikan fungsi NetJoinDomain untuk menggunakan nama baru selama operasi gabungan domain. Reboot diperlukan setelah berhasil memanggil NetJoinDomain pada saat itu perubahan nama komputer dan perubahan keanggotaan domain akan diterapkan. Catatan Bendera ini didukung pada Windows Vista dan yang lebih baru.
NETSETUP_JOIN_READONLY 0x00000800	Gabungkan komputer target yang ditentukan dalam parameter lpServer menggunakan akun yang telah dibuat sebelumnya tanpa memerlukan pengontrol domain bisa-tulis. Opsi ini menyediakan kemampuan untuk menggabungkan komputer ke domain jika akun telah disediakan dan direplikasi ke pengontrol domain baca-saja. Pengontrol domain baca-saja target ditentukan sebagai bagian dari parameter lpDomain , setelah nama domain dibatasi oleh karakter '\'. Provisi ini harus menyertakan rahasia komputer. Akun komputer harus ditambahkan melalui keanggotaan grup ke dalam daftar yang diizinkan untuk kebijakan replikasi kata sandi, dan kata sandi akun harus direplikasi ke pengontrol domain baca-saja sebelum operasi gabungan. Untuk informasi selengkapnya, lihat informasi tentang Administrasi Kebijakan Replikasi Kata Sandi. Dimulai dengan Windows 7, mekanisme alternatif adalah menggunakan mekanisme gabungan domain offline. Untuk informasi selengkapnya, lihat fungsi NetProvisionComputerAccount dan NetRequestOfflineDomainJoin . Catatan Bendera ini didukung pada Windows Vista dan yang lebih baru.
NETSETUP_AMBIGUOUS_DC 0x00001000	Saat bergabung dengan domain, jangan mencoba mengatur pengendali domain pilihan di registri. Catatan Bendera ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru.
NETSETUP_NO_NETLOGON_CACHE 0x00002000	Saat bergabung dengan domain, jangan buat cache Netlogon. Catatan Bendera ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru.
NETSETUP_DONT_CONTROL_SERVICES 0x00004000	Saat bergabung dengan domain, jangan paksa layanan Netlogon untuk memulai. Catatan Bendera ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru.
NETSETUP_SET_MACHINE_NAME 0x00008000	Saat bergabung dengan domain hanya untuk gabungan offline, atur nama host komputer target dan nama NetBIOS. Catatan Bendera ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru.
NETSETUP_FORCE_SPN_SET 0x00010000	Saat bergabung dengan domain, ganti pengaturan lain selama bergabung dengan domain dan atur nama prinsipal layanan (SPN). Catatan Bendera ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru.
NETSETUP_NO_ACCT_REUSE 0x00020000	Saat bergabung dengan domain, jangan gunakan kembali akun yang sudah ada. Catatan Bendera ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru.
NETSETUP_IGNORE_UNSUPPORTED_FLAGS 0x10000000	Jika bit ini diatur, bendera yang tidak dikenal akan diabaikan oleh fungsi NetJoinDomain dan NetJoinDomain akan berperilaku seolah-olah bendera tidak diatur.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah NERR_Success.

Jika fungsi gagal, nilai yang dikembalikan dapat menjadi salah satu kode kesalahan berikut atau salah satu kode kesalahan sistem.

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Akses ditolak. Kesalahan ini dikembalikan jika penelepon bukan anggota grup lokal Administrator pada komputer target.
ERROR_INVALID_PARAMETER	Parameter salah. Kesalahan ini dikembalikan jika parameter lpDomain adalah NULL.
ERROR_NO_SUCH_DOMAIN	Domain yang ditentukan tidak ada.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan jika komputer yang ditentukan dalam parameter lpServer tidak mendukung beberapa opsi yang diteruskan dalam parameter fJoinOptions .
NERR_InvalidWorkgroupName	Nama grup kerja yang ditentukan tidak valid.
NERR_SetupAlreadyJoined	Komputer sudah tergabung ke domain.
NERR_WkstaNotStarted	Layanan Stasiun Kerja belum dimulai.
RPC_S_CALL_IN_PROGRESS	Panggilan prosedur jarak jauh sudah berlangsung untuk utas ini.
RPC_S_PROTSEQ_NOT_SUPPORTED	Urutan protokol panggilan prosedur jarak jauh tidak didukung.

Keterangan

Bergabung (dan membatalkan bergabung) komputer ke domain atau grup kerja hanya dapat dilakukan oleh anggota grup lokal Administrator pada komputer target. Perhatikan bahwa administrator domain dapat menetapkan persyaratan tambahan untuk bergabung dengan domain menggunakan delegasi dan penetapan hak istimewa.

Jika Anda memanggil fungsi NetJoinDomain dari jarak jauh, Anda harus menyediakan kredensial karena Anda tidak dapat mendelegasikan kredensial dalam keadaan ini.

Proses yang berbeda, atau utas yang berbeda dari proses yang sama, tidak boleh memanggil fungsi NetJoinDomain secara bersamaan. Situasi ini dapat membuat komputer dalam keadaan tidak konsisten.

Jika Anda mengalami masalah selama operasi gabungan, Anda tidak boleh menghapus akun komputer dan segera mengikuti penghapusan dengan upaya gabungan lain. Hal ini dapat menyebabkan masalah terkait replikasi yang sulit diselidiki. Ketika Anda menghapus akun komputer, tunggu hingga perubahan direplikasi ke semua pengontrol domain sebelum mencoba operasi gabungan lain.

Reboot sistem diperlukan setelah memanggil fungsi NetJoinDomain agar operasi selesai.

Windows Server 2003 dan Windows XP: Ketika panggilan ke fungsi NetJoinDomain mendahului panggilan ke fungsi NetRenameMachineInDomain , Anda harus menunda pembaruan properti SPN dan DnsHostName pada objek komputer hingga operasi ganti nama. Ini karena operasi gabungan dapat gagal dalam situasi tertentu. Contoh situasi seperti itu adalah ketika SPN yang berasal dari nama komputer saat ini tidak valid di domain baru yang bergabung dengan komputer, tetapi SPN yang berasal dari nama baru yang akan dimiliki komputer setelah operasi penggantian nama valid di domain baru. Dalam situasi ini, panggilan ke NetJoinDomain gagal kecuali Anda menunda pembaruan dua properti hingga operasi ganti nama dengan menentukan bendera NETSETUP_DEFER_SPN_SET di parameter fJoinOptions saat Anda memanggil NetJoinDomain.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	lmjoin.h (termasuk Lm.h)
Pustaka	Netapi32.lib
DLL	Netapi32.dll