gln_create_file_state_store

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

GLN_API gln_status_t GLN_CALL gln_create_file_state_store(
    const char*         in_state_path,
    const char*         in_key_path_or_null,
    gln_state_store_t** out_store,
    gln_error_t*        out_error);

Family: Create and open functions
Return type: gln_status_t

Purpose

Creates a caller-owned FinTS state-store handle backed by one encrypted state blob file.

Use this constructor when the built-in file-backed state store is sufficient and a custom gln_state_store_vtable_t is unnecessary.

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_state_path`	input	`const char*`	nonnull	borrowed
`in_key_path_or_null`	input	`const char*`	nullable	borrowed
`out_store`	output	`gln_state_store_t**`	nonnull	transferred_out
`out_error`	output	`gln_error_t*`	nullable	caller_allocated_output

Path Semantics

in_state_path names the encrypted state blob file. It is a file path, not a directory path.

in_key_path_or_null may be NULL. When it is NULL, the state-store storage helpers derive the sidecar key path as .galanthus_fints.key in the state file's parent directory.

Supplied paths are copied into std::filesystem::path values and used as filesystem paths by the implementation. An explicit key path is used as supplied; it is not resolved relative to in_state_path.

Storage Security

The store encrypts the serialized state blob and uses a separate sidecar key file. A process that can read both files can recover the state, so callers must protect the state file, the sidecar key file, and their containing directories.

The constructor only builds the handle. The state blob and key are created lazily when state is saved; loading before a state blob exists reports an empty store.

Ownership And Lifetime

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

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

gln_open_fints_backend retains the underlying shared store implementation during a successful open, so the C state-store handle may be destroyed after gln_open_fints_backend returns GLN_OK.

gln_open_revolut_backend and gln_open_wise_backend keep non-owning references to the C state-store handle. Keep the handle alive until every Revolut or Wise backend using it has been closed.

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_state_path or out_store is NULL.

Allocation or path-construction failures return a non-OK status. File, permission, lock, key, and write/read errors surface later when a backend operation loads or saves through the store.

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