Fungsi NetCreateProvisioningPackage (lmjoin.h)

Artikel
03/14/2023

Fungsi NetCreateProvisioningPackage membuat paket provisi yang menyediakan akun komputer untuk digunakan nanti dalam operasi gabungan domain offline. Paket juga dapat berisi informasi tentang sertifikat dan kebijakan untuk ditambahkan ke komputer selama provisi.

Sintaks

NET_API_STATUS NET_API_FUNCTION NetCreateProvisioningPackage(
  [in]            PNETSETUP_PROVISIONING_PARAMS pProvisioningParams,
  [out, optional] PBYTE                         *ppPackageBinData,
  [out, optional] DWORD                         *pdwPackageBinDataSize,
  [out, optional] LPWSTR                        *ppPackageTextData
);

Parameter

[in] pProvisioningParams

Penunjuk ke struktur NETSETUP_PROVISIONING_PARAMS yang berisi informasi tentang paket provisi.

Nilai berikut didefinisikan untuk anggota struktur ini:

Nilai	Makna
dwVersion	Versi Windows dalam paket provisi. Anggota ini harus menggunakan nilai berikut yang ditentukan dalam file header Lmjoin.h : NETSETUP_PROVISIONING_PARAMS_CURRENT_VERSION (0x00000001)
lpDomain	Penunjuk ke string karakter yang dihentikan null konstanta yang menentukan nama domain tempat akun komputer dibuat.
lpMachineName	Penunjuk ke string karakter yang dihentikan null konstanta yang menentukan nama pendek komputer tempat atribut akun komputer sAMAccountName diturunkan dengan menambahkan '$'. Parameter ini harus berisi DNS atau nama komputer NetBIOS yang valid.
lpMachineAccountOU	Penunjuk opsional ke string karakter yang dihentikan null konstan yang berisi nama format RFC 1779 dari unit organisasi (OU) tempat akun komputer akan dibuat. 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. Jika parameter ini NULL, kontainer objek komputer yang terkenal akan digunakan seperti yang diterbitkan di domain.
lpDcName	Penunjuk opsional ke string karakter yang dihentikan null konstanta yang berisi nama pengendali domain ke target.
dwProvisionOptions	Sekumpulan bendera bit yang menentukan opsi provisi. Parameter ini dapat berupa satu atau beberapa nilai yang ditentukan untuk parameter dwOptions yang diteruskan ke fungsi NetProvisionComputerAccount . Nilai yang mungkin ini didefinisikan dalam file header Lmjoin.h . Opsi NETSETUP_PROVISION_ROOT_CA_CERTS hanya didukung pada Windows 8 dan Windows Server 2012.
aCertTemplateNames	Penunjuk opsional ke array nama templat sertifikat yang dihentikan NULL.
cCertTemplateNames	Ketika aCertTemplateNames bukan NULL, anggota ini menyediakan jumlah eksplisit jumlah item dalam array.
aMachinePolicyNames	Penunjuk opsional ke array nama kebijakan komputer yang dihentikan NULL.
cMachinePolicyNames	Ketika aMachinePolicyNames bukan NULL, anggota ini menyediakan jumlah eksplisit jumlah item dalam array.
aMachinePolicyPaths	Penunjuk opsional ke array string karakter. Setiap elemen array adalah string karakter yang dihentikan NULL yang menentukan jalur lengkap atau parsial ke file dalam format File Kebijakan Registri. Untuk informasi selengkapnya tentang Format File Kebijakan Registri, lihat Format File Kebijakan Registri Jalur bisa menjadi jalur UNC pada server jarak jauh.
cMachinePolicyPaths	Ketika aMachinePolicyPaths bukan NULL, anggota ini menyediakan jumlah eksplisit jumlah item dalam array.

[out, optional] ppPackageBinData

Penunjuk opsional yang akan menerima paket yang diperlukan oleh fungsi NetRequestOfflineDomainJoin untuk menyelesaikan gabungan domain offline, jika fungsi NetProvisionComputerAccount berhasil diselesaikan. Data dikembalikan sebagai buffer biner buram yang dapat diteruskan ke fungsi NetRequestOfflineDomainJoin .

Jika parameter ini NULL, parameter pPackageTextData tidak boleh NULL. Jika parameter ini bukan NULL, maka parameter pPackageTextData harus NULL.

[out, optional] pdwPackageBinDataSize

Penunjuk ke nilai yang menerima ukuran, dalam byte, dari buffer yang dikembalikan dalam parameter pProvisionBinData .

Parameter ini tidak boleh NULL jika parameter pPackageBinData bukan NULL. Parameter ini harus NULL ketika parameter pPackageBinData adalah NULL.

[out, optional] ppPackageTextData

Penunjuk opsional yang akan menerima paket yang diperlukan oleh fungsi NetRequestOfflineDomainJoin untuk menyelesaikan gabungan domain offline, jika fungsi NetProvisionComputerAccount berhasil diselesaikan. Data dikembalikan dalam formulir string untuk disematkan dalam file jawaban penyiapan tanpa pengawas.

Jika parameter ini NULL, parameter pPackageBinData tidak boleh NULL. Jika parameter ini bukan NULL, parameter pPackageBinData harus NULL.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan 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 pemanggil tidak memiliki hak istimewa yang memadai untuk menyelesaikan operasi.
ERROR_INVALID_DOMAIN_ROLE	Operasi ini hanya diperbolehkan untuk Pengendali Domain Utama domain. Kesalahan ini dikembalikan jika nama pengendali domain ditentukan dalam lpDcName dari struct NETSETUP_PROVISIONING_PARAMS yang ditunjukkan oleh parameter pProvisioningParams , tetapi komputer yang ditentukan tidak dapat divalidasi sebagai pengendali domain untuk domain target yang ditentukan dalam lpDomaindari NETSETUP_PROVISIONING_PARAMS.
ERROR_INVALID_PARAMETER	Parameter salah. Kesalahan ini juga dikembalikan jika kedua parameter pProvisioningParams adalah NULL. Kesalahan ini juga dikembalikan jika anggota lpDomain atau lpMachineName dari struct NETSETUP_PROVISIONING_PARAMS yang ditunjukkan oleh parameter pProvisioningParams adalah NULL.
ERROR_NO_SUCH_DOMAIN	Domain yang ditentukan tidak ada.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan jika anggota lpMachineAccountOU ditentukan dalam struct NETSETUP_PROVISIONING_PARAMS yang diacu oleh parameter pProvisioningParams dan pengendali domain berjalan pada versi Windows yang lebih lama yang tidak mendukung parameter ini.
NERR_DS8DCRequired	Pengendali domain yang ditentukan tidak memenuhi persyaratan versi untuk operasi ini.
NERR_LDAPCapableDCRequired	Operasi ini memerlukan pengendali domain yang mendukung LDAP.
NERR_UserExists	Akun sudah ada di domain dan bit NETSETUP_PROVISION_REUSE_ACCOUNT tidak ditentukan dalam anggota dwProvisionOptions dari struktur NETSETUP_PROVISIONING_PARAMS yang diarahkan oleh parameter pProvisioningParams .
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

Fungsi NetCreateProvisioningPackage didukung pada Windows 8 dan Windows Server 2012 untuk operasi gabungan offline. Untuk Windows 7, gunakan fungsi NetProvisionComputerAccount .

Fungsi NetCreateProvisioningPackage digunakan untuk menyediakan akun komputer untuk digunakan nanti dalam operasi gabungan domain offline menggunakan fungsi NetRequestProvisioningPackageInstall .

Skenario gabungan domain offline menggunakan dua fungsi:

NetCreateProvisioningPackage adalah fungsi provisi yang pertama kali dipanggil untuk melakukan operasi jaringan yang diperlukan untuk membuat dan mengonfigurasi objek komputer di Direktori Aktif. Output dari NetCreateProvisioningPackage adalah paket yang digunakan untuk langkah berikutnya.
NetRequestProvisioningPackageInstall, fungsi inisialisasi gambar, dipanggil untuk menyuntikkan output dari fungsi provisi NetCreateProvisioningPackage ke dalam gambar sistem operasi Windows untuk digunakan selama pra-instalasi dan pasca-instalasi.

Perubahan pada kode inisialisasi Windows akan mendeteksi status tersimpan ini dan memengaruhi bagian gabungan domain khusus lokal.

Ketika pointer keluar pPackageBinData dan pdwPackageBinDataSize digunakan, atur pPackageTextData out pointer ke NULL. Ketika pPackageTextData digunakan, atur pPackageBinData dan pdwPackageBinDataSize out pointer ke NULL.

Parameter pProvisioningParams menentukan data untuk disertakan dalam paket provisi. Paket ini mencakup informasi yang relevan dengan gabungan domain, dan juga dapat mencakup informasi tentang kebijakan dan sertifikat untuk diinstal pada komputer. Paket provisi dapat digunakan dengan empat cara:

Bergabung ke Domain
Gabungan domain dan penginstalan sertifikat
Gabungan domain dan penginstalan kebijakan
Gabungan domain dan penginstalan sertifikat dan kebijakan

Fungsi NetCreateProvisioningPackage membuat atau menggunakan kembali akun komputer di domain, mengumpulkan semua metadata yang diperlukan dan mengembalikannya dalam paket. Paket dapat dikonsumsi oleh operasi permintaan gabungan domain offline yang menyediakan semua input yang diperlukan untuk menyelesaikan gabungan domain selama boot pertama tanpa operasi jaringan (hanya pembaruan status lokal).

Catatan Keamanan: Paket yang dikembalikan oleh fungsi NetCreateProvisioningPackage berisi data yang sangat sensitif. Ini harus diperlakukan sama amannya dengan kata sandi teks biasa. Paket berisi kata sandi akun komputer dan informasi lain tentang domain, termasuk nama domain, nama pengendali domain, dan ID keamanan (SID) domain. Jika paket sedang diangkut secara fisik atau melalui jaringan, perawatan harus dilakukan untuk mengangkutnya dengan aman. Desain tidak membuat ketentuan untuk mengamankan data ini. Masalah ini ada saat ini dengan file jawaban penyiapan tanpa pengawas yang dapat membawa sejumlah rahasia termasuk kata sandi pengguna domain. Penelepon harus mengamankan paket. Solusi untuk masalah ini bervariasi. Sebagai contoh, kunci yang telah ditukar sebelumnya dapat digunakan untuk mengenkripsi sesi antara konsumen dan entitas provisi yang memungkinkan transfer paket yang aman.

Paket yang dikembalikan dalam parameter pPackageBinData oleh fungsi NetCreateProvisioningPackage diberi versi untuk memungkinkan skenario interoperabilitas dan kemampuan layanan antara versi Windows yang berbeda (seperti bergabung dengan klien, menyediakan komputer, dan menggunakan pengendali domain). Paket yang dibuat pada Windows 8 atau Windows Server 2012 dapat digunakan Windows 7 atau Windows Server 2008 R2, namun hanya informasi gabungan domain yang akan berlaku (sertifikat dan kebijakan tidak didukung). Skenario gabungan offline saat ini tidak membatasi masa pakai paket yang dikembalikan oleh fungsi NetCreateProvisioningPackage .

Untuk gabungan domain offline, pemeriksaan akses yang dilakukan tergantung pada konfigurasi domain. Pembuatan akun komputer diaktifkan menggunakan tiga metode:

Administrator domain memiliki hak untuk membuat akun komputer.
SD pada kontainer dapat mendelegasikan hak untuk membuat akun komputer.
Secara default, pengguna yang diautentikasi dapat membuat akun komputer dengan hak istimewa. Pengguna terautentikasi dibatasi untuk membuat sejumlah akun terbatas yang ditentukan sebagai kuota pada domain (nilai defaultnya adalah 10). Untuk informasi selengkapnya, lihat atribut ms-DS-MachineAccountQuota dalam skema Direktori Aktif.

Fungsi NetCreateProvisioningPackage hanya berfungsi dengan pengontrol domain bisa-tulis dan tidak berfungsi terhadap pengontrol domain baca-saja. Setelah provisi dilakukan terhadap pengendali domain bisa-tulis dan akun direplikasi ke pengontrol domain baca-saja, bagian lain dari operasi gabungan domain offline tidak memerlukan akses ke pengendali domain.

Jika fungsi NetCreateProvisioningPackage berhasil, penunjuk di parameter pPackageBinData atau pPackageTextData (tergantung pada parameter mana yang bukan NULL) dikembalikan dengan data serial untuk digunakan dalam operasi gabungan offline atau sebagai teks dalam file penyiapan tanpa pengawasan.

Semua fase proses provisi ditambahkan ke file NetSetup.log di komputer lokal. Proses provisi dapat mencakup hingga tiga komputer yang berbeda: komputer tempat paket provisi dibuat, komputer yang meminta penginstalan paket, dan komputer tempat paket diinstal. Akan ada NetSetup.log informasi file yang disimpan di ketiga komputer sesuai dengan operasi yang dilakukan. Meninjau konten file-file ini adalah cara paling umum untuk memecahkan masalah kesalahan provisi online dan offline. Operasi provisi yang dilakukan oleh admin dicatat ke file NetSetup.log di %WINDIR%\Debug. Operasi provisi yang dilakukan oleh non-admin dicatat ke file NetSetup.log di folder %USERPROFILE%\Debug .

Untuk informasi selengkapnya tentang operasi gabungan domain offline, lihat Panduan Langkah demi Langkah Gabungan Domain Offline.

Bergabung (dan membatalkan bergabung) komputer ke domain menggunakan NetJoinDomain dan NetUnjoinDomain hanya 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.

Persyaratan


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