gln_retrieve_bank_info

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

GLN_API gln_status_t GLN_CALL gln_retrieve_bank_info(
    gln_backend_t*         in_backend,
    gln_backend_result_t** out_result);

Family: Backend operations
Return type: gln_status_t

Purpose

gln_retrieve_bank_info asks the backend for bank parameter and account information and returns a gln_backend_result_t envelope.

A success result exposes bank name, bank code, embedded account rows, TAN mode rows, and bank-specific operation capability answers.

gln_check_backend_operation_support checks only the backend kind's static operation surface. For FinTS bank-specific capability decisions, retrieve bank info and call gln_get_bank_info_operation_capability for the bank operation. Unsupported calls still return an envelope whose status is GLN_ERR_NOT_SUPPORTED when the backend rejects the operation.

When To Use

Use this operation when the caller needs FinTS bank metadata rather than only the list of accounts.

Use gln_retrieve_accounts when only account rows are needed.

Call Contract

GLN_OK from the function means an envelope was produced in *out_result; it does not mean the backend operation succeeded. Inspect the envelope with gln_get_backend_result_outcome, gln_get_backend_result_status, and gln_get_backend_result_kind.

out_result == NULL is the no-envelope invalid-argument case. In that case the function returns GLN_ERR_INVALID_ARG directly.

The parameter table is binding for required handles and output slots.

Return

Returns GLN_OK when the call produced a gln_backend_result_t envelope in out_result. Operation success, caller action or documented follow-up, provider rejection, and operation errors are reported inside that envelope.

Type	Nullability	Ownership
`gln_status_t`	value	value

Parameters

Name	Direction	Type	Nullability	Ownership
`in_backend`	input	`gln_backend_t*`	nonnull	borrowed
`out_result`	output	`gln_backend_result_t**`	nonnull	transferred_out

Success Result

Successful operation envelopes have outcome GLN_BACKEND_OUTCOME_SUCCESS, status GLN_OK, and kind GLN_BACKEND_RESULT_KIND_BANK_INFO.

Borrow the typed success view with gln_get_backend_result_bank_info.

Use gln_get_backend_result_bank_info only when the envelope outcome is GLN_BACKEND_OUTCOME_SUCCESS and the kind is GLN_BACKEND_RESULT_KIND_BANK_INFO.

Action-required envelopes carry interrupt details and a continuation instead of this typed success view. Resume the operation and read the accessor only after a success envelope is produced.

Read bank fields with gln_get_bank_info_name and gln_get_bank_info_code.

Embedded account rows are enumerated with gln_get_bank_info_accounts_count and gln_get_bank_info_account_at and use the same gln_get_account_* row accessors as gln_retrieve_accounts.

Embedded TAN mode rows are enumerated with gln_get_bank_info_tan_modes_count and gln_get_bank_info_tan_mode_at; use gln_get_bank_info_operation_capability for bank-specific operation availability.

Outcomes

GLN_BACKEND_OUTCOME_SUCCESS: read the GLN_BACKEND_RESULT_KIND_BANK_INFO typed view.
GLN_BACKEND_OUTCOME_ACTION_REQUIRED: FinTS read flows can require caller action, usually a TAN or decoupled step. Inspect gln_get_backend_result_interrupt_info, take the continuation with gln_take_backend_result_continuation, and resume with gln_resume_continuation.
GLN_BACKEND_OUTCOME_REJECTED: inspect gln_get_backend_result_status and gln_get_backend_result_error for FinTS rejection details.
GLN_BACKEND_OUTCOME_ERROR: inspect gln_get_backend_result_status and gln_get_backend_result_error. Other backends use this outcome with status GLN_ERR_NOT_SUPPORTED.

Ownership And Lifetime

The envelope returned through out_result is caller-owned and must be released with gln_destroy_backend_result.

Typed views, result rows or fields, borrowed strings, and the JSON string are borrowed from the envelope. They become invalid when the envelope is destroyed. Copy strings or row data before destroying the envelope when the caller needs to keep them.

For action-required envelopes, gln_get_backend_result_interrupt_info returns borrowed interrupt details. gln_take_backend_result_continuation transfers continuation ownership to the caller; destroy that continuation with gln_destroy_continuation after it has been saved or resumed.