CreateDesktopExA-Funktion (winuser.h)

Artikel
03/04/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, die entweder vom System zum Zeitpunkt der Prozesserstellung zugewiesen oder durch die SetProcessWindowStation-Funktion festgelegt wird.

Syntax

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

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	Ermöglicht Prozessen, die in anderen Konten auf dem Desktop ausgeführt werden, das Festlegen von Hooks in diesem Prozess.

[in] dwDesiredAccess

Der angeforderte Zugriff auf den Desktop. Eine Liste der Werte finden Sie unter Desktopsicherheit und Zugriffsrechte.

Dieser Parameter muss das DESKTOP_CREATEWINDOW Zugriffsrecht enthalten, da CreateDesktop intern das Handle verwendet, um ein Fenster zu erstellen.

[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 das Handle nicht geerbt werden.

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

[in] ulHeapSize

Die Größe des Desktopheaps 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, ist die Funktion erfolgreich 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 es zu schließen.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn der dwDesiredAccess-Parameter die 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, wird durch die Größe des Systemdesktopheaps 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 Desktopheaps erhöhen oder den für jeden Desktop reservierten Standardheap in der interaktiven Fensterstation 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 gilt, in Kilobytes.
Der zweite SharedSection-Wert ist die Größe des Desktopheaps, der für jeden Desktop benötigt wird, der in der interaktiven Fensterstation WinSta0 erstellt wird, in Kilobyte.
Der dritte SharedSection-Wert ist die Größe des Desktopheaps, der für jeden Desktop benötigt wird, der in einer nicht interaktiven Fensterstation erstellt wird( in Kilobytes).

Die Standardgröße des Desktopheaps hängt von Faktoren wie der Hardwarearchitektur ab. Um die Größe des Desktopheaps abzurufen, rufen Sie die GetUserObjectInformation-Funktion mit UOI_HEAPSIZE auf.

Hinweis

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
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll