Convenções da API de Hooks

Convenções de nomenclatura

Todas as APIs de Hooks seguem uma convenção de nomenclatura padrão:

namespace	[ _ substantivo nº1 ]	[ _ verbo ]	[ _ substantivo nº2 ]

Isso pode parecer confuso a princípio, mas na verdade é bem simples:

• Se o primeiro substantivo estiver ausente, ele é implicitamente o mesmo que o namespace
• Se o verbo estiver ausente, ele é implicitamente get

Assim:

• state() significa: buscar um estado do hook.
• state_set() significa: definir um estado do hook.
• state_foreign() significa: buscar um estado de hook externo.

Modelo de memória

Cada Hook é executado como um único stack frame. Toda a memória de trabalho deve existir dentro deste stack frame. Não há heap nem memória dinâmica.

Quando os Hooks se comunicam com o xahaud, eles só podem passar valores inteiros. Tipicamente, esses inteiros são ponteiros dentro da memória do Hook. Como o Hook é executado dentro do xahaud, esses ponteiros podem então ser resolvidos pelo xahaud e ter seu conteúdo lido ou escrito conforme necessário para realizar a função da API de Hooks.

Funções permitidas

Apenas duas funções são permitidas dentro de um Hook: hook() e cbak(). Leia sobre isso aqui

Parâmetros

C

Todos os parâmetros passados para uma API de Hooks devem ser de um dos tipos: uint32_t, int32_t, uint64_t, int64_t. Tipicamente, são ponteiros e tamanhos de buffers dentro do stack frame do Hook. Às vezes são Números de Ponto Flutuante Codificados como Inteiros (XFL) ou outros dados.

Os parâmetros de uma API de Hooks seguem sempre a seguinte ordem:

1. Ponteiro de escrita se houver
2. Tamanho de escrita se houver
3. Ponteiro de leitura se houver
4. Tamanho de leitura se houver
5. Específicos / outros campos se houver

Algumas APIs de Hooks podem apenas escrever ou apenas ler da memória, e algumas podem não fazer nenhum dos dois, retornando um valor apenas pelo código de retorno.

JavaScript

Todos os parâmetros passados para uma API de Hooks devem ser de um dos tipos: string, number[], bigint(xfl), object(json). Tipicamente, são ponteiros e tamanhos de buffers dentro do stack frame do Hook. Às vezes são Números de Ponto Flutuante Codificados como Inteiros (XFL) ou outros dados.

Os parâmetros de uma API de Hooks seguem sempre a seguinte ordem:

1. Variável de escrita se houver
2. Variável de leitura se houver
3. Específicos / outros campos se houver

Algumas APIs de Hooks podem apenas escrever ou apenas ler da memória, e algumas podem não fazer nenhum dos dois, retornando um valor apenas pelo código de retorno.

Códigos de retorno

Todas as APIs de Hooks retornam um inteiro com sinal. Leia sobre os códigos de retorno aqui: Códigos de Retorno