Convenciones de la API de Hooks

Convenciones de nomenclatura

Todas las APIs de Hooks siguen una convención de nombres estándar:

namespace	[ _ sustantivo #1 ]	[ _ verbo ]	[ _ sustantivo #2 ]

Esto puede parecer confuso al principio, pero en realidad es bastante simple:

• Si falta el primer sustantivo, entonces implícitamente es el mismo que el namespace
• Si falta el verbo, entonces implícitamente es get

Por lo tanto:

• state() significa: obtener el estado de un hook.
• state_set() significa: establecer el estado de un hook.
• state_foreign() significa: obtener el estado de un hook externo.

Modelo de memoria

Cada Hook se ejecuta como un único frame de pila (stack frame). Toda la memoria de trabajo debe existir dentro de este frame. No hay heap ni memoria dinámica.

Cuando los Hooks se comunican con xahaud, solo pueden pasar valores enteros. Normalmente estos enteros son punteros dentro de la memoria del Hook. Dado que el Hook se ejecuta dentro de xahaud, estos punteros pueden ser resueltos por xahaud y utilizados para escribir o leer datos según sea necesario para ejecutar la función de la API.

Funciones permitidas

Solo se permiten dos funciones dentro de un Hook: hook() y cbak(). Puedes leer más sobre esto aquí

Parámetros

C

Todos los parámetros pasados a una API de Hook deben ser uno de los siguientes tipos: uint32_t, int32_t, uint64_t, int64_t. Normalmente son punteros y longitudes de buffers dentro del stack frame del Hook. En algunos casos pueden ser números en coma flotante codificados como enteros (XFL) u otros datos.

Los parámetros de una API de Hook siempre siguen este orden:

1. Puntero de escritura si existe
2. Longitud de escritura si existe
3. Puntero de lectura si existe
4. Longitud de lectura si existe
5. Campos específicos / adicionales si existen

Algunas APIs solo escriben, otras solo leen, y algunas no hacen ninguna de las dos y devuelven únicamente un valor mediante el código de retorno.

JavaScript

Todos los parámetros pasados a una API de Hook deben ser uno de los siguientes tipos: string, number[], bigint(xfl), object(json). Normalmente representan buffers o datos dentro del contexto del Hook. En algunos casos pueden ser números en coma flotante codificados como enteros (XFL) u otros datos.

Los parámetros de una API de Hook siempre siguen este orden:

1. Variable de escritura si existe
2. Variable de lectura si existe
3. Campos específicos / adicionales si existen

Algunas APIs solo escriben, otras solo leen, y algunas no hacen ninguna de las dos y devuelven únicamente un valor mediante el código de retorno.

Códigos de retorno

Todas las APIs de Hooks devuelven un entero con signo. Puedes leer más sobre los códigos de retorno aquí: Códigos de retorno