Função CreateDesktopA (winuser.h)

Artigo
03/15/2023

Cria uma nova área de trabalho, 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 .

Para especificar o tamanho do heap para a área de trabalho, use a função CreateDesktopEx .

Sintaxe

HDESK CreateDesktopA(
  [in]           LPCSTR                lpszDesktop,
                 LPCSTR                lpszDevice,
                 DEVMODEA              *pDevmode,
  [in]           DWORD                 dwFlags,
  [in]           ACCESS_MASK           dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES lpsa
);

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

Reservados; deve ser NULL.

pDevmode

Reservados; 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 à á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.

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, que é de 48 MB. 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 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.

Observação

O cabeçalho winuser.h define CreateDesktop 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 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-windowstation-l1-1-0 (introduzido em Windows 8)