Функция CreateDesktopExA (winuser.h)

Статья
08/27/2023

Создает рабочий стол с указанной кучей, связывает его с текущей станцией окон вызывающего процесса и назначает его вызывающему потоку. Вызывающий процесс должен иметь связанную оконную станцию, назначенную системой во время создания процесса или заданную функцией SetProcessWindowStation .

Синтаксис

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

Параметры

[in] lpszDesktop

Имя создаваемого рабочего стола. Имена рабочих столов не учитывают регистр и не могут содержать символы обратной косой черты (\).

lpszDevice

Этот параметр зарезервирован и должен иметь значение NULL.

pDevmode

Этот параметр зарезервирован и должен иметь значение NULL.

[in] dwFlags

Этот параметр может быть равен нулю или следующему значению.

Значение	Значение
DF_ALLOWOTHERACCOUNTHOOK 0x0001	Позволяет процессам, запущенным в других учетных записях на рабочем столе, устанавливать перехватчики в этом процессе.

[in] dwDesiredAccess

Запрошенный доступ к рабочему столу. Список значений см. в разделе Безопасность и права доступа к рабочему столу.

Этот параметр должен включать право доступа DESKTOP_CREATEWINDOW, так как для создания окна внутри CreateDesktop использует дескриптор.

[in, optional] lpsa

Указатель на структуру SECURITY_ATTRIBUTES , которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Если lpsa имеет значение NULL, дескриптор не может быть унаследован.

Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового рабочего стола. Если этот параметр имеет значение NULL, рабочий стол наследует дескриптор безопасности от родительской станции окна.

[in] ulHeapSize

Размер кучи рабочего стола в килобайтах.

pvoid

Этот параметр зарезервирован и должен иметь значение NULL.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет дескриптором для только что созданного рабочего стола. Если указанный рабочий стол уже существует, функция выполняется успешно и возвращает дескриптор существующему рабочему столу. Завершив использование дескриптора, вызовите функцию CloseDesktop , чтобы закрыть ее.

Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Количество рабочих столов, которые можно создать, ограничено размером системной кучи рабочего стола. Объекты рабочего стола используют кучу для хранения ресурсов. Вы можете увеличить количество рабочих столов, которые можно создать, увеличив размер кучи рабочего стола или уменьшив кучи по умолчанию, зарезервированную для каждого рабочего стола в интерактивной станции окон. Это значение указывается в подстроке SharedSection следующего значения реестра: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SubSystems\Windows. Данные по умолчанию для этого значения реестра:

%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

Значения для подстроки SharedSection описаны следующим образом:

Первое значение SharedSection — это размер общей кучи, общей для всех рабочих столов, в килобайтах.
Второе значение SharedSection — это размер кучи рабочего стола, необходимого для каждого рабочего стола, созданного в интерактивной оконной станции WinSta0, в килобайтах.
Третье значение SharedSection — это размер кучи рабочего стола, необходимой для каждого рабочего стола, созданного в неинтерактивной оконной станции, в килобайтах.

Размер кучи по умолчанию зависит от таких факторов, как архитектура оборудования. Чтобы получить размер кучи рабочего стола, вызовите функцию GetUserObjectInformation с UOI_HEAPSIZE.

Примечание

Заголовок winuser.h определяет CreateDesktopEx в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll