CreateDesktopW-Funktion (winuser.h)

Artikel
11/20/2024

Erstellt einen neuen Desktop, 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.

Um die Größe des Heaps für den Desktop anzugeben, verwenden Sie die CreateDesktopEx--Funktion.

Syntax

HDESK CreateDesktopW(
  [in]           LPCWSTR               lpszDesktop,
                 LPCWSTR               lpszDevice,
                 DEVMODEW              *pDevmode,
  [in]           DWORD                 dwFlags,
  [in]           ACCESS_MASK           dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES lpsa
);

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

Reserviert; muss NULL-sein.

pDevmode

Reserviert; 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 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.

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_DACoder 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, was 48 MB beträgt. Desktopobjekte verwenden den Heap zum Speichern von Ressourcen. Sie können die Anzahl der Desktops erhöhen, die erstellt werden können, indem Sie den Für jeden Desktop in der interaktiven Fensterstation reservierten Heap verringern. Dieser Wert wird in der Teilzeichenfolge "SharedSection" 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 Teilzeichenfolge "SharedSection" werden wie folgt beschrieben:

Der erste Wert "SharedSection" ist die Größe des freigegebenen Heaps, der für alle Desktops in Kilobyte gemeinsam ist.
Der zweite Wert "SharedSection" 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 Wert "SharedSection" ist die Größe des Desktop-Heaps, der für jeden Desktop benötigt wird, der in einer nichtinteraktiven Fensterstation in Kilobyte erstellt wird.

Anmerkung

Der winuser.h-Header definiert CreateDesktop 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 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winuser.h (enthalten Windows.h)
Library	User32.lib
DLL-	User32.dll
API-Satz	ext-ms-win-ntuser-windowstation-l1-1-0 (eingeführt in Windows 8)