sto_subfield

Conceptos

Objetos Serializados

Comportamiento

C

• Parsea un STObject apuntado por read_ptr
• Encuentra el campo especificado por field_id
• Si el campo se encuentra, y:
• 1. Es un array, devuelve el inicio y la longitud del array incluyendo los bytes de cabecera y cierre, o
• 2. No es un array, devuelve el inicio y la longitud del PAYLOAD del campo (excluyendo los bytes de cabecera)

Codificación del Field ID

Las APIs sto_ aceptan un parámetro field_id codificado así: (type << 16U) + field Por ejemplo, tipo 1 campo 2 sería 0x10002U.

JavaScript

• Parsea un STObject en la variable sto
• Encuentra el campo especificado por field_id

Definición

C

int64_t sto_subfield (
    uint32_t read_ptr,
    uint32_t read_len,
    uint32_t field_id
);

JavaScript

function sto_subfield(
    sto: ByteArray | HexString,
    field_id: number
  ): ErrorCode | bigint

Ejemplo

C

#define SUB_OFFSET(x) ((int32_t)(x >> 32))
#define SUB_LENGTH(x) ((int32_t)(x & 0xFFFFFFFFULL))
int64_t memos_lookup =
    sto_subfield(txn_ptr, txn_len, sfMemos);
if (memos_lookup < 0)
{
    // sfMemos no fue encontrado en el STObject apuntado por memo_ptr
}
else
{
    // sfMemos fue encontrado y su ubicación es la siguiente:
    uint8_t* memos_ptr = SUB_OFFSET(memos_lookup) + memos_ptr;
    int64_t  memos_len = SUB_LENGTH(memos_lookup);
}

Consejo

hookmacro.h ya contiene las macros SUB_OFFSET y SUB_LENGTH.

JavaScript

const SUB_OFFSET = (x) => Number(x >> 32n)
const SUB_LENGTH = (x) => Number(x & 0xFFFFFFFFn)
const memos_lookup = sto_subfield(txn, sfMemos);
if (typeof memos_lookup === 'number')
{
    // sfMemos no fue encontrado en el STObject
}
else
{
    // sfMemos fue encontrado y su ubicación es la siguiente:
    const memo_start = SUB_OFFSET(memos_lookup)
    const memo_len = SUB_LENGTH(memos_lookup)
    const memo = txn.slice(memo_start, memo_len)
}

Parámetros

C

Nombre	Tipo	Descripción
read_ptr	uint32_t	Puntero al buffer que contiene el STObject
read_len	uint32_t	Longitud del STObject
field_id	uint32_t	Código sf del campo que se desea buscar. Para calcularlo manualmente, toma el type serializado y desplázalo a los 16 bits más altos de un uint32_t, luego toma el field y colócalo en los 16 bits más bajos. Ejemplo: sfEmitNonce tiene type 5 y field 11, por lo que su valor es 0x050BU

JavaScript

Nombre	Tipo	Descripción
sto	ByteArray or HexString	Objeto STO (datos del ledger codificados en binario) del que extraer el subcampo
field_id	number	Identificador del campo a extraer

Código de retorno

C

Tipo	Descripción
int64_t	Ubicación del campo dentro del buffer especificado: - Los 32 bits altos son el desplazamiento (offset) - Los 32 bits bajos son la longitud Si es negativo, error: OUT_OF_BOUNDS - punteros fuera de la memoria del hook TOO_SMALL - el buffer es demasiado pequeño para contener un STObject válido DOESNT_EXIST - el campo no existe en el STObject PARSE_ERROR - el STObject es inválido o mal formado

JavaScript

Tipo	Descripción
bigint / ErrorCode	Ubicación del campo dentro del buffer: - 32 bits altos = offset - 32 bits bajos = longitud o un código de error si la extracción falla