CreateDesktopExA function (winuser.h)

Creates a new desktop with the specified heap, associates it with the current window station of the calling process, and assigns it to the calling thread. The calling process must have an associated window station, either assigned by the system at process creation time or set by the SetProcessWindowStation function.

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
);

Parameters

[in] lpszDesktop

The name of the desktop to be created. Desktop names are case-insensitive and may not contain backslash characters (\).

lpszDevice

This parameter is reserved and must be NULL.

pDevmode

This parameter is reserved and must be NULL.

[in] dwFlags

This parameter can be zero or the following value.

Value Meaning
DF_ALLOWOTHERACCOUNTHOOK
0x0001
Enables processes running in other accounts on the desktop to set hooks in this process.

[in] dwDesiredAccess

The requested access to the desktop. For a list of values, see Desktop Security and Access Rights.

This parameter must include the DESKTOP_CREATEWINDOW access right, because internally CreateDesktop uses the handle to create a window.

[in, optional] lpsa

A pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpsa is NULL, the handle cannot be inherited.

The lpSecurityDescriptor member of the structure specifies a security descriptor for the new desktop. If this parameter is NULL, the desktop inherits its security descriptor from the parent window station.

[in] ulHeapSize

The size of the desktop heap, in kilobytes.

pvoid

This parameter is reserved and must be NULL.

Return value

If the function succeeds, the return value is a handle to the newly created desktop. If the specified desktop already exists, the function succeeds and returns a handle to the existing desktop. When you are finished using the handle, call the CloseDesktop function to close it.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If the dwDesiredAccess parameter specifies the READ_CONTROL, WRITE_DAC, or WRITE_OWNER standard access rights, you must also request the DESKTOP_READOBJECTS and DESKTOP_WRITEOBJECTS access rights.

The number of desktops that can be created is limited by the size of the system desktop heap. Desktop objects use the heap to store resources. You can increase the number of desktops that can be created by increasing the size of the desktop heap or by reducing the default heap reserved for each desktop in the interactive window station. This value is specified in the SharedSection substring of the following registry value: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SubSystems\Windows. The default data for this registry value is as follows:

%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

The values for the SharedSection substring are described as follows:

  • The first SharedSection value is the size of the shared heap common to all desktops, in kilobytes.
  • The second SharedSection value is the size of the desktop heap needed for each desktop that is created in the interactive window station, WinSta0, in kilobytes.
  • The third SharedSection value is the size of the desktop heap needed for each desktop that is created in a noninteractive window station, in kilobytes.

The default size of the desktop heap depends on factors such as hardware architecture. To retrieve the size of the desktop heap, call the GetUserObjectInformation function with UOI_HEAPSIZE.

Note

The winuser.h header defines CreateDesktopEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header winuser.h (include Windows.h)
Library User32.lib
DLL User32.dll

See also

CloseDesktop

Desktops

SECURITY_ATTRIBUTES

SetProcessWindowStation

SwitchDesktop

Window Station and Desktop Functions