Uma API (Application Programming Interface) é uma interface para programar uma aplicação. No caso da Windows API, esta consiste num conjunto de funções expostas para serem usadas por aplicativos rodando em user mode.
Para o escopo deste livro, vamos cobrir uma minúscula parte da Win32 API (outro nome para a Windows API), com foco nas funções disponíveis basicamente em duas bibliotecas diferentes: a USER32.DLL e a KERNEL32.DLL.
Considere o seguinte programa em C:
#include <windows.h>int main(void) {MessageBox(NULL, "Cash", "Johnny", MB_OK);return 0;}
A função MessageBox() está definida em windows.h. Quando compilado, o código acima gera um executável dependente da USER32.DLL (além de outras bibliotecas), que provê a versão compilada de tal função. A documentação desta e de outras funções da Win32 está disponível no site da Microsoft. Copiamos seu protótipo abaixo para explicar seus parâmetros:
int WINAPI MessageBox(_In_opt_ HWND hWnd,_In_opt_ LPCTSTR lpText,_In_opt_ LPCTSTR lpCaption,_In_ UINT uType);
A Microsoft utiliza em várias de suas documentações de funções em C uma espécie de linguagem de anotação alheia à linguagem C padrão, que ela criou chamou de SAL (Source-code Annotation Language). Além disso, ela criou definições de novos tipos na linguagem que precisam ser explicadas para o entendimento dos protótipos das funções de sua API. Para entender o protótipo da função MessageBox, é preciso conhecer o significado dos seguintes termos:
| |
WINAPI | Define que a convenção de chamada da função é a __stdcall |
_In_ | Define que o parâmetro é de entrada |
_Out_ | Define que o parâmetro é de saída (a função vai escrever nele) |
_opt_ | O parâmetro é opcional (pode ser NULL, ou 0 normalmente) |
HANDLE | Um número identificador de um objeto no ambiente Windows |
HWND | Um handle (identificador) da janela |
LPCTSTR | Long Pointer to a Const TCHAR STRing |
UINT | unsigned int ou DWORD (32-bits) |
Um handle é um número que identifica um objeto (arquivo, chave de registro, diretório, etc) aberto usado por um processo. É um conceito similar ao file descriptor em ambiente Unix/Linux. Handles só são acessíveis diretamente em kernel mode, por isso os programas interagem com eles através de funções da API do Windows. Por exemplo, a função CreateFile() retorna um handle em caso de sucesso, enquanto a função CloseHandle() o fecha.
Agora vamos explicar os parâmetros da função MessageBox:
Um handle que identifica qual janela é dona da caixa de mensagem. Isso serve para atrelar uma mensagem a uma certa janela (e impedi-la de ser fechada antes da caixa de mensagem, por exemplo). Como é opcional, este parâmetro pode ser NULL, o que faz com que a caixa de mensagem não possua uma janela dona.
Um ponteiro para um texto (uma string) que será exibido na caixa de mensagem. Se for NULL, a mensagem não terá um conteúdo, mas ainda assim aparecerá.
Um ponteiro para o texto que será o título da caixa de mensagem. Se for NULL a caixa de mensagem não terá um título, mas ainda assim aparecerá.
Configura o tipo de caixa de mensagem. É um número inteiro que pode ser definido por macros para cada flag, definida na documentação da função. Se passada a macro MB_OKCANCEL (0x00000001L), por exemplo, faz com que a caixa de mensagem tenha dois botões: OK e Cancelar. Se passada a macro MB_ICONEXCLAMATION (0x00000030L), a janela terá um ícone de exclamação. Se quiséssemos combinar as duas características, precisaríamos passar as duas flags utilizando uma operação OU entre elas, assim:
MessageBox(NULL, "Cash", "Johnny", MB_OKCANCEL | MB_ICONEXCLAMATION);
Como macros e cálculos assim são resolvidos em C numa etapa conhecida por pré-compilação, o resultado da operação OU entre 1 e 0x30 será substituído neste código, antes de ser compilado, ficando assim:
MessageBox(0, "Cash", "Johnny", 0x31);
Dizer que um parâmetro é opcional não quer dizer que você não precise passá-lo ao chamar a função, mas sim que ele pode ser NULL, ou zero, dependendo do que a documentação da função diz.
Funções importantes da Win32 incluem CreateFile, DeleteFile, RegOpenKey, RegCreateKey, dentre outras. É altamente recomendado que o leitor crie programas de exemplo utilizando-as para atestar o funcionamento delas. Você encontrará algumas dessas funções separadas por categoria no apêndice Funções da API do Windows.