gln_open_fints_backend

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

GLN_API gln_status_t GLN_CALL gln_open_fints_backend(
    const gln_fints_config_t* in_config,
    gln_state_store_t*        in_state_store,
    gln_continuation_store_t* in_continuation_store_or_null,
    gln_secret_t*             in_pin,
    gln_backend_t**           out_backend,
    gln_error_t*              out_error);

Family: Create and open functions
Return type: gln_status_t

Purpose

Opens a FinTS backend handle from a typed FinTS configuration, a required state store, an optional continuation store, and a required PIN secret.

On success, out_backend receives a caller-owned backend handle that must be closed with gln_close_backend.

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_config`	input	`const gln_fints_config_t*`	nonnull	borrowed
`in_state_store`	input	`gln_state_store_t*`	nonnull	borrowed
`in_continuation_store_or_null`	input	`gln_continuation_store_t*`	nullable	borrowed
`in_pin`	input	`gln_secret_t*`	nonnull	borrowed
`out_backend`	output	`gln_backend_t**`	nonnull	transferred_out
`out_error`	output	`gln_error_t*`	nullable	caller_allocated_output

Configuration

Initialize gln_fints_config_t by calling gln_default_fints_config so struct_size and optional defaults match the loaded header.

The required config fields are endpoint, bank_code, user_id, and product_id. Optional string fields use their _or_null names; product_version_or_null defaults to 1.0 when missing or empty, security_reference is ignored when it is GLN_FINTS_SECURITY_REFERENCE_NONE, and timeout_seconds is used only when positive.

The C strings in in_config are borrowed only for the open call. The implementation translates them into the owned FinTS client configuration before returning.

Ownership And Lifetime

in_state_store is required and borrowed for the open call. The backend retains the underlying state-store implementation before returning, so the C store handle itself does not need to outlive the opened backend.

in_continuation_store_or_null may be NULL. When non-NULL, it is borrowed for the open call and the backend retains the underlying continuation-store implementation for resumable interrupted operations.

in_pin is borrowed for the call; the backend copies the PIN into an owned gln_secret_t before returning and destroys that copy during gln_close_backend. The caller remains responsible for the original secret.

On success, out_backend is caller-owned and must be released with gln_close_backend. The function clears *out_backend to NULL before validation when the output slot itself is non-NULL.

Failure Cases

The call returns GLN_ERR_INVALID_ARG when out_backend, in_config, in_state_store, or in_pin is NULL, when in_config->struct_size does not match sizeof(gln_fints_config_t), or when a required config string is missing.

Config translation, client construction, backend allocation, or PIN-copy failures return a non-OK status. When out_error is a valid non-NULL error slot, the function clears it on entry and writes failure details for these validation and construction failures.

out_error may be NULL. If it is non-NULL, its struct_size must describe a valid gln_error_t; otherwise the call fails before writing diagnostic fields.

Example

gln_fints_config_t config = {0};
gln_default_fints_config(&config);
config.endpoint = "https://bank.example/fints";
config.bank_code = "12030000";
config.user_id = "fints-user";
config.product_id = "MYPRODUCTID";

gln_backend_t* backend = NULL;
gln_error_t error = {0};
gln_default_error(&error);
gln_status_t rc = gln_open_fints_backend(
    &config,
    state_store,
    continuation_store_or_null,
    pin_secret,
    &backend,
    &error);
if (rc == GLN_OK) {
    run_fints_operations(backend);
}

gln_close_backend(backend);
gln_release_error(&error);