Emplace a field into an existing STObject at its canonical placement

Concepts

Behaviour

  • Parse an STObject S (source object) pointed to by sread_ptr
  • Parse an STObject F (to inject/emplace) pointed to by fread_ptr
  • Write a new STObject to write_ptr which places F into S at the canonical position field_id

Definition

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
);

Example

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);

Parameters

Name

Type

Description

write_ptr

uint32_t

The buffer to write the modified STObject to

write_len

uint32_t

The length of the output buffer

sread_ptr

uint32_t

The buffer to read the source STObject from

sread_len

uint32_t

The Length of the source object

fread_ptr

uint32_t

The buffer to read the field to be emplaced/injected from

fread_len

uint32_t

The length of the field to be emplaced/injected

field_id

uint32_t

The sf code (location) to form the emplacement. If this already exists in the source object then the existing field is overriden. If it doesn't exist it is inserted.

Return Code

Type

Description

int64_t

The number of bytes written to write_ptr

If negative, an error:
OUT_OF_BOUNDS

  • pointers/lengths specified outside of hook memory.

TOO_SMALL

  • Output buffer must be at least as large as the source object + the injected field, even if the field is only being overriden.

TOO_BIG

  • Field you are attempting to emplace is too large

PARSE_ERROR

  • The supplied STObject is malformed or not an STObject.