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 Pointer 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 access rights the returned handle has to the desktop. This parameter must include the DESKTOP_CREATEWINDOW flag because internally CreateDesktop uses the handle to create a window. In addition, you can specify any of the standard access rights, such as READ_CONTROL or WRITE_DAC, and a combination of the following desktop-specific access rights. 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. 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. Return Values 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.Res The CreateDesktop function returns a handle that can be used to access the desktop.If the dwDesiredAccess parameter specifies the READ_CONTROL, WRITE_DAC, or WRITE_OWNER standard access rights to access the security descriptor of the desktop object, you must also request the DESKTOP_READOBJECTS and DESKTOP_WRITEOBJECTS access rights.QuickInfo Windows NT: Requires version 3.51 or later. Windows: Unsupported. Windows CE: Unsupported. Header: Declared in winuser.h. Import Library: Use user32.lib. Unicode: Implemented as Unicode and ANSI versions on Windows NT.See Also Window Stations and Desktops Overview, Window Station and Desktop Functions, CloseDesktop, SECURITY_ATTRIBUTES, SetProcessWindowStation, SwitchDesktop
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
Pointer 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 access rights the returned handle has to the desktop. This parameter must include the DESKTOP_CREATEWINDOW flag because internally CreateDesktop uses the handle to create a window. In addition, you can specify any of the standard access rights, such as READ_CONTROL or WRITE_DAC, and a combination of the following desktop-specific access rights. 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.
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. Return Values
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.Res
The CreateDesktop function returns a handle that can be used to access the desktop.If the dwDesiredAccess parameter specifies the READ_CONTROL, WRITE_DAC, or WRITE_OWNER standard access rights to access the security descriptor of the desktop object, you must also request the DESKTOP_READOBJECTS and DESKTOP_WRITEOBJECTS access rights.QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winuser.h.
Import Library: Use user32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.See Also
Window Stations and Desktops Overview, Window Station and Desktop Functions, CloseDesktop, SECURITY_ATTRIBUTES, SetProcessWindowStation, SwitchDesktop