Fungsi CreateDesktopExA (winuser.h)

Artikel
08/27/2023

Membuat desktop baru dengan tumpukan yang ditentukan, mengaitkannya dengan stasiun jendela saat ini dari proses panggilan, dan menetapkannya ke utas panggilan. Proses panggilan harus memiliki stasiun jendela terkait, baik yang ditetapkan oleh sistem pada waktu pembuatan proses atau diatur oleh fungsi SetProcessWindowStation .

Sintaks

HDESK CreateDesktopExA(
  [in]           LPCSTR                lpszDesktop,
                 LPCSTR                lpszDevice,
                 DEVMODEA              *pDevmode,
  [in]           DWORD                 dwFlags,
  [in]           ACCESS_MASK           dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES lpsa,
  [in]           ULONG                 ulHeapSize,
                 PVOID                 pvoid
);

Parameter

[in] lpszDesktop

Nama desktop yang akan dibuat. Nama desktop tidak peka huruf besar/kecil dan mungkin tidak berisi karakter garis miring terbelakang (\).

lpszDevice

Parameter ini dicadangkan dan harus NULL.

pDevmode

Parameter ini dicadangkan dan harus NULL.

[in] dwFlags

Parameter ini bisa nol atau nilai berikut.

Nilai	Makna
DF_ALLOWOTHERACCOUNTHOOK 0x0001	Memungkinkan proses yang berjalan di akun lain di desktop untuk mengatur hook dalam proses ini.

[in] dwDesiredAccess

Akses yang diminta ke desktop. Untuk daftar nilai, lihat Keamanan Desktop dan Hak Akses.

Parameter ini harus menyertakan hak akses DESKTOP_CREATEWINDOW, karena secara internal CreateDesktop menggunakan handel untuk membuat jendela.

[in, optional] lpsa

Penunjuk ke struktur SECURITY_ATTRIBUTES yang menentukan apakah handel yang dikembalikan dapat diwariskan oleh proses anak. Jika lpsa NULL, handel tidak dapat diwariskan.

Anggota lpSecurityDescriptor dari struktur menentukan deskriptor keamanan untuk desktop baru. Jika parameter ini NULL, desktop mewarisi deskriptor keamanannya dari stasiun jendela induk.

[in] ulHeapSize

Ukuran timbunan desktop, dalam kilobyte.

pvoid

Parameter ini dicadangkan dan harus NULL.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke desktop yang baru dibuat. Jika desktop yang ditentukan sudah ada, fungsi berhasil dan mengembalikan handel ke desktop yang ada. Setelah selesai menggunakan handel, panggil fungsi CloseDesktop untuk menutupnya.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Jika parameter dwDesiredAccess menentukan hak akses standar READ_CONTROL, WRITE_DAC, atau WRITE_OWNER, Anda juga harus meminta hak akses DESKTOP_READOBJECTS dan DESKTOP_WRITEOBJECTS.

Jumlah desktop yang dapat dibuat dibatasi oleh ukuran timbunan desktop sistem. Objek desktop menggunakan timbunan untuk menyimpan sumber daya. Anda dapat meningkatkan jumlah desktop yang dapat dibuat dengan meningkatkan ukuran tumpukan desktop atau dengan mengurangi tumpukan default yang dicadangkan untuk setiap desktop di stasiun jendela interaktif. Nilai ini ditentukan dalam substring SharedSection dari nilai registri berikut: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SubSystems\Windows. Data default untuk nilai registri ini adalah sebagai berikut:

%SystemRoot%\system32\csrss.exe ObjectDirectory=\Windows SharedSection=1024,3072,512 Windows=On SubSystemType=Windows ServerDll=basesrv,1 ServerDll=winsrv:UserServerDllInitialization,3 ServerDll=winsrv:ConServerDllInitialization,2 ProfileControl=Off MaxRequestThreads=16

Nilai untuk substring SharedSection dijelaskan sebagai berikut:

Nilai SharedSection pertama adalah ukuran timbunan bersama yang umum untuk semua desktop, dalam kilobyte.
Nilai SharedSection kedua adalah ukuran timbunan desktop yang diperlukan untuk setiap desktop yang dibuat di stasiun jendela interaktif, WinSta0, dalam kilobyte.
Nilai SharedSection ketiga adalah ukuran timbunan desktop yang diperlukan untuk setiap desktop yang dibuat di stasiun jendela noninteraktif, dalam kilobyte.

Ukuran default timbunan desktop tergantung pada faktor-faktor seperti arsitektur perangkat keras. Untuk mengambil ukuran timbunan desktop, panggil fungsi GetUserObjectInformation dengan UOI_HEAPSIZE.

Catatan

Header winuser.h mendefinisikan CreateDesktopEx 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 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	winuser.h (sertakan Windows.h)
Pustaka	User32.lib
DLL	User32.dll