Hook API Conventions

Naming conventions

All Hook APIs follow a standard naming convention:

namespace[ _ 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 get

Thus:

  • state() means: fetch a hook state.
  • state_set() means: set a hook.
  • state_foreign() means: fetch a foreign hook state.

Memory model

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.

Allowed functions

Only two functions are allowed within a Hook: hook() and cbak(). Read about this here

Parameters

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:

  1. Writing pointer if any
  2. Writing length if any
  3. Reading pointer if any
  4. Reading length if any
  5. 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.

Return codes

All Hook APIs return a signed integer. Read about return codes here: Return codes