extism/libextism/API.md

libextism API

We generate C headers so that any language with a C-compatible FFI can bind functions to the runtime itself and embed Extism. This is how most of the official SDKs are created.

If you would like to embed Extism into a language that we currently do not support, you should take a look at the header file linked above.

The general set of functions that is necessary to satisfy the runtime requirements is:

extism_plugin_new

Create a new plugin.

• wasm: is a WASM module (wat or wasm) or a JSON encoded manifest
• wasm_size: the length of the wasm parameter
• functions: is an array of ExtismFunction*
• n_functions: is the number of functions
• with_wasi: enables/disables WASI
• errmsg: error message during plugin creation

ExtismPlugin extism_plugin_new(const uint8_t *wasm,
                               ExtismSize wasm_size,
                               const ExtismFunction **functions,
                               ExtismSize n_functions,
                               bool with_wasi,
                               char **errmsg);

extism_plugin_free

Remove a plugin from the registry and free associated memory.

void extism_plugin_free(ExtismPlugin *plugin);

extism_plugin_config

Update plugin config values, this will merge with the existing values.

bool extism_plugin_config(ExtismPlugin *plugin,
                          const uint8_t *json,
                          ExtismSize json_size);

extism_plugin_function_exists

Returns true if func_name exists.

bool extism_plugin_function_exists(ExtismPlugin *plugin,
                                   const char *func_name);

extism_plugin_call

Call a function.

• func_name: is the function to call
• data: is the input data
• data_len: is the length of data

int32_t extism_plugin_call(ExtismPlugin *plugin,
                           const char *func_name,
                           const uint8_t *data,
                           ExtismSize data_len);

extism_plugin_error

Get the error associated with a Plugin

const char *extism_plugin_error(ExtismPlugin *plugin);

extism_plugin_output_length

Get the length of a plugin's output data.

ExtismSize extism_plugin_output_length(ExtismPlugin *plugin);

extism_plugin_output_data

Get the plugin's output data.

const uint8_t *extism_plugin_output_data(ExtismPlugin *plugin);

extism_plugin_reset

Reset the Extism runtime, this will invalidate all allocated memory.

bool extism_plugin_reset(ExtismPlugin *plugin);

extism_log_file

Set log file and level.

bool extism_log_file(const char *filename, const char *log_level);

extism_log_custom

Enable a custom log handler, this will buffer logs until extism_log_drain is called Log level should be one of: info, error, trace, debug, warn

bool extism_log_custom(const char *log_level);

extism_log_drain

Calls the provided callback function for each buffered log line. This is only needed when extism_log_custom is used.

void extism_log_drain(void (*handler)(const char *, uintptr_t));

extism_version

Get the Extism version string.

const char *extism_version(void);

extism_current_plugin_memory

Returns a pointer to the memory of the currently running plugin

uint8_t *extism_current_plugin_memory(ExtismCurrentPlugin *plugin);

extism_current_plugin_memory_alloc

Allocate a memory block in the currently running plugin

uint64_t extism_current_plugin_memory_alloc(ExtismCurrentPlugin *plugin, ExtismSize n);

extism_current_plugin_memory_length

Get the length of an allocated block

ExtismSize extism_current_plugin_memory_length(ExtismCurrentPlugin *plugin, ExtismSize n);

extism_current_plugin_memory_free

Free an allocated memory block

void extism_current_plugin_memory_free(ExtismCurrentPlugin *plugin, uint64_t ptr);

extism_function_new

Create a new host function

• name: function name, this should be valid UTF-8
• inputs: argument types
• n_inputs: number of argument types
• outputs: return types
• n_outputs: number of return types
• func: the function to call
• user_data: a pointer that will be passed to the function when it's called this value should live as long as the function exists
• free_user_data: a callback to release the user_data value when the resulting ExtismFunction is freed.

Returns a new ExtismFunction or null if the name argument is invalid.

ExtismFunction *extism_function_new(const char *name,
                                    const ExtismValType *inputs,
                                    ExtismSize n_inputs,
                                    const ExtismValType *outputs,
                                    ExtismSize n_outputs,
                                    ExtismFunctionType func,
                                    void *user_data,
                                    void (*free_user_data)(void *_));

extism_function_set_namespace

Set the namespace of an ExtismFunction

void extism_function_set_namespace(ExtismFunction *ptr, const char *namespace_);

extism_function_free

Free an ExtismFunction

void extism_function_free(ExtismFunction *ptr);

extism_plugin_cancel_handle

Get handle for plugin cancellation

const ExtismCancelHandle *extism_plugin_cancel_handle(const ExtismPlugin *plugin);

extism_plugin_cancel

Cancel a running plugin from another thread

bool extism_plugin_cancel(const ExtismCancelHandle *handle);

Type definitions:

ExtismPlugin

typedef int32_t ExtismPlugin;

ExtismSize

typedef uint64_t ExtismSize;

ExtismFunction

ExtismFunction is used to register host functions with plugins

typedef struct ExtismFunction ExtismFunction;

ExtismCurrentPlugin

ExtismCurrentPlugin provides access to the currently executing plugin from within a host function

typedef struct ExtismCurrentPlugin ExtismCurrentPlugin;

ExtismCancelHandle

ExtismCancelHandle can be used to cancel a running plugin from another thread

typedef struct ExtismCancelHandle ExtismCancelHandle;