Função CreateDesktopExA (winuser.h)

Artigo
08/27/2023

Cria uma nova área de trabalho com o heap especificado, associa-a à estação de janela atual do processo de chamada e a atribui ao thread de chamada. O processo de chamada deve ter uma estação de janela associada, atribuída pelo sistema no momento da criação do processo ou definida pela função SetProcessWindowStation .

Sintaxe

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

Parâmetros

[in] lpszDesktop

O nome da área de trabalho a ser criada. Os nomes da área de trabalho não diferenciam maiúsculas de minúsculas e podem não conter caracteres de barra invertida (\).

lpszDevice

Esse parâmetro é reservado e deve ser NULL.

pDevmode

Esse parâmetro é reservado e deve ser NULL.

[in] dwFlags

Esse parâmetro pode ser zero ou o valor a seguir.

Valor	Significado
DF_ALLOWOTHERACCOUNTHOOK 0x0001	Habilita processos em execução em outras contas na área de trabalho para definir ganchos nesse processo.

[in] dwDesiredAccess

O acesso solicitado à área de trabalho. Para obter uma lista de valores, consulte Segurança da Área de Trabalho e Direitos de Acesso.

Esse parâmetro deve incluir o DESKTOP_CREATEWINDOW direito de acesso, pois o CreateDesktop usa internamente o identificador para criar uma janela.

[in, optional] lpsa

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que determina se o identificador retornado pode ser herdado por processos filho. Se lpsa for NULL, o identificador não poderá ser herdado.

O membro lpSecurityDescriptor da estrutura especifica um descritor de segurança para a nova área de trabalho. Se esse parâmetro for NULL, a área de trabalho herdará seu descritor de segurança da estação de janela pai.

[in] ulHeapSize

O tamanho do heap da área de trabalho, em quilobytes.

pvoid

Esse parâmetro é reservado e deve ser NULL.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para a área de trabalho recém-criada. Se a área de trabalho especificada já existir, a função terá êxito e retornará um identificador para a área de trabalho existente. Quando terminar de usar o identificador, chame a função CloseDesktop para fechá-la.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Se o parâmetro dwDesiredAccess especificar os direitos de acesso padrão READ_CONTROL, WRITE_DAC ou WRITE_OWNER, você também deverá solicitar os direitos de acesso DESKTOP_READOBJECTS e DESKTOP_WRITEOBJECTS.

O número de áreas de trabalho que podem ser criadas é limitado pelo tamanho do heap da área de trabalho do sistema. Os objetos da área de trabalho usam o heap para armazenar recursos. Você pode aumentar o número de áreas de trabalho que podem ser criadas aumentando o tamanho do heap da área de trabalho ou reduzindo o heap padrão reservado para cada área de trabalho na estação de janela interativa. Esse valor é especificado na subcadeia de caracteres SharedSection do seguinte valor do Registro: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SubSystems\Windows. Os dados padrão para esse valor do Registro são os seguintes:

%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

Os valores da subcadeia de caracteres SharedSection são descritos da seguinte maneira:

O primeiro valor SharedSection é o tamanho do heap compartilhado comum a todas as áreas de trabalho, em quilobytes.
O segundo valor SharedSection é o tamanho do heap da área de trabalho necessário para cada área de trabalho criada na estação de janela interativa, WinSta0, em quilobytes.
O terceiro valor SharedSection é o tamanho do heap da área de trabalho necessário para cada área de trabalho criada em uma estação de janela nãointerativa, em quilobytes.

O tamanho padrão do heap da área de trabalho depende de fatores como a arquitetura de hardware. Para recuperar o tamanho do heap da área de trabalho, chame a função GetUserObjectInformation com UOI_HEAPSIZE.

Observação

O cabeçalho winuser.h define CreateDesktopEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll