gln_open_wise_backend

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

GLN_API gln_status_t GLN_CALL gln_open_wise_backend(
    const gln_wise_config_t* in_config,
    gln_state_store_t*       in_state_store,
    gln_wise_token_store_t*  in_token_store,
    gln_backend_t**          out_backend,
    gln_error_t*             out_error);

Family: Create and open functions
Return type: gln_status_t

Purpose

Opens a Wise backend handle from a typed Wise configuration, a state store, and a Wise token 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_wise_config_t*`	nonnull	borrowed
`in_state_store`	input	`gln_state_store_t*`	nonnull	borrowed
`in_token_store`	input	`gln_wise_token_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_wise_config_t by calling gln_default_wise_config so struct_size and optional defaults match the loaded header.

The required config field is endpoint. Optional fields include profile_id_or_null, dump_dir_or_null, timeout_seconds, profile_name_or_null, and plugin_dll_path_or_null; empty optional strings are treated as absent and the timeout is used only when positive.

The C strings in in_config are borrowed only for the open call. The implementation copies them into the Wise client object before returning.

profile_name_or_null and plugin_dll_path_or_null are copied when present and non-empty; they are stored for Wise surfaces that require a local profile or plugin path.

Ownership And Lifetime

in_state_store and in_token_store are required and borrowed by the backend. Keep both handles alive until after gln_close_backend closes every backend using them.

The token store persists Wise token state. The file token-store constructor records the store directory, token blob path, and optional sidecar key path; the backend uses the supplied store handle but does not destroy it.

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_token_store is NULL, when in_config->struct_size does not match sizeof(gln_wise_config_t), or when endpoint is missing or empty.

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.

Capability Probing

Code that accepts an arbitrary backend should probe specific operations with gln_check_backend_operation_support; use gln_get_backend_operation_name and gln_parse_backend_operation_name when converting between enum values and operation names.

Example

gln_wise_config_t config = {0};
gln_default_wise_config(&config);
config.endpoint = "https://api.wise.example";
config.profile_id_or_null = "profile-123";

gln_backend_t* backend = NULL;
gln_error_t error = {0};
gln_default_error(&error);
gln_status_t rc = gln_open_wise_backend(
    &config,
    state_store,
    token_store,
    &backend,
    &error);
if (rc == GLN_OK) {
    remember_open_backend(backend);
}

gln_close_backend(backend);
gln_release_error(&error);