gln_create_continuation_store

Declared in <galanthus/c_api/gln_capi.h>.

GLN_API gln_status_t GLN_CALL gln_create_continuation_store(
    const gln_continuation_store_vtable_t* in_vtable,
    gln_secret_t*                          in_encryption_key,
    gln_continuation_store_t**             out_store,
    gln_error_t*                           out_error);

• Family: Create and open functions
• Return type: gln_status_t

Purpose

Creates a caller-owned continuation-store handle from a caller-supplied vtable.

Use this constructor when the host application owns persistence for resumable operation artifacts.

Return

Returns GLN_OK on success and a non-OK gln_status_t value on failure.

Parameters

Vtable Contract

in_vtable must point to a complete gln_continuation_store_vtable_t. The required callbacks are save, load, and free_payload; user_data may be NULL and is passed unchanged to each callback.

save persists in_payload[0..in_len) under the library-supplied in_id before returning GLN_OK. The bytes the library hands the callback are ciphertext (header || nonce || ciphertext || tag); the user vtable does not see plaintext.

load returns the previously saved artifact for in_id. On GLN_OK, a nonzero *out_len requires a non-NULL freshly allocated *out_payload; return GLN_ERR_NOT_FOUND when no artifact exists for that ID. The library decrypts the returned bytes internally before any higher layer sees them.

Callback Ownership

in_id and in_payload are borrowed from the library for the callback only. Copy the ID and payload into the backing store if they must live after the callback returns.

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.

Persistence Security

in_encryption_key supplies the AES-256-GCM key used to encrypt every continuation persisted through this store. The secret must wrap exactly 32 bytes of key material; the store retains its own owning copy of those bytes and the caller may destroy in_encryption_key after the call returns.

Continuation artifacts can resume an in-flight banking operation and can include bank-facing request context. Encryption at the C-API boundary is non-optional; the user vtable always sees ciphertext (header || nonce || ciphertext || tag).

Key transport (where the 32 bytes come from: a sidecar file, an OS keyring, an env var, a derivation from a password) is the caller's responsibility and is not handled by this constructor.

Handle Lifetime

On success, out_store receives a caller-owned handle that must be released with gln_destroy_continuation_store.

The handle stores a copy of the vtable values and an owning copy of the encryption key bytes. The object referenced by user_data remains host-owned and must stay valid for as long as any live handle or backend-retained continuation-store implementation can invoke the callbacks.

When a backend-open path retains the handle's underlying shared continuation-store implementation, that implementation remains alive after this C handle is destroyed.

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, in_encryption_key, out_store, save, load, or free_payload is NULL, or when in_encryption_key does not wrap exactly 32 bytes of key material.

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.

See Also

• gln_create_file_continuation_store
• gln_destroy_continuation_store
• gln_save_continuation
• gln_load_continuation
• gln_open_fints_backend
• ABI function index