gln_create_file_continuation_store

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

GLN_API gln_status_t GLN_CALL gln_create_file_continuation_store(
    const char*                in_directory_path,
    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 backed by encrypted resume files in a directory.

Use this constructor to persist resumable operation artifacts with the built-in file-backed store.

Nullable parameter slots (out_error) may be passed as NULL; all other non-value parameters follow the nullability shown in the table.

Return

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

Parameters

Path Semantics

in_directory_path names the directory that will contain continuation artifacts. The constructor creates this directory if it does not already exist.

Each continuation ID is stored as <id>.resume inside that directory; the implementation accepts only non-empty IDs made from [A-Za-z0-9._-] so an ID cannot escape the directory.

Storage 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 files on disk are ciphertext only (header || nonce || ciphertext || tag). Continuations can resume in-flight banking operations, so callers must protect the directory and the key material with care.

The directory is created at constructor time. Individual resume files are created lazily when continuations are saved. 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.

Ownership And Lifetime

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

The continuation-store handle is caller-owned; calls that accept it do not destroy it.

gln_open_fints_backend retains the underlying shared continuation-store implementation during a successful open, so the C continuation-store handle does not need to outlive the opened FinTS backend.

Direct calls to gln_save_continuation and gln_load_continuation borrow the C continuation-store handle and require it to remain live for the duration of the call.

Failure Cases

After accepting the optional out_error slot as valid, the function clears *out_store to NULL before validating the remaining arguments when out_store is non-NULL.

The call returns GLN_ERR_INVALID_ARG when in_directory_path, in_encryption_key, or out_store is NULL, or when in_encryption_key does not wrap exactly 32 bytes of key material.

Allocation, path-construction, or directory-creation failures return a non-OK status. Later save/load calls can also return file, permission, lock, encryption, and write/read errors.

out_error may be NULL. If it is non-NULL, its struct_size must describe a valid gln_error_t.

See Also

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