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,
    const char*                in_key_path_or_null,
    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 (in_key_path_or_null, 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.

Type	Nullability	Ownership
`gln_status_t`	value	value

Parameters

Name	Direction	Type	Nullability	Ownership
`in_directory_path`	input	`const char*`	nonnull	borrowed
`in_key_path_or_null`	input	`const char*`	nullable	borrowed
`out_store`	output	`gln_continuation_store_t**`	nonnull	transferred_out
`out_error`	output	`gln_error_t*`	nullable	caller_allocated_output

Path Semantics

in_directory_path is a required non-empty UTF-8 filesystem path string naming 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_key_path_or_null optionally selects the protected-key sidecar path. Passing NULL or an empty string uses the Galanthus default .galanthus_continuations.key file in in_directory_path.

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 sidecar key path with care.

The directory is created at constructor time. Individual resume files are created lazily when continuations are saved. Key sidecars are created lazily when a continuation is first saved.

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; gln_remove_continuation borrows it and removes one stored entry by id. These calls require the handle 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 is NULL or empty, or when out_store is NULL.

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.

Remove Semantics

File-backed remove resolves <id>.resume inside the configured directory, refuses to remove paths that are not regular files, and reports those failures with issue type continuation_store_remove_failed.