state_set

Set the Hook State for a given key and value

Behaviour

• Read a 32 byte Hook State key from the kread_ptr
• Read an arbitrary amount of data from read_ptr (the value)
• Update the Hook State key with the value

Definition

C

int64_t state_set (
    uint32_t read_ptr,
    uint32_t read_len,
    uint32_t kread_ptr,
    uint32_t kread_len  
);

Example

C

#define SBUF(str) (uint32_t)(str), sizeof(str)
if (state_set(SBUF(vault), SBUF(vault_key)) < 0)
		rollback(SBUF("Error: could not set state!"), 1);

📘

Hint

To delete the state use state_set(0, 0, SBUF(key);.

Parameters

Name	Type	Description
read_ptr	uint32_t	Pointer to the data (value) to write into Hook State. If this is 0 (null) then delete the data at this key. May be null.
read_len	uint32_t	The length of the data. If this is 0 (null) then delete the data at this key. May be null.
kread_ptr	uint32_t	A pointer to the Hook State key at which to store the value.
kread_len	uint32_t	The length of the key. (Should always be 32.)

🚧

Caution

Xrpl sets internally a maximum hook data size. At time of writing and for public testnet this is hard coded at 128 bytes, however in future it will be a validator-votable number.

Return Code

Type	Description
int64_t	The number of bytes written to Hook State (the length of the data.) If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_BIG - kread_len was greater than 32, or - read_len was greater than the maximum hook data size. TOO_SMALL - kread_len was 0.