Função WinMain (winbase.h)

Artigo
08/27/2023

O ponto de entrada fornecido pelo usuário para um aplicativo gráfico baseado no Windows.

WinMain é o nome convencional usado para o ponto de entrada do aplicativo. Para obter mais informações, consulte Comentários.

Sintaxe

int __clrcall WinMain(
  [in]           HINSTANCE hInstance,
  [in, optional] HINSTANCE hPrevInstance,
  [in]           LPSTR     lpCmdLine,
  [in]           int       nShowCmd
);

Parâmetros

[in] hInstance

Tipo: HINSTANCE

Um identificador para a instância atual do aplicativo.

[in, optional] hPrevInstance

Tipo: HINSTANCE

Um identificador para a instância anterior do aplicativo. Esse parâmetro é sempre NULL. Se você precisar detectar se outra instância já existe, crie um mutex nomeado exclusivamente usando a função CreateMutex . CreateMutex terá êxito mesmo que o mutex já exista, mas a função retornará ERROR_ALREADY_EXISTS. Isso indica que existe outra instância do seu aplicativo, porque ele criou o mutex primeiro. No entanto, um usuário mal-intencionado pode criar esse mutex antes de você e impedir que seu aplicativo seja iniciado. Para evitar essa situação, crie um mutex nomeado aleatoriamente e armazene o nome para que ele só possa ser obtido por um usuário autorizado. Como alternativa, você pode usar um arquivo para essa finalidade. Para limitar seu aplicativo a uma instância por usuário, crie um arquivo bloqueado no diretório de perfil do usuário.

[in] lpCmdLine

Tipo: LPSTR

A linha de comando do aplicativo, excluindo o nome do programa. Para recuperar toda a linha de comando, use a função GetCommandLine .

[in] nShowCmd

Tipo: int

Controla como a janela deve ser mostrada. Esse parâmetro pode ser qualquer um dos valores que podem ser especificados no parâmetro nCmdShow para a função ShowWindow .

Retornar valor

Tipo: int

Se a função for bem-sucedida, encerrando quando receber uma mensagem WM_QUIT , ela deverá retornar o valor de saída contido no parâmetro wParam dessa mensagem. Se a função terminar antes de inserir o loop de mensagem, ela deverá retornar zero.

Comentários

O nome WinMain é usado por convenção por muitas estruturas de programação. Dependendo da estrutura de programação, a chamada para a função WinMain pode ser precedida e seguida por atividades adicionais específicas a essa estrutura.

O WinMain deve inicializar o aplicativo, exibir sua janela main e inserir um loop de recuperação e expedição de mensagens que seja a estrutura de controle de nível superior para o restante da execução do aplicativo. Encerre o loop de mensagem quando receber uma mensagem WM_QUIT . Nesse ponto, o WinMain deve sair do aplicativo, retornando o valor passado no parâmetro wParam da mensagem WM_QUIT. Se WM_QUIT foi recebido como resultado da chamada de PostQuitMessage, o valor de wParam será o valor do parâmetro nExitCode da função PostQuitMessage. Para obter mais informações, consulte Criando um loop de mensagem.

Os aplicativos ANSI podem usar o parâmetro lpCmdLine da função WinMain para acessar a cadeia de caracteres de linha de comando, excluindo o nome do programa. Observe que lpCmdLine usa o tipo de dados LPSTR em vez do tipo de dados LPTSTR . Isso significa que o WinMain não pode ser usado por programas Unicode. A função GetCommandLineW pode ser usada para obter a linha de comando como uma cadeia de caracteres Unicode. Algumas estruturas de programação podem fornecer um ponto de entrada alternativo que fornece uma linha de comando Unicode. Por exemplo, o complier do Microsoft Visual Studio C++ usa o nome wWinMain para o ponto de entrada Unicode.

Exemplo

O exemplo de código a seguir demonstra o uso do WinMain

#include <windows.h>

int APIENTRY WinMain(HINSTANCE hInst, HINSTANCE hInstPrev, PSTR cmdline, int cmdshow)
{
    return MessageBox(NULL, "hello, world", "caption", 0);
}

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	winbase.h (incluir Windows.h)