gln_retrieve_tan_modes

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

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

Family: Backend operations
Return type: gln_status_t

Purpose

gln_retrieve_tan_modes asks a backend for TAN security functions and returns the result in a gln_backend_result_t envelope.

Backend support is operation-specific. Use gln_check_backend_operation_support to check whether a backend supports this operation before calling it. Unsupported operations return an envelope whose status is GLN_ERR_NOT_SUPPORTED.

For FinTS, the implementation may use authenticated discovery or cached TAN mechanism fallback when authenticated discovery returns no mechanisms. A success result is therefore not proof that the current bank response still advertises every returned mode or the stored selection.

When To Use

Use this operation before presenting TAN mode choices from the backend result.

Use the rows as selectable TAN security functions for the current interaction. The selected value reported by gln_get_tan_modes_selected is persisted backend state copied into the result.

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, 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_TAN_MODES.

Borrow the typed success view with gln_get_backend_result_tan_modes.

Use gln_get_backend_result_tan_modes only when the envelope outcome is GLN_BACKEND_OUTCOME_SUCCESS and the kind is GLN_BACKEND_RESULT_KIND_TAN_MODES.

Enumerate the modes with gln_get_tan_modes_count and gln_get_tan_mode_at. Each row exposes security_function, name, and decoupled through gln_get_tan_mode_security_function, gln_get_tan_mode_name, and gln_get_tan_mode_decoupled.

gln_get_tan_modes_selected returns the stored selected TAN security function when one is available. For a non-null TAN modes view, NULL means no selected TAN security function is stored in the backend state. A non-NULL value is the cached backend selection copied into the result.

Outcomes

GLN_BACKEND_OUTCOME_SUCCESS: read the GLN_BACKEND_RESULT_KIND_TAN_MODES typed view.
GLN_BACKEND_OUTCOME_REJECTED: inspect gln_get_backend_result_status and gln_get_backend_result_error for bank 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.

This operation reports success or failure through its result envelope; it does not define an action-required continuation path.

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.

Example

gln_backend_result_t* result = NULL;
gln_status_t rc = gln_retrieve_tan_modes(backend, &result);
if (rc != GLN_OK) {
    /* No envelope exists here, for example when out_result was NULL. */
    return rc;
}

if (gln_get_backend_result_outcome(result) == GLN_BACKEND_OUTCOME_SUCCESS &&
    gln_get_backend_result_kind(result) == GLN_BACKEND_RESULT_KIND_TAN_MODES) {
    const gln_tan_modes_t* modes = gln_get_backend_result_tan_modes(result);
    size_t count = gln_get_tan_modes_count(modes);

    for (size_t i = 0; i < count; ++i) {
        const gln_tan_mode_t* mode = gln_get_tan_mode_at(modes, i);
        const char* security_function = gln_get_tan_mode_security_function(mode);
        const char* name = gln_get_tan_mode_name(mode);
        int decoupled = gln_get_tan_mode_decoupled(mode);

        /* security_function and name are borrowed from result.
           Copy them before destroying result if they are needed later. */
        use_tan_mode(security_function, name, decoupled);
    }
}
else {
    gln_status_t status = gln_get_backend_result_status(result);
    const gln_error_t* error = gln_get_backend_result_error(result);
    handle_tan_mode_discovery_failure(status, error);
}

gln_destroy_backend_result(result);