CreateDesktopExW-Funktion (winuser.h)

Artikel
11/20/2024

Erstellt einen neuen Desktop mit dem angegebenen Heap, ordnet ihn der aktuellen Fensterstation des aufrufenden Prozesses zu und weist ihn dem aufrufenden Thread zu. Der aufrufende Prozess muss über eine zugeordnete Fensterstation verfügen, entweder zur Prozesserstellungszeit vom System zugewiesen oder von der SetProcessWindowStation-Funktion festgelegt.

Syntax

HDESK CreateDesktopExW(
  [in]           LPCWSTR               lpszDesktop,
                 LPCWSTR               lpszDevice,
                 DEVMODEW              *pDevmode,
  [in]           DWORD                 dwFlags,
  [in]           ACCESS_MASK           dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES lpsa,
  [in]           ULONG                 ulHeapSize,
                 PVOID                 pvoid
);

Parameter

[in] lpszDesktop

Der Name des zu erstellenden Desktops. Bei Desktopnamen wird die Groß-/Kleinschreibung nicht beachtet und dürfen keine umgekehrten Schrägstriche (\) enthalten.

lpszDevice

Dieser Parameter ist reserviert und muss NULL sein.

pDevmode

Dieser Parameter ist reserviert und muss NULL sein.

[in] dwFlags

Dieser Parameter kann null oder der folgende Wert sein.

Wert	Bedeutung
DF_ALLOWOTHERACCOUNTHOOK 0x0001	Aktiviert Prozesse, die in anderen Konten auf dem Desktop ausgeführt werden, um Hooks in diesem Prozess festzulegen.

[in] dwDesiredAccess

Der angeforderte Zugriff auf den Desktop. Eine Liste der Werte finden Sie unter Desktop security and access rights.

Dieser Parameter muss das DESKTOP_CREATEWINDOW Zugriffsrecht enthalten, da intern CreateDesktop- das Handle zum Erstellen eines Fensters verwendet.

[in, optional] lpsa

Ein Zeiger auf eine SECURITY_ATTRIBUTES Struktur, die bestimmt, ob das zurückgegebene Handle von untergeordneten Prozessen geerbt werden kann. Wenn lpsa NULL ist, kann der Handle nicht geerbt werden.

Der lpSecurityDescriptor Mitglied der Struktur gibt einen Sicherheitsdeskriptor für den neuen Desktop an. Wenn dieser Parameter NULL ist, erbt der Desktop seine Sicherheitsbeschreibung von der übergeordneten Fensterstation.

[in] ulHeapSize

Die Größe des Desktop-Heaps in Kilobyte.

pvoid

Dieser Parameter ist reserviert und muss NULL sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für den neu erstellten Desktop. Wenn der angegebene Desktop bereits vorhanden ist, wird die Funktion erfolgreich ausgeführt und gibt ein Handle an den vorhandenen Desktop zurück. Wenn Sie mit der Verwendung des Handle fertig sind, rufen Sie die CloseDesktop--Funktion auf, um sie zu schließen.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Wenn der parameter dwDesiredAccess den READ_CONTROL, WRITE_DAC oder WRITE_OWNER Standardzugriffsrechte angibt, müssen Sie auch die DESKTOP_READOBJECTS und DESKTOP_WRITEOBJECTS Zugriffsrechte anfordern.

Die Anzahl der Desktops, die erstellt werden können, ist durch die Größe des Systemdesktop-Heaps begrenzt. Desktopobjekte verwenden den Heap zum Speichern von Ressourcen. Sie können die Anzahl der Desktops erhöhen, die erstellt werden können, indem Sie die Größe des Desktop-Heaps erhöhen oder den Für jeden Desktop in der interaktiven Fensterstation reservierten Heap verringern. Dieser Wert wird in der SharedSection-Teilzeichenfolge des folgenden Registrierungswerts angegeben: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SubSystems\Windows. Die Standarddaten für diesen Registrierungswert sind wie folgt:

%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

Die Werte für die SharedSection-Teilzeichenfolge werden wie folgt beschrieben:

Der erste SharedSection-Wert ist die Größe des freigegebenen Heaps, der für alle Desktops in Kilobyte gemeinsam ist.
Der zweite SharedSection-Wert ist die Größe des Desktop-Heaps, der für jeden Desktop benötigt wird, der in der interaktiven Fensterstation WinSta0 in Kilobyte erstellt wird.
Der dritte SharedSection-Wert ist die Größe des Desktop-Heaps, der für jeden Desktop benötigt wird, der in einer nichtinteraktiven Fensterstation in Kilobyte erstellt wird.

Die Standardgröße des Desktop-Heaps hängt von Faktoren wie der Hardwarearchitektur ab. Rufen Sie zum Abrufen der Größe des Desktop-Heaps die GetUserObjectInformation-Funktion mit UOI_HEAPSIZE auf.

Anmerkung

Der winuser.h-Header definiert CreateDesktopEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winuser.h (enthalten Windows.h)
Library	User32.lib
DLL-	User32.dll