CreateDesktopA-Funktion (winuser.h)

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

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

Syntax

HDESK CreateDesktopA(
  [in]           LPCSTR                lpszDesktop,
                 LPCSTR                lpszDevice,
                 DEVMODEA              *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	Ermöglicht Es Prozessen, die in anderen Konten auf dem Desktop ausgeführt werden, Hooks in diesem Prozess festzulegen.

[in] dwDesiredAccess

Der 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.

Das lpSecurityDescriptor-Element 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, 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, die 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 standardmäßigen Heap reduzieren, der für jeden Desktop in der interaktiven Fensterstation reserviert ist. Dieser Wert wird in der Unterzeichenfolge "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 "SharedSection"-Wert ist die Größe des freigegebenen Heaps, der für alle Desktops gemeinsam ist, in Kb.
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 KB.
Der dritte Wert "SharedSection" ist die Größe des Desktopheaps, der für jeden Desktop benötigt wird, der in einer nichtinteraktiven Fensterstation erstellt wird, in Kilobyte.

Hinweis

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 nicht codierungsneutralem Code 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 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (einschließlich Windows.h)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-windowstation-l1-1-0 (eingeführt in Windows 8)