sto_emplace

Conceitos

Objetos Serializados

Comportamento

C

• Analisa um STObject S (objeto de origem) apontado por sread_ptr
• Analisa um STObject F (a ser injetado/inserido) apontado por fread_ptr
• Escreve um novo STObject em write_ptr que coloca F dentro de S na posição canônica field_id

Codificação do Field ID

As APIs sto_ aceitam um parâmetro field_id codificado da seguinte forma: (type << 16U) + field
Assim, o tipo 1 campo 2 seria 0x10002U.

JavaScript

• Solicita o objeto STO pelo parâmetro sto
• Solicita os bytes que representam o campo a ser adicionado pelo parâmetro field_bytes
• Solicita o ID do campo a ser adicionado pelo parâmetro field_id
• Retorna o objeto STO atualizado em formato de dados de ledger codificados em binário, ou um código de erro se a operação falhar.

Definição

C

C

int64_t sto_emplace (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t sread_ptr,
    uint32_t sread_len,
    uint32_t fread_ptr,
    uint32_t fread_len,
    uint32_t field_id
);

JavaScript

function sto_emplace(
    sto: ByteArray | HexString,
    field_bytes: ByteArray | HexString,
    field_id: number
  ): ErrorCode | ByteArray

Exemplo

C

uint8_t tx_out[1024];

int64_t tx_len =
    sto_emplace(tx_out, sizeof(tx_out),
                tx_in, tx_len,
                sequence_field, 5, sfSequence);

if (tx_len <= 0)
    rollback("Emplacing failed.", 17, 1);

JavaScript

const tx_out = sto_emplace(tx_in, sequence_field, sfSequence)
if (typeof tx_out === 'number')
    rollback("Emplacing failed.", 1)

Parâmetros

C

Nome	Tipo	Descrição
write_ptr	uint32_t	O buffer onde o STObject modificado será escrito
write_len	uint32_t	O tamanho do buffer de saída
sread_ptr	uint32_t	O buffer de onde o STObject de origem será lido
sread_len	uint32_t	O tamanho do objeto de origem
fread_ptr	uint32_t	O buffer de onde o campo a ser inserido/injetado será lido
fread_len	uint32_t	O tamanho do campo a ser inserido/injetado
field_id	uint32_t	O código sf (localização) para formar a inserção. Se já existir no objeto de origem, o campo existente é substituído. Se não existir, é inserido.

JavaScript

Nome	Tipo	Descrição
sto	ByteArray | HexString	O objeto STO (dados de ledger codificados em binário) ao qual o campo será adicionado.
field_bytes	ByteArray | HexString	Os bytes que representam o campo a ser adicionado.
field_id	number	O ID do campo a ser adicionado.

Código de Retorno

C

Tipo

Descrição

int64_t

O número de bytes escritos em write_ptr Se negativo, um erro: OUT_OF_BOUNDS - ponteiros/tamanhos especificados fora da memória do hook. TOO_SMALL - O buffer de saída deve ser pelo menos tão grande quanto o objeto de origem + o campo injetado, mesmo que o campo esteja apenas sendo substituído. TOO_BIG - O campo que você está tentando inserir é muito grande PARSE_ERROR - O STObject fornecido está malformado ou não é um STObject.

JavaScript

Tipo	Descrição
ErrorCode | ByteArray	O objeto STO atualizado em formato de dados de ledger codificados em binário, ou um código de erro se a operação falhar.