All Hook APIs follow a standard naming convention:
[ _ noun #1 ]
[ _ verb ]
[ _ noun #2 ]
This may look confusing at first but is actually quite simple:
- If the first noun is missing then it is implicitly the same as the namespace
- If the verb is missing then it is implicitly
state()means: fetch a hook state.
state_set()means: set a hook.
state_foreign()means: fetch a foreign hook state.
Each Hook executes as a singular stack frame. All working memory must exist within this stackframe. There is no heap and no dynamic memory.
When Hooks communicate with
xrpld they can only pass integer values. Typically these integers are pointers within the Hook's memory. Since the Hook runs within xrpld, these points can then be resolved by xrpld and written to or read from as needed to perform the Hook API function.
Only two functions are allowed within a Hook:
cbak(). Read about this here
All parameters passed to a Hook API must be one of:
uint32_t, int32_t, uint64_t, int64_t. Typically these are pointers and lengths of buffers within the Hook's stack frame. Sometimes they are Integer Encoded Floating Point Numbers (XFL) or other data.
The parameters to a Hook API are always in the following order:
- Writing pointer if any
- Writing length if any
- Reading pointer if any
- Reading length if any
- Specifics / other fields if any
Some Hook APIs may only write or may only read from memory, and some might not do either and return a value only by return code.
All Hook APIs return a signed integer. Read about return codes here: Return codes