state_foreign

Retrieve the data pointed to, on another account, by a Hook State key and write it to an output buffer

Behaviour

C

• Read a 20 byte Account ID from the aread_ptr

• Read a 32 byte Hook State key from the kread_ptr

• Write the data (value) at that key at that Account ID to the buffer pointed to by write_ptr

Javascript

• Retrieves the Foreign Hook State value belonging to another account for the specified key.

• Returns an error code or the Hook State value for the key.

Definition

C

int64_t state_foreign (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t kread_ptr,
    uint32_t kread_len,
    uint32_t nread_ptr,
    uint32_t nread_len,
    uint32_t aread_ptr,
    uint32_t aread_len  
);

Javascript

function state_foreign(
    key: ByteArray | HexString,
    namespace: ByteArray | HexString | undefined | null,
    accountid: ByteArray | HexString | undefined | null
  ): ErrorCode | ByteArray

Example

C

#define SBUF(str) (uint32_t)(str), sizeof(str)
uint8_t ns[32] = {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0};
int64_t lookup =
    state_foreign(SBUF(blacklist_status), SBUF(otxn_accid), SBUF(ns), SBUF(blacklist_accid));
if (lookup < 0)
     rollback(SBUF("Error: could not find key on foreign state."), 1);

Javascript

const ns = [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
const blacklist_status =
    state_foreign(otxn_accid, ns, blacklist_accid)
if (typeof blacklist_status === 'number')
     rollback("Error: could not find key on foreign state.", 1);

Parameters

C

Name	Type	Description
write_ptr	uint32_t	A pointer to the buffer to write the data in the Hook State into.
write_len	uint32_t	The length of the write buffer.
kread_ptr	uint32_t	Pointer to a buffer containing the Hook State key.
kread_len	uint32_t	The length of the Hook State key. (Should be 32.)
nread_ptr	uint32_t	A pointer to the buffer containing the 32 byte Namespace to lookup the state on
nread_len	uint32_t	The length of the namespace buffer (Should be 32).
aread_ptr	uint32_t	A pointer to a buffer containing the 20 byte Account ID to look up state on.
aread_len	uint32_t	The length of the Account buffer. (Should always be 20).

📘Hint

Ensure you check the return value. A state lookup can fail of a range of reasons and the buffer will then contain whatever it did before the call (typically all zeros).

Javascript

Name	Type	Description
key	ByteArray or HexString	The key of the Hook State to retrieve the value from.
namespace	ByteArray or HexString	The Hook namespace to look in.
accountid	ByteArray or HexString	The owner of the state.

Return Code

C

Type

Description

int64_t

The number of bytes written to the write buffer. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. DOESNT_EXIST - the specified Hook State key doesn't have an associated value on the ledger at the time of the call. TOO_BIG - the key specified by read_ptr and read_len was larger than 32 bytes. TOO_SMALL - the output buffer was too small to store the Hook State data. INVALID_ACCOUNT - the account specified at aread_ptr is invalid or does not exist.

Javascript

Type	Description
ErrorCode or ByteArray	Returns an error code or the Hook State value for the key.