mirror of
https://github.com/extism/extism.git
synced 2026-01-12 07:18:02 -05:00
352 lines
7.5 KiB
Markdown
352 lines
7.5 KiB
Markdown
# libextism API
|
|
|
|
We [generate C headers](https://github.com/extism/extism/blob/main/runtime/extism.h) 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](/docs/concepts/host-sdk) 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, this should be freed with
|
|
`extism_plugin_new_error_free`
|
|
|
|
|
|
```c
|
|
ExtismPlugin extism_plugin_new(const uint8_t *wasm,
|
|
ExtismSize wasm_size,
|
|
const ExtismFunction **functions,
|
|
ExtismSize n_functions,
|
|
bool with_wasi,
|
|
char **errmsg);
|
|
```
|
|
---
|
|
|
|
### `extism_plugin_new_error_free`
|
|
|
|
Frees the error message returned when creating a plugin
|
|
|
|
```c
|
|
void extism_plugin_new_error_free(char *err);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_plugin_free`
|
|
|
|
Remove a plugin from the registry and free associated memory.
|
|
|
|
```c
|
|
void extism_plugin_free(ExtismPlugin *plugin);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_plugin_config`
|
|
|
|
Update plugin config values, this will merge with the existing values.
|
|
|
|
```c
|
|
bool extism_plugin_config(ExtismPlugin *plugin,
|
|
const uint8_t *json,
|
|
ExtismSize json_size);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_plugin_function_exists`
|
|
|
|
Returns true if `func_name` exists.
|
|
|
|
```c
|
|
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`
|
|
|
|
Returns `0` when the call is successful.
|
|
|
|
```c
|
|
int32_t extism_plugin_call(ExtismPlugin *plugin,
|
|
const char *func_name,
|
|
const uint8_t *data,
|
|
ExtismSize data_len);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_plugin_call_with_host_context`
|
|
|
|
Call a function with additional host context that can be accessed from inside host functions.
|
|
- `func_name`: is the function to call
|
|
- `data`: is the input data
|
|
- `data_len`: is the length of `data`
|
|
- `host_ctx`: an opaque pointer that can be accessed in host functions
|
|
|
|
Returns `0` when the call is successful.
|
|
|
|
```c
|
|
int32_t extism_plugin_call_with_host_context(ExtismPlugin *plugin,
|
|
const char *func_name,
|
|
const uint8_t *data,
|
|
ExtismSize data_len,
|
|
void *host_ctx);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_plugin_error`
|
|
|
|
Get the error associated with a `Plugin`
|
|
|
|
```c
|
|
const char *extism_plugin_error(ExtismPlugin *plugin);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_plugin_output_length`
|
|
|
|
Get the length of a plugin's output data.
|
|
|
|
```c
|
|
ExtismSize extism_plugin_output_length(ExtismPlugin *plugin);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_plugin_output_data`
|
|
|
|
Get the plugin's output data.
|
|
|
|
```c
|
|
const uint8_t *extism_plugin_output_data(ExtismPlugin *plugin);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_plugin_reset`
|
|
|
|
Reset the Extism runtime, this will invalidate all allocated memory.
|
|
|
|
```c
|
|
bool extism_plugin_reset(ExtismPlugin *plugin);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_log_file`
|
|
|
|
Set log file and level.
|
|
|
|
```c
|
|
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
|
|
|
|
```c
|
|
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.
|
|
|
|
```c
|
|
void extism_log_drain(void (*handler)(const char *, uintptr_t));
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_version`
|
|
|
|
Get the Extism version string.
|
|
|
|
```c
|
|
const char *extism_version(void);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_current_plugin_memory`
|
|
|
|
Returns a pointer to the memory of the currently running plugin
|
|
|
|
```c
|
|
uint8_t *extism_current_plugin_memory(ExtismCurrentPlugin *plugin);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_current_plugin_host_context`
|
|
|
|
Get access to the host context, passed in using `extism_plugin_call_with_host_context`
|
|
|
|
```c
|
|
void *extism_current_plugin_host_context(ExtismCurrentPlugin *plugin);
|
|
```
|
|
|
|
---
|
|
|
|
|
|
### `extism_current_plugin_memory_alloc`
|
|
|
|
Allocate a memory block in the currently running plugin
|
|
|
|
```c
|
|
uint64_t extism_current_plugin_memory_alloc(ExtismCurrentPlugin *plugin, ExtismSize n);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_current_plugin_memory_length`
|
|
|
|
Get the length of an allocated block
|
|
|
|
```c
|
|
ExtismSize extism_current_plugin_memory_length(ExtismCurrentPlugin *plugin, ExtismSize n);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_current_plugin_memory_free`
|
|
|
|
Free an allocated memory block
|
|
|
|
```c
|
|
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.
|
|
|
|
```c
|
|
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`
|
|
|
|
```c
|
|
void extism_function_set_namespace(ExtismFunction *ptr, const char *namespace_);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_function_free`
|
|
|
|
Free an `ExtismFunction`
|
|
|
|
```c
|
|
void extism_function_free(ExtismFunction *ptr);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_plugin_cancel_handle`
|
|
|
|
Get handle for plugin cancellation
|
|
|
|
```c
|
|
const ExtismCancelHandle *extism_plugin_cancel_handle(const ExtismPlugin *plugin);
|
|
```
|
|
|
|
---
|
|
|
|
### `extism_plugin_cancel`
|
|
|
|
Cancel a running plugin from another thread
|
|
|
|
```c
|
|
bool extism_plugin_cancel(const ExtismCancelHandle *handle);
|
|
```
|
|
|
|
---
|
|
|
|
## Type definitions:
|
|
|
|
### `ExtismPlugin`
|
|
|
|
```c
|
|
typedef struct ExtismPlugin ExtismPlugin;
|
|
```
|
|
|
|
### `ExtismSize`
|
|
|
|
```c
|
|
typedef uint64_t ExtismSize;
|
|
```
|
|
|
|
### `ExtismFunction`
|
|
|
|
`ExtismFunction` is used to register host functions with plugins
|
|
|
|
```c
|
|
typedef struct ExtismFunction ExtismFunction;
|
|
```
|
|
|
|
### `ExtismCurrentPlugin`
|
|
|
|
`ExtismCurrentPlugin` provides access to the currently executing plugin from within a host function
|
|
|
|
```c
|
|
typedef struct ExtismCurrentPlugin ExtismCurrentPlugin;
|
|
```
|
|
|
|
### `ExtismCancelHandle`
|
|
|
|
`ExtismCancelHandle` can be used to cancel a running plugin from another thread
|
|
|
|
```c
|
|
typedef struct ExtismCancelHandle ExtismCancelHandle;
|
|
```
|
|
|
|
|