CreateDesktop

The CreateDesktop function creates a new desktop on the window station associated with the calling process. It returns a handle that can be used to access the new desktop. The calling process must have an associated window station, either assigned by the system at process creation time or set by SetProcessWindowStation. A desktop is a secure object contained within a window station object. A desktop has a logical display surface and contains windows, menus, and hooks.

HDESK CreateDesktop(

LPCTSTR lpszDesktop, // name of the new desktop
LPCTSTR lpszDevice, // reserved; must be NULL.
LPDEVMODE pDevMode, // reserved; must be NULL
DWORD dwFlags, // flags to control interaction with other applications
DWORD dwDesiredAccess, // specifies access of returned handle
LPSECURITY_ATTRIBUTES lpsa // specifies security attributes of the desktop
);  

Parameters

lpszDesktop

Points to a null-terminated string specifying the name of the desktop to be created. Desktop names are case-insensitive and may not contain backslash characters (\).

lpszDevice

Reserved; must be NULL. The desktop uses the default display driver loaded at boot time.

pDevMode

Reserved; must be NULL.

dwFlags

A bit flag parameter that controls how the calling application will cooperate with other applications on the desktop. This parameter can specify zero or the following value:

Value Description
DF_ALLOWOTHERACCOUNTHOOK Allows processes running in other accounts on the desktop to set hooks in this process.

dwDesiredAccess

Specifies the type of access to the desktop. This parameter can be one or more of the following values:

Value Description
DESKTOP_CREATEMENU Required to create a menu on the desktop.
DESKTOP_CREATEWINDOW Required to create a window on the desktop.
DESKTOP_ENUMERATE Required for the desktop to be enumerated.
DESKTOP_HOOKCONTROL Required to establish any of the window hooks.
DESKTOP_JOURNALPLAYBACK Required to perform journal playback on the desktop.
DESKTOP_JOURNALRECORD Required to perform journal recording on the desktop.
DESKTOP_READOBJECTS Required to read objects on the desktop.
DESKTOP_SWITCHDESKTOP Required to activate the desktop using the SwitchDesktop function.
DESKTOP_WRITEOBJECTS Required to write objects on the desktop.

lpsa

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.

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

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

Return Values

If the function succeeds, the return value is a handle to the newly created desktop.

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

Remarks

The CreateDesktop function returns a handle that can be used to access the desktop.

See Also

SECURITY_ATTRIBUTES, SetProcessWindowStation, SwitchDesktop