Estrutura STARTUPINFOA (processthreadsapi.h)
Especifica a estação de janela, a área de trabalho, os identificadores padrão e a aparência da janela main para um processo no momento da criação.
Sintaxe
typedef struct _STARTUPINFOA {
DWORD cb;
LPSTR lpReserved;
LPSTR lpDesktop;
LPSTR lpTitle;
DWORD dwX;
DWORD dwY;
DWORD dwXSize;
DWORD dwYSize;
DWORD dwXCountChars;
DWORD dwYCountChars;
DWORD dwFillAttribute;
DWORD dwFlags;
WORD wShowWindow;
WORD cbReserved2;
LPBYTE lpReserved2;
HANDLE hStdInput;
HANDLE hStdOutput;
HANDLE hStdError;
} STARTUPINFOA, *LPSTARTUPINFOA;
Membros
cb
O tamanho da estrutura em bytes.
lpReserved
Reservados; deve ser NULL.
lpDesktop
O nome da área de trabalho ou o nome da área de trabalho e da estação de janela para esse processo. Uma barra invertida na cadeia de caracteres indica que a cadeia de caracteres inclui os nomes da estação da área de trabalho e da janela.
Para obter mais informações, consulte Conexão de thread com uma área de trabalho.
lpTitle
Para processos de console, esse é o título exibido na barra de título se uma nova janela de console for criada. Se NULL, o nome do arquivo executável será usado como o título da janela. Esse parâmetro deve ser NULL para processos de GUI ou console que não criam uma nova janela de console.
dwX
Se dwFlags especificar STARTF_USEPOSITION, esse membro será o deslocamento x do canto superior esquerdo de uma janela se uma nova janela for criada, em pixels. Caso contrário, esse membro será ignorado.
O deslocamento é do canto superior esquerdo da tela. Para processos de GUI, a posição especificada é usada na primeira vez que o novo processo chama CreateWindow para criar uma janela sobreposta se o parâmetro x de CreateWindow for CW_USEDEFAULT.
dwY
Se dwFlags especificar STARTF_USEPOSITION, esse membro será o deslocamento y do canto superior esquerdo de uma janela se uma nova janela for criada, em pixels. Caso contrário, esse membro será ignorado.
O deslocamento é do canto superior esquerdo da tela. Para processos de GUI, a posição especificada é usada na primeira vez que o novo processo chama CreateWindow para criar uma janela sobreposta se o parâmetro y de CreateWindow for CW_USEDEFAULT.
dwXSize
Se dwFlags especificar STARTF_USESIZE, esse membro será a largura da janela se uma nova janela for criada, em pixels. Caso contrário, esse membro será ignorado.
Para processos de GUI, isso é usado apenas na primeira vez que o novo processo chama CreateWindow para criar uma janela sobreposta se o parâmetro nWidth de CreateWindow for CW_USEDEFAULT.
dwYSize
Se dwFlags especificar STARTF_USESIZE, esse membro será a altura da janela se uma nova janela for criada, em pixels. Caso contrário, esse membro será ignorado.
Para processos de GUI, isso é usado apenas na primeira vez que o novo processo chama CreateWindow para criar uma janela sobreposta se o parâmetro nHeight de CreateWindow for CW_USEDEFAULT.
dwXCountChars
Se dwFlags especificar STARTF_USECOUNTCHARS, se uma nova janela de console for criada em um processo de console, esse membro especificará a largura do buffer de tela, em colunas de caracteres. Caso contrário, esse membro será ignorado.
dwYCountChars
Se dwFlags especificar STARTF_USECOUNTCHARS, se uma nova janela de console for criada em um processo de console, esse membro especificará a altura do buffer de tela, em linhas de caracteres. Caso contrário, esse membro será ignorado.
dwFillAttribute
Se dwFlags especificar STARTF_USEFILLATTRIBUTE, esse membro será o texto inicial e as cores da tela de fundo se uma nova janela de console for criada em um aplicativo de console. Caso contrário, esse membro será ignorado.
Esse valor pode ser qualquer combinação dos seguintes valores: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED e BACKGROUND_INTENSITY. Por exemplo, a seguinte combinação de valores produz texto vermelho em uma tela de fundo branca:
FOREGROUND_RED| BACKGROUND_RED| BACKGROUND_GREEN| BACKGROUND_BLUE
dwFlags
Um campo de bits que determina se determinados membros STARTUPINFO são usados quando o processo cria uma janela. Esse membro pode ser um ou mais dos valores a seguir.
| Valor | Significado |
|---|---|
|
Indica que o cursor está no modo de comentários por dois segundos depois que CreateProcess é chamado. O cursor Trabalhando em Segundo Plano é exibido (consulte a guia Ponteiros no utilitário do painel de controle do mouse).
Se durante esses dois segundos o processo fizer a primeira chamada de GUI, o sistema dará mais cinco segundos ao processo. Se durante esses cinco segundos o processo mostrar uma janela, o sistema dará mais cinco segundos ao processo para concluir o desenho da janela. O sistema desativa o cursor de comentários após a primeira chamada para GetMessage, independentemente de o processo ser desenhado. |
|
Indica que o cursor de comentários é forçado a sair enquanto o processo está sendo iniciado. O cursor Seleção Normal é exibido. |
|
Indica que as janelas criadas pelo processo não podem ser fixadas na barra de tarefas.
Esse sinalizador deve ser combinado com STARTF_TITLEISAPPID. |
|
Indica que o processo deve ser executado no modo de tela inteira, em vez de no modo em janelas.
Esse sinalizador só é válido para aplicativos de console em execução em um computador x86. |
|
O membro lpTitle contém um AppUserModelID. Esse identificador controla como a barra de tarefas e o menu Iniciar apresentam o aplicativo e permite que ele seja associado aos atalhos corretos e ao Jump Listas. Geralmente, os aplicativos usarão as funções SetCurrentProcessExplicitAppUserModelID e GetCurrentProcessExplicitAppUserModelID em vez de definir esse sinalizador. Para obter mais informações, consulte IDs do modelo de usuário do aplicativo.
Se STARTF_PREVENTPINNING for usado, as janelas do aplicativo não poderão ser fixadas na barra de tarefas. O uso de qualquer propriedade de janela relacionada a AppUserModelID pelo aplicativo substitui essa configuração somente para essa janela. Esse sinalizador não pode ser usado com STARTF_TITLEISLINKNAME. |
|
O membro lpTitle contém o caminho do arquivo de atalho (.lnk) que o usuário invocou para iniciar esse processo. Normalmente, isso é definido pelo shell quando um arquivo .lnk que aponta para o aplicativo iniciado é invocado. A maioria dos aplicativos não precisará definir esse valor.
Esse sinalizador não pode ser usado com STARTF_TITLEISAPPID. |
|
A linha de comando veio de uma fonte não confiável. Para obter mais informações, consulte Comentários. |
|
Os membros dwXCountChars e dwYCountChars contêm informações adicionais. |
|
O membro dwFillAttribute contém informações adicionais. |
|
O membro hStdInput contém informações adicionais.
Esse sinalizador não pode ser usado com STARTF_USESTDHANDLES. |
|
Os membros dwX e dwY contêm informações adicionais. |
|
O membro wShowWindow contém informações adicionais. |
|
Os membros dwXSize e dwYSize contêm informações adicionais. |
|
Os membros hStdInput, hStdOutput e hStdError contêm informações adicionais.
Se esse sinalizador for especificado ao chamar uma das funções de criação do processo, os identificadores deverão ser herdáveis e o parâmetro bInheritHandles da função deverá ser definido como TRUE. Para obter mais informações, consulte Manipular herança. Se esse sinalizador for especificado ao chamar a função GetStartupInfo , esses membros serão o valor do identificador especificado durante a criação do processo ou INVALID_HANDLE_VALUE. Os identificadores devem ser fechados com CloseHandle quando não forem mais necessários. Esse sinalizador não pode ser usado com STARTF_USEHOTKEY. |
wShowWindow
Se dwFlags especificar STARTF_USESHOWWINDOW, esse membro poderá ser qualquer um dos valores que podem ser especificados no parâmetro nCmdShow para a função ShowWindow , exceto para SW_SHOWDEFAULT. Caso contrário, esse membro será ignorado.
Para processos de GUI, na primeira vez que ShowWindow é chamado, seu parâmetro nCmdShow é ignorado wShowWindow especifica o valor padrão. Em chamadas subsequentes para ShowWindow, o membro wShowWindow será usado se o parâmetro nCmdShow de ShowWindow estiver definido como SW_SHOWDEFAULT.
cbReserved2
Reservado para uso pelo tempo de execução C; deve ser zero.
lpReserved2
Reservado para uso pelo tempo de execução C; deve ser NULL.
hStdInput
Se dwFlags especificar STARTF_USESTDHANDLES, esse membro será o identificador de entrada padrão para o processo. Se STARTF_USESTDHANDLES não for especificado, o padrão para entrada padrão será o buffer de teclado.
Se dwFlags especificar STARTF_USEHOTKEY, esse membro especificará um valor de tecla de acesso que é enviado como o parâmetro wParam de uma mensagem de WM_SETHOTKEY para a primeira janela de nível superior qualificada criada pelo aplicativo que possui o processo. Se a janela for criada com o estilo de janela WS_POPUP, ela não será qualificada, a menos que o WS_EX_APPWINDOW estilo de janela estendida também esteja definido. Para obter mais informações, consulte CreateWindowEx.
Caso contrário, esse membro será ignorado.
hStdOutput
Se dwFlags especificar STARTF_USESTDHANDLES, esse membro será o identificador de saída padrão para o processo. Caso contrário, esse membro será ignorado e o padrão para a saída padrão será o buffer da janela do console.
Se um processo for iniciado na barra de tarefas ou na lista de atalhos, o sistema definirá hStdOutput como um identificador para o monitor que contém a barra de tarefas ou a lista de atalhos usada para iniciar o processo. Para obter mais informações, consulte Comentários. Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP e Windows Server 2003: Esse comportamento foi introduzido em Windows 8 e Windows Server 2012.
hStdError
Se dwFlags especificar STARTF_USESTDHANDLES, esse membro será o identificador de erro padrão para o processo. Caso contrário, esse membro será ignorado e o padrão para erro padrão será o buffer da janela do console.
Comentários
Para processos de GUI (interface gráfica do usuário), essas informações afetam a primeira janela criada pela função CreateWindow e mostrada pela função ShowWindow . Para processos de console, essas informações afetarão a janela do console se um novo console for criado para o processo. Um processo pode usar a função GetStartupInfo para recuperar a estrutura STARTUPINFO especificada quando o processo foi criado.
Se um processo de GUI estiver sendo iniciado e nenhum STARTF_FORCEONFEEDBACK ou STARTF_FORCEOFFFEEDBACK for especificado, o cursor de comentários do processo será usado. Um processo de GUI é aquele cujo subsistema é especificado como "windows".
Se um processo for iniciado na barra de tarefas ou na lista de atalhos, o sistema definirá GetStartupInfo para recuperar a estrutura STARTUPINFO e marcar que hStdOutput esteja definido. Nesse caso, use GetMonitorInfo para marcar se hStdOutput é um HMONITOR (identificador de monitor válido). Em seguida, o processo pode usar o identificador para posicionar suas janelas.
Se o sinalizador STARTF_UNTRUSTEDSOURCE for especificado, o aplicativo deverá estar ciente de que a linha de comando não é confiável. Se esse sinalizador estiver definido, os aplicativos deverão desabilitar recursos potencialmente perigosos, como macros, conteúdo baixado e impressão automática. Esse sinalizador é opcional, mas os aplicativos que chamam CreateProcess são incentivados a definir esse sinalizador ao iniciar um programa com argumentos de linha de comando não confiáveis (como os fornecidos pelo conteúdo da Web) para que o processo recém-criado possa aplicar a política apropriada.
O sinalizador STARTF_UNTRUSTEDSOURCE tem suporte a partir do Windows Vista, mas não é definido nos arquivos de cabeçalho do SDK antes do SDK do Windows 10. Para usar o sinalizador em versões anteriores a Windows 10, você pode defini-lo manualmente em seu programa.
Exemplos
O exemplo de código a seguir mostra o uso de StartUpInfoA.
#include <windows.h>
#include <stdio.h>
#include <tchar.h>
void _tmain( int argc, TCHAR *argv[] )
{
STARTUPINFO si;
PROCESS_INFORMATION pi;
ZeroMemory( &si, sizeof(si) );
si.cb = sizeof(si);
ZeroMemory( &pi, sizeof(pi) );
if( argc != 2 )
{
printf("Usage: %s [cmdline]\n", argv[0]);
return;
}
// Start the child process.
if( !CreateProcess( NULL, // No module name (use command line)
argv[1], // Command line
NULL, // Process handle not inheritable
NULL, // Thread handle not inheritable
FALSE, // Set handle inheritance to FALSE
0, // No creation flags
NULL, // Use parent's environment block
NULL, // Use parent's starting directory
&si, // Pointer to STARTUPINFO structure
&pi ) // Pointer to PROCESS_INFORMATION structure
)
{
printf( "CreateProcess failed (%d).\n", GetLastError() );
return;
}
// Wait until child process exits.
WaitForSingleObject( pi.hProcess, INFINITE );
// Close process and thread handles.
CloseHandle( pi.hProcess );
CloseHandle( pi.hThread );
}
Para obter mais informações sobre este exemplo, consulte Criando processos.
Observação
O cabeçalho processthreadsapi.h define STARTUPINFO 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 XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Cabeçalho | processthreadsapi.h (inclua Windows.h no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |