GALANTHUS / ABI FUNCTION REFERENCE
gln_create_state_store
Declared in <galanthus/c_api/gln_capi.h>.
GLN_API gln_status_t GLN_CALL gln_create_state_store(
const gln_state_store_vtable_t* in_vtable,
gln_state_store_t** out_store,
gln_error_t* out_error);
Purpose
Creates a caller-owned state-store handle from a caller-supplied vtable.
Use this constructor when the host application owns durable state storage instead of using the built-in file-backed store.
Return
Returns GLN_OK on success and a non-OK gln_status_t value on failure.
| Type | Nullability | Ownership |
|---|---|---|
gln_status_t | value | value |
Parameters
| Name | Direction | Type | Nullability | Ownership |
|---|---|---|---|---|
in_vtable | input | const gln_state_store_vtable_t* | nonnull | borrowed |
out_store | output | gln_state_store_t** | nonnull | transferred_out |
out_error | output | gln_error_t* | nullable | caller_allocated_output |
Vtable Contract
in_vtable must point to a complete gln_state_store_vtable_t. The required callbacks are load, save, and free_payload; user_data may be NULL and is passed unchanged to each callback.
load returns the previously saved state blob. On GLN_OK, a nonzero *out_len requires a non-NULL freshly allocated *out_payload; return GLN_ERR_NOT_FOUND when no state exists yet.
save persists in_payload[0..in_len) before returning GLN_OK.
Callback Ownership
load output is owned by the store implementation until the library has copied it. The adapter calls free_payload(user_data, payload) for every non-NULL payload returned by load, including failure paths after the callback returned GLN_OK.
save input is borrowed from the library for the callback only. Copy or durably write it before returning; do not retain the pointer.
Handle Lifetime
On success, out_store receives a caller-owned handle that must be released with gln_destroy_state_store.
The handle stores a copy of the vtable values. The object referenced by user_data remains host-owned and must stay valid for as long as any live handle or backend-retained store implementation can invoke the callbacks.
Backend-open pages document backend-specific handle lifetime. FinTS retains the underlying shared store implementation during backend open. Revolut and Wise keep non-owning references to the C store handle, so the handle must stay alive until those backends are closed.
Failure Cases
The function clears *out_store to NULL before validation when out_store is non-NULL.
The call returns GLN_ERR_INVALID_ARG when in_vtable, out_store, load, save, or free_payload is NULL.
out_error may be NULL. If it is non-NULL, its struct_size must describe a valid gln_error_t; the function clears it on entry and writes invalid-vtable details when validation fails.