# Windows API

Uma API (*Application Programming Interface*) é uma interface para uma aplicação "falar" com outra. A Windows API consiste num conjunto de funções expostas para serem usadas por aplicativos rodando em *user mode*.

Para o escopo deste livro, vamos cobrir uma pequena parte da Windows API, pois o assunto é extenso.

Considere o seguinte programa em C:

```c
#include <windows.h>

int main(void) {
    MessageBox(NULL, "Mundo", "Olá", MB_OK);
}
```

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, dependendo de certas opções de compilação), que provê a versão compilada de tal função. A documentação desta e de outras funções da Windows API está disponível no site da Microsoft. Copiamos seu protótipo abaixo para explicar seus parâmetros:

```c
int MessageBox(
  [in, optional] HWND    hWnd,
  [in, optional] LPCTSTR lpText,
  [in, optional] LPCTSTR lpCaption,
  [in]           UINT    uType
);
```

A Microsoft criou definições de anotações e novos tipos na linguagem C 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:

|                 |                                                          |
| --------------- | -------------------------------------------------------- |
| \\\[in\\]       | Define que o parâmetro é de entrada                      |
| \\\[optional\\] | O parâmetro é opcional (pode ser NULL, ou 0 normalmente) |
| HWND            | Um *handle* (identificador) da janela                    |
| LPCTSTR         | **L**ong **P**ointer to a **C**onst **T**CHAR **STR**ing |
| UINT            | *unsigned int* ou DWORD (32-bits ou 4 *bytes*)           |

> 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* válido em caso de execução com sucesso. A partir daí, toda leitura e escrita neste arquivo deve ser feita a partir do *handle*. Por fim, a função CloseHandle() o fecha o *handle* quando ele não é mais necessário.

Agora vamos explicar os parâmetros da função *MessageBox*:

## MessageBox

### hWnd

É um parâmetro de entrada, ou seja, é uma informação que a função precisa (e não quem chamou). Neste caso, é 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.

### lpText

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á.

### lpCaption

Um ponteiro para o texto que será o título da caixa de mensagem. Se for NULL, a caixa de mensagem terá o título padrão "Error" (pode rir).

### uType

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:

```c
MessageBox(NULL, "Mundo", "Olá", MB_OKCANCEL | MB_ICONEXCLAMATION);
```

Como macros e cálculos assim são resolvidos 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:

```c
MessageBox(NULL, "Mundo", "Olá"), 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 `0`, dependendo do que a documentação da função diz. Como o Visual Studio é um compilador de C++, você também pode usar `nullptr`, que também está disponível em C a partir da C23.

Veremos agora algumas funções da Windows API para funções básicas, mas você encontrará informações sobre outras rotinas no apêndice Funções da API do Windows.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mentebinaria.gitbook.io/engenharia-reversa/07-windows-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.