# Function Reference

# _WinAPI_CreateDesktop

Creates a new desktop, associates it with the current window station of the calling process

#include <WinAPISys.au3>
_WinAPI_CreateDesktop ( $sName [, $iAccess = $DESKTOP_CREATEWINDOW [, $iFlags = 0 [, $iHeap = 0 [, $tSecurity = 0]]]] )

## Parameters

$sName | The name of the desktop to be created. Desktop names are case-insensitive and may not contain backslash characters (\).
$iAccess | [optional] The requested access to the desktop. This parameter can be one or more of the following values: $DESKTOP_ALL_ACCESS $DESKTOP_CREATEMENU $DESKTOP_CREATEWINDOW (Default) $DESKTOP_ENUMERATE $DESKTOP_HOOKCONTROL $DESKTOP_JOURNALPLAYBACK $DESKTOP_JOURNALRECORD $DESKTOP_READOBJECTS $DESKTOP_SWITCHDESKTOP $DESKTOP_WRITEOBJECTS
$iFlags | [optional] The optional flags. It can be zero or the following value: $DF_ALLOWOTHERACCOUNTHOOK
$iHeap | [optional] The size of the desktop heap, in kilobytes. Default is 0.
$tSecurity | [optional] $tagSECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If this parameter is 0 (Default), the handle cannot be inherited .

## Return Value

Success: | Handle to the newly created desktop. If the specified desktop already exists, the function succeeds and returns a handle to the existing desktop.
Failure: | 0, call _WinAPI_GetLastError() to get extended error information.

## Remarks

The number of desktops that can be created is limited by the size of the system desktop heap.
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.
The default size of the desktop heap depends on factors such as hardware architecture.
To retrieve the size of the heap, call the _WinAPI_GetUserObjectInformation() function with $UOI_HEAPSIZE.
When you are finished using the desktop, call the _WinAPI_CloseDesktop() function to close it.

## Related

_WinAPI_CloseDesktop, _WinAPI_GetUserObjectInformation

## See Also

Search CreateDesktopEx in MSDN Library.

## Example

    #include <MsgBoxConstants.au3>
    #include <StructureConstants.au3>
    #include <WinAPIMem.au3>
    #include <WinAPIProc.au3>
    #include <WinAPISys.au3>

    ; Retrieve a handle to the current desktop and create a new desktop named "MyDesktop"
    Local $hPrev = _WinAPI_GetThreadDesktop(_WinAPI_GetCurrentThreadId())
    Local $hDesktop = _WinAPI_CreateDesktop('MyDesktop', BitOR($DESKTOP_CREATEWINDOW, $DESKTOP_SWITCHDESKTOP))
    If Not $hDesktop Then
        MsgBox(($MB_ICONERROR + $MB_SYSTEMMODAL), 'Error', 'Unable to create desktop.')
        Exit
    EndIf

    ; Switch to the newly created desktop
    _WinAPI_SwitchDesktop($hDesktop)

    ; Run "notepad.exe" on "MyDesktop" and wait until a process will not be closed by user
    Local $pText = _WinAPI_CreateString('MyDesktop')
    Local $tProcess = DllStructCreate($tagPROCESS_INFORMATION)
    Local $tStartup = DllStructCreate($tagSTARTUPINFO)
    DllStructSetData($tStartup, 'Size', DllStructGetSize($tStartup))
    DllStructSetData($tStartup, 'Desktop', $pText)
    If _WinAPI_CreateProcess('', @SystemDir & '\notepad.exe', 0, 0, 0, $CREATE_NEW_PROCESS_GROUP, 0, 0, $tStartup, $tProcess) Then
        ProcessWaitClose(DllStructGetData($tProcess, 'ProcessID'))
    EndIf

    ; Switch to previous desktop and close "MyDesktop"
    _WinAPI_SwitchDesktop($hPrev)
    _WinAPI_CloseDesktop($hDesktop)

    ; Free memory allocated for a string
    _WinAPI_FreeMemory($pText)