Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Membuat proses baru dan utas utamanya. Proses baru berjalan dalam konteks keamanan pengguna yang diwakili oleh token yang ditentukan.
Biasanya, proses yang memanggil fungsi
Sintaksis
BOOL CreateProcessAsUserW(
[in, optional] HANDLE hToken,
[in, optional] LPCWSTR lpApplicationName,
[in, out, optional] LPWSTR lpCommandLine,
[in, optional] LPSECURITY_ATTRIBUTES lpProcessAttributes,
[in, optional] LPSECURITY_ATTRIBUTES lpThreadAttributes,
[in] BOOL bInheritHandles,
[in] DWORD dwCreationFlags,
[in, optional] LPVOID lpEnvironment,
[in, optional] LPCWSTR lpCurrentDirectory,
[in] LPSTARTUPINFOW lpStartupInfo,
[out] LPPROCESS_INFORMATION lpProcessInformation
);
Parameter
[in, optional] hToken
Handel ke token utama yang mewakili pengguna. Handel harus memiliki hak akses TOKEN_QUERY, TOKEN_DUPLICATE, dan TOKEN_ASSIGN_PRIMARY. Untuk informasi selengkapnya, lihat Hak Akses untuk Objek Access-Token. Pengguna yang diwakili oleh token harus memiliki akses baca dan jalankan ke aplikasi yang ditentukan oleh
Untuk mendapatkan token utama yang mewakili pengguna yang ditentukan, panggil fungsi
Jika hToken adalah versi terbatas dari token utama pemanggil, hak istimewa SE_ASSIGNPRIMARYTOKEN_NAME tidak diperlukan. Jika hak istimewa yang diperlukan belum diaktifkan, CreateProcessAsUser memungkinkannya selama panggilan. Untuk informasi selengkapnya, lihat Berjalan dengan Hak Istimewa Khusus.
Layanan Terminal: Proses dijalankan dalam sesi yang ditentukan dalam token. Secara default, ini adalah sesi yang sama yang disebut LogonUser. Untuk mengubah sesi, gunakan fungsi setTokenInformation
[in, optional] lpApplicationName
Nama modul yang akan dijalankan. Modul ini bisa menjadi aplikasi berbasis Windows. Ini bisa menjadi beberapa jenis modul lain (misalnya, MS-DOS atau OS/2) jika subsistem yang sesuai tersedia di komputer lokal.
String dapat menentukan jalur lengkap dan nama file modul yang akan dijalankan atau dapat menentukan nama parsial. Dalam kasus nama parsial, fungsi menggunakan drive saat ini dan direktori saat ini untuk menyelesaikan spesifikasi. Fungsi tidak akan menggunakan jalur pencarian. Parameter ini harus menyertakan ekstensi nama file; tidak ada ekstensi default yang diasumsikan.
Parameter lpApplicationName
c:\program.exec:\program files\sub.exec:\program files\sub dir\program.exec:\program files\sub dir\program name.exe Jika modul yang dapat dieksekusi adalah aplikasi 16-bit, lpApplicationName harus null, dan string yang ditunjukkan oleh lpCommandLine harus menentukan modul yang dapat dieksekusi serta argumennya. Secara default, semua aplikasi berbasis Windows 16-bit yang dibuat oleh CreateProcessAsUser dijalankan dalam VDM terpisah (setara dengan CREATE_SEPARATE_WOW_VDM di CreateProcess).
[in, out, optional] lpCommandLine
Baris perintah yang akan dijalankan. Panjang maksimum string ini adalah 32K karakter. Jika lpApplicationNameNULL, bagian nama modul lpCommandLine terbatas pada karakter MAX_PATH.
Versi Unicode dari fungsi ini, CreateProcessAsUserW, dapat memodifikasi konten string ini. Oleh karena itu, parameter ini tidak dapat menjadi penunjuk ke memori baca-saja (seperti const variabel atau string harfiah). Jika parameter ini adalah string konstanta, fungsi dapat menyebabkan pelanggaran akses.
Parameter lpCommandLine
Jika lpApplicationName dan lpCommandLine non-NULL, *lpApplicationName menentukan modul yang akan dijalankan, dan *lpCommandLine menentukan baris perintah. Proses baru dapat menggunakan GetCommandLine
Jika lpApplicationNameNULL, token spasi putih pertama yang dibatasi dari baris perintah menentukan nama modul. Jika Anda menggunakan nama file panjang yang berisi spasi, gunakan string yang dikutip untuk menunjukkan di mana nama file berakhir dan argumen dimulai (lihat penjelasan untuk parameter lpApplicationName). Jika nama file tidak berisi ekstensi, .exe ditambahkan. Oleh karena itu, jika ekstensi nama file .com, parameter ini harus menyertakan ekstensi .com. Jika nama file berakhir dalam titik (.) tanpa ekstensi, atau jika nama file berisi jalur, .exe tidak ditambahkan. Jika nama file tidak berisi jalur direktori, sistem mencari file yang dapat dieksekusi dalam urutan berikut:
- Direktori tempat aplikasi dimuat.
- Direktori saat ini untuk proses induk.
- Direktori sistem Windows 32-bit. Gunakan fungsi
GetSystemDirectory untuk mendapatkan jalur direktori ini. - Direktori sistem Windows 16-bit. Tidak ada fungsi yang mendapatkan jalur direktori ini, tetapi dicari.
- Direktori Windows. Gunakan fungsi
GetWindowsDirectory untuk mendapatkan jalur direktori ini. - Direktori yang tercantum dalam variabel lingkungan PATH. Perhatikan bahwa fungsi ini tidak mencari jalur per aplikasi yang ditentukan oleh App Paths kunci registri. Untuk menyertakan jalur per aplikasi ini dalam urutan pencarian, gunakan fungsi ShellExecute.
[in, optional] lpProcessAttributes
Penunjuk ke struktur SECURITY_ATTRIBUTES yang menentukan deskriptor keamanan untuk objek proses baru dan menentukan apakah proses anak dapat mewarisi handel yang dikembalikan ke proses. Jika
[in, optional] lpThreadAttributes
Penunjuk ke struktur SECURITY_ATTRIBUTES yang menentukan deskriptor keamanan untuk objek utas baru dan menentukan apakah proses anak dapat mewarisi handel yang dikembalikan ke utas. Jika lpThreadAttributesNULL atau lpSecurityDescriptorNULL, utas mendapatkan deskriptor keamanan default dan handel tidak dapat diwariskan. Pendeskripsi keamanan default adalah dari pengguna yang dirujuk dalam parameter hToken
[in] bInheritHandles
Jika parameter ini TRUE, setiap handel yang dapat diwariskan dalam proses panggilan diwariskan oleh proses baru. Jika parameter FALSE, handel tidak diwariskan. Perhatikan bahwa handel yang diwariskan memiliki nilai dan hak akses yang sama dengan handel asli. Untuk diskusi tambahan tentang handel yang dapat diwariskan, lihat Komentar.
Layanan Terminal: Anda tidak dapat mewarisi handel di seluruh sesi. Selain itu, jika parameter ini TRUE, Anda harus membuat proses dalam sesi yang sama dengan pemanggil.
proses Protected Process Light (PPL): Pewarisan handel generik diblokir ketika proses PPL membuat proses non-PPL karena PROCESS_DUP_HANDLE tidak diizinkan dari proses non-PPL ke proses PPL. Lihat Keamanan proses dan Akses
[in] dwCreationFlags
Bendera yang mengontrol kelas prioritas dan pembuatan proses. Untuk daftar nilai, lihat Bendera Pembuatan Proses.
Parameter ini juga mengontrol kelas prioritas proses baru, yang digunakan untuk menentukan prioritas penjadwalan utas proses. Untuk daftar nilai, lihat GetPriorityClass. Jika tidak ada bendera kelas prioritas yang ditentukan, kelas prioritas default ke NORMAL_PRIORITY_CLASS kecuali kelas prioritas proses pembuatan IDLE_PRIORITY_CLASS atau BELOW_NORMAL_PRIORITY_CLASS. Dalam hal ini, proses anak menerima kelas prioritas default dari proses panggilan.
Jika parameter dwCreationFlags memiliki nilai 0:
- Proses ini mewarisi mode kesalahan pemanggil dan konsol induk.
- Blok lingkungan untuk proses baru diasumsikan berisi karakter ANSI (lihat parameter lpEnvironment
untuk informasi tambahan). - Aplikasi berbasis Windows 16-bit berjalan di komputer Virtual DOS (VDM) bersama.
[in, optional] lpEnvironment
Pointer ke blok lingkungan untuk proses baru. Jika parameter ini NULL, proses baru menggunakan lingkungan proses panggilan.
Blok lingkungan terdiri dari blok string null-terminated dari string yang dihentikan null. Setiap string dalam bentuk berikut:
nilai
Karena tanda sama dengan digunakan sebagai pemisah, tanda tersebut tidak boleh digunakan dalam nama variabel lingkungan.
Blok lingkungan dapat berisi karakter Unicode atau ANSI. Jika blok lingkungan yang diarahkan oleh lpEnvironment berisi karakter Unicode, pastikan bahwa dwCreationFlags menyertakan CREATE_UNICODE_ENVIRONMENT.
Versi ANSI dari fungsi ini, CreateProcessAsUserA gagal jika ukuran total blok lingkungan untuk proses melebihi 32.767 karakter.
Perhatikan bahwa blok lingkungan ANSI dihentikan oleh dua byte nol: satu untuk string terakhir, satu lagi untuk mengakhiri blok. Blok lingkungan Unicode dihentikan oleh empat byte nol: dua untuk string terakhir, dua lagi untuk mengakhiri blok.
Windows Server 2003 dan Windows XP: Jika ukuran variabel lingkungan pengguna dan sistem gabungan melebihi 8192 byte, proses yang dibuat oleh CreateProcessAsUser tidak lagi berjalan dengan blok lingkungan yang diteruskan ke fungsi oleh proses induk. Sebagai gantinya, proses anak berjalan dengan blok lingkungan yang dikembalikan oleh fungsi
Untuk mengambil salinan blok lingkungan untuk pengguna tertentu, gunakan fungsi
[in, optional] lpCurrentDirectory
Jalur lengkap ke direktori saat ini untuk proses tersebut. String juga dapat menentukan jalur UNC.
Jika parameter ini NULL, proses baru akan memiliki drive dan direktori saat ini yang sama dengan proses panggilan. (Fitur ini disediakan terutama untuk shell yang perlu memulai aplikasi dan menentukan drive awal dan direktori kerjanya.)
[in] lpStartupInfo
Pointer ke
Pengguna harus memiliki akses penuh ke stasiun jendela dan desktop yang ditentukan. Jika Anda ingin prosesnya interaktif, tentukan winsta0\default. Jika anggota
Untuk mengatur atribut yang diperluas, gunakan struktur STARTUPINFOEX
Handel di
Penting Pemanggil bertanggung jawab untuk memastikan bahwa bidang handel standar di STARTUPINFO berisi nilai handel yang valid. Bidang-bidang ini disalin tidak berubah ke proses anak tanpa validasi, bahkan ketika anggota dwFlags menentukan STARTF_USESTDHANDLES. Nilai yang salah dapat menyebabkan proses anak salah tingkah atau crash. Gunakan alat verifikasi runtime Application Verifier untuk mendeteksi handel yang tidak valid.
[out] lpProcessInformation
Penunjuk ke struktur PROCESS_INFORMATION yang menerima informasi identifikasi tentang proses baru.
Handel di PROCESS_INFORMATION harus ditutup dengan CloseHandle saat tidak lagi diperlukan.
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan bukan nol.
Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.
Perhatikan bahwa fungsi kembali sebelum proses selesai diinisialisasi. Jika DLL yang diperlukan tidak dapat ditemukan atau gagal diinisialisasi, proses dihentikan. Untuk mendapatkan status penghentian proses, panggil GetExitCodeProcess.
Komentar
CreateProcessAsUser harus dapat membuka token utama proses panggilan dengan hak akses TOKEN_DUPLICATE dan TOKEN_IMPERSONATE.
Secara default, CreateProcessAsUser membuat proses baru pada stasiun jendela noninteraktif dengan desktop yang tidak terlihat dan tidak dapat menerima input pengguna. Untuk mengaktifkan interaksi pengguna dengan proses baru, Anda harus menentukan nama stasiun jendela interaktif default dan desktop, "winsta0\default", di lpDesktop anggota struktur STARTUPINFO. Selain itu, sebelum memanggil CreateProcessAsUser, Anda harus mengubah daftar kontrol akses diskresi (DACL) dari stasiun jendela interaktif default dan desktop default. DACL untuk stasiun jendela dan desktop harus memberikan akses ke pengguna atau sesi masuk yang diwakili oleh parameter
CreateProcessAsUser tidak memuat profil pengguna yang ditentukan ke dalam kunci registri HKEY_USERS. Oleh karena itu, untuk mengakses informasi dalam kunci registri
Jika parameter
Fungsi
CreateProcessAsUser memungkinkan Anda mengakses direktori yang ditentukan dan gambar yang dapat dieksekusi dalam konteks keamanan pemanggil atau pengguna target. Secara default, CreateProcessAsUser mengakses direktori dan gambar yang dapat dieksekusi dalam konteks keamanan pemanggil. Dalam hal ini, jika pemanggil tidak memiliki akses ke direktori dan gambar yang dapat dieksekusi, fungsi gagal. Untuk mengakses direktori dan gambar yang dapat dieksekusi menggunakan konteks keamanan pengguna target, tentukan
Proses ini diberi pengidentifikasi proses. Pengidentifikasi valid sampai proses berakhir. Ini dapat digunakan untuk mengidentifikasi proses, atau ditentukan dalam fungsi
Alur panggilan dapat menggunakan fungsi
Cara yang disukai untuk mematikan proses adalah dengan menggunakan fungsi ExitProcess
Secara default, meneruskan
Keterangan Keamanan
Parameter lpApplicationName LPTSTR szCmdline[] = _tcsdup(TEXT("C:\\Program Files\\MyApp"));
CreateProcessAsUser(hToken, NULL, szCmdline, /*...*/ );
Jika pengguna jahat membuat aplikasi yang disebut "Program.exe" pada sistem, program apa pun yang salah memanggil CreateProcessAsUser menggunakan direktori Program Files akan menjalankan aplikasi ini alih-alih aplikasi yang dimaksudkan.
Untuk menghindari masalah ini, jangan lulus NULL untuk lpApplicationName. Jika Anda lulus null untuk lpApplicationName, gunakan tanda kutip di sekitar jalur yang dapat dieksekusi di lpCommandLine, seperti yang ditunjukkan pada contoh di bawah ini.
LPTSTR szCmdline[] = _tcsdup(TEXT("\"C:\\Program Files\\MyApp\""));
CreateProcessAsUser(hToken, NULL, szCmdline, /*...*/);
Contoh
Misalnya, lihat Memulai Proses Klien Interaktif.
Nota
Header processthreadsapi.h mendefinisikan CreateProcessAsUser sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor 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
| Syarat | Nilai |
|---|---|
| klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
| server minimum yang didukung |
Windows Server 2003 [hanya aplikasi desktop] |
| Platform Target |
Windows |
| Header |
processthreadsapi.h (termasuk Windows.h) |
| Pustaka |
Advapi32.lib |
| DLL |
Advapi32.dll |
Lihat juga
ExitProcess
GetExitCodeProcess
Proses
STARTUPINFOEX
WaitForInputIdle