Backend Results - Varinomics

The operation surface is built around gln_backend_t and gln_backend_result_t. Backend operation calls produce one caller-owned result envelope, and every typed list, row, string, error view, and interrupt view derived from that envelope is borrowed from it.

Call Contract

Operation functions such as gln_retrieve_accounts and gln_submit_transfer return gln_status_t to report whether an envelope was produced.

Function return	`out_result`	Caller action
`GLN_OK`	Non-null envelope	Inspect `gln_get_backend_result_status`, `gln_get_backend_result_outcome`, and `gln_get_backend_result_kind`.
non-`GLN_OK`	No envelope	Treat the return as an argument/allocation level failure for the call itself.

When an envelope exists, the envelope is the source of truth for the operation result:

Envelope accessor	Meaning
`gln_get_backend_result_status`	Provider/domain status represented as `gln_status_t`.
`gln_get_backend_result_outcome`	Coarse outcome: success, action required, rejected, or error.
`gln_get_backend_result_kind`	Typed payload kind.
`gln_get_backend_result_error`	Borrowed structured error when the outcome is rejected or error.
`gln_get_backend_result_interrupt_info`	Borrowed interrupt information when action is required.
`gln_take_backend_result_continuation`	Transfers the continuation handle out of the envelope.

Destroy every produced envelope with gln_destroy_backend_result.

For action-required envelopes, gln_get_backend_result_status identifies the specific pending action: GLN_ERR_TAN_REQUIRED, GLN_ERR_DECOUPLED_PENDING, or GLN_ERR_VOP_CONFIRMATION_REQUIRED. gln_get_backend_result_kind is GLN_BACKEND_RESULT_KIND_UNKNOWN until the operation is resumed and returns a success payload.

Result Kinds and Accessors

Result kind	Accessor	Handle
`GLN_BACKEND_RESULT_KIND_OPAQUE_JSON`	`gln_get_backend_result_opaque_json`	`const char*`
`GLN_BACKEND_RESULT_KIND_ACCOUNTS`	`gln_get_backend_result_accounts`	`const gln_accounts_t*`
`GLN_BACKEND_RESULT_KIND_BALANCES`	`gln_get_backend_result_balances`	`const gln_balances_t*`
`GLN_BACKEND_RESULT_KIND_TRANSACTIONS`	`gln_get_backend_result_transactions`	`const gln_transactions_t*`
`GLN_BACKEND_RESULT_KIND_TAN_MODES`	`gln_get_backend_result_tan_modes`	`const gln_tan_modes_t*`
`GLN_BACKEND_RESULT_KIND_TAN_MODE_SELECTION`	`gln_get_backend_result_tan_mode_selection`	`const gln_tan_mode_selection_t*`
`GLN_BACKEND_RESULT_KIND_TAN_MEDIA`	`gln_get_backend_result_tan_media`	`const gln_tan_media_t*`
`GLN_BACKEND_RESULT_KIND_HOLDINGS`	`gln_get_backend_result_holdings`	`const gln_holdings_t*`
`GLN_BACKEND_RESULT_KIND_STANDING_ORDERS`	`gln_get_backend_result_standing_orders`	`const gln_standing_orders_t*`
`GLN_BACKEND_RESULT_KIND_STANDING_ORDER_SUBMISSION`	`gln_get_backend_result_standing_order_submission`	`const gln_standing_order_submission_t*`
`GLN_BACKEND_RESULT_KIND_PREPAID_TOPUP_SUBMISSION`	`gln_get_backend_result_prepaid_topup_submission`	`const gln_prepaid_topup_submission_t*`
`GLN_BACKEND_RESULT_KIND_TRANSFER_SUBMISSION`	`gln_get_backend_result_transfer_submission`	`const gln_transfer_submission_t*`
`GLN_BACKEND_RESULT_KIND_BATCH_TRANSFER_SUBMISSION`	`gln_get_backend_result_batch_transfer_submission`	`const gln_batch_transfer_submission_t*`
`GLN_BACKEND_RESULT_KIND_DIRECT_DEBIT_SUBMISSION`	`gln_get_backend_result_direct_debit_submission`	`const gln_direct_debit_submission_t*`
`GLN_BACKEND_RESULT_KIND_BANK_INFO`	`gln_get_backend_result_bank_info`	`const gln_bank_info_t*`

Calling a typed get_* accessor on a non-matching kind returns NULL. gln_get_backend_result_opaque_json returns a borrowed string only for GLN_BACKEND_RESULT_KIND_OPAQUE_JSON. Typed success envelopes do not carry an opaque JSON payload; consume them through the matching typed accessor.

Backend Support

gln_check_backend_operation_support answers against the opened backend handle. gln_get_backend_operation_name and gln_parse_backend_operation_name convert between enum values and stable operation names.

Operation name	Supported backends
`get_tan_modes`	FinTS
`set_tan_mode`	FinTS
`list_tan_media`	FinTS
`list_accounts`	FinTS, EBICS
`list_balances`	FinTS, EBICS
`list_transactions`	FinTS, EBICS
`list_holdings`	FinTS
`list_standing_orders`	FinTS
`submit_prepaid_topup`	FinTS
`add_standing_order`	FinTS
`resume`	FinTS
`submit_transfer`	FinTS, EBICS
`submit_instant_transfer`	FinTS
`submit_batch_transfer`	FinTS, EBICS
`submit_direct_debit`	FinTS, EBICS
`submit_direct_debit_batch`	FinTS, EBICS
`modify_standing_order`	FinTS
`delete_standing_order`	FinTS
`info`	FinTS

Example: Inspect an Envelope

gln_backend_result_t* result = NULL;
gln_status_t call_status = gln_retrieve_accounts(backend, &result);
if (call_status != GLN_OK) {
    return 1;
}

if (gln_get_backend_result_outcome(result) == GLN_BACKEND_OUTCOME_SUCCESS &&
    gln_get_backend_result_kind(result) == GLN_BACKEND_RESULT_KIND_ACCOUNTS) {
    const gln_accounts_t* accounts = gln_get_backend_result_accounts(result);
    for (size_t i = 0; i < gln_get_accounts_count(accounts); ++i) {
        const gln_account_t* account = gln_get_account_at(accounts, i);
        const char* iban = gln_get_account_iban(account);
        (void)iban;
    }
} else if (gln_get_backend_result_outcome(result) == GLN_BACKEND_OUTCOME_ACTION_REQUIRED) {
    const gln_interrupt_info_t* interrupt = gln_get_backend_result_interrupt_info(result);
    gln_continuation_t* continuation = gln_take_backend_result_continuation(result);
    (void)interrupt;
    gln_destroy_continuation(continuation);
} else {
    const gln_error_t* error = gln_get_backend_result_error(result);
    (void)error;
}

gln_destroy_backend_result(result);

Continuation and Resume Flow

Call an operation and inspect the produced envelope.
If gln_get_backend_result_outcome(result) is GLN_BACKEND_OUTCOME_ACTION_REQUIRED, read gln_get_backend_result_interrupt_info(result).
Take the continuation with gln_take_backend_result_continuation(result).
Save it with gln_save_continuation if the user may leave the process, or destroy the original result envelope if the caller is resuming immediately and has copied any interrupt fields it still needs.
Build gln_continuation_input_t with gln_default_continuation_input.
Call gln_resume_continuation with the backend, continuation, optional interactive secret, input struct, and a fresh gln_backend_result_t**.
Destroy the resumed result envelope and the continuation handle.

gln_take_backend_result_continuation transfers ownership. After it returns, the caller must eventually call gln_destroy_continuation.