These docs are for v2.0. Click to read the latest docs for v3.0.

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

🚧

Field ID encoding

The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field
Thus type 1 field 2 would be 0x10002U.

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

NameTypeDescription
write_ptruint32_tThe buffer to write the modified STObject to
write_lenuint32_tThe length of the output buffer
sread_ptruint32_tThe buffer to read the source STObject from
sread_lenuint32_tThe Length of the source object
fread_ptruint32_tThe buffer to read the field to be emplaced/injected from
fread_lenuint32_tThe length of the field to be emplaced/injected
field_iduint32_tThe 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

TypeDescription
int64_tThe 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.