gln_open_ebics_backend

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

GLN_API gln_status_t GLN_CALL gln_open_ebics_backend(
    const gln_ebics_config_t* in_config,
    gln_key_store_t*          in_key_store,
    gln_backend_t**           out_backend,
    gln_error_t*              out_error);

Family: Create and open functions
Return type: gln_status_t

Purpose

Opens an EBICS backend handle from a typed EBICS configuration and a required key store.

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_ebics_config_t*`	nonnull	borrowed
`in_key_store`	input	`gln_key_store_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_ebics_config_t by calling gln_default_ebics_config so struct_size and optional defaults match the loaded header.

The required config fields are endpoint, host_id, partner_id, user_id, and product_id. Optional fields include product language, security medium, dump directory, TLS public-key pin, and timeout; empty optional strings are treated as absent.

product_language_or_null defaults to de, and security_medium_or_null defaults to 0000 when those fields are missing or empty.

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

Ownership And Lifetime

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

The EBICS client uses the retained key-store implementation for client keys, bank keys, certificates, and key reset/promotion callbacks. The backend does not destroy the caller's key-store handle.

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, or in_key_store is NULL, when in_config->struct_size does not match sizeof(gln_ebics_config_t), or when a required config string is missing.

Config translation, client construction, or backend allocation 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_ebics_config_t config = {0};
gln_default_ebics_config(&config);
config.endpoint = "https://bank.example/ebicsweb";
config.host_id = "BANKHOST";
config.partner_id = "PARTNER01";
config.user_id = "USER01";
config.product_id = "MYPRODUCTID";

gln_backend_t* backend = NULL;
gln_error_t error = {0};
gln_default_error(&error);
gln_status_t rc = gln_open_ebics_backend(
    &config,
    key_store,
    &backend,
    &error);
if (rc == GLN_OK) {
    run_ebics_operations(backend);
}

gln_close_backend(backend);
gln_release_error(&error);