client_state.cpp File Reference

Implements client state models and transitions. More...

#include "src/app/client_state.h"
#include "src/network/host_pairing.h"
#include <algorithm>
#include <array>
#include <string_view>
#include <utility>
#include <vector>

Include dependency graph for client_state.cpp:

Functions
void	app::activate_hosts_toolbar (ClientState &state, AppUpdate *update)
	Handles activation of the hosts toolbar.
void	app::activate_selected_host (ClientState &state, AppUpdate *update)
	Activates a selected host from the hosts screen.
bool	app::app_list_result_targets_active_selection (const ClientState &state, const HostRecord *host)
	Returns whether the given host is the active apps-screen selection.
void	app::apply_add_host_validation_error (ClientState &state, std::string_view validationError)
	Applies an invalid add-host draft error to the UI state.
void	app::apply_app_list_result (ClientState &state, const std::string &address, uint16_t port, std::vector< HostAppRecord > apps, uint64_t appListContentHash, bool success, std::string message)
	Apply a fetched app list to a saved host.
void	app::apply_cached_app_list_failure (ClientState &state, HostRecord *host, bool hostIsActiveAppsScreenSelection, std::string message)
	Applies a failed app-list refresh that can fall back to cached app data.
void	app::apply_connection_test_result (ClientState &state, bool success, std::string message)
	Apply the result of a host connection test to the current shell state.
void	app::apply_log_viewer_contents (ClientState &state, std::vector< std::string > lines, std::string statusMessage)
	Replace the loaded log viewer contents.
bool	app::apply_pairing_result (ClientState &state, const std::string &address, uint16_t port, bool success, std::string message)
	Apply the result of a pairing attempt to the current shell state.
void	app::apply_unpaired_app_list_failure (ClientState &state, HostRecord *host, bool hostIsActiveAppsScreenSelection, std::string message)
	Applies a failed app-list refresh for an unpaired host.
const HostRecord *	app::apps_host (const ClientState &state)
	Return the host currently shown by the Apps screen.
bool	app::begin_selected_host_app_browse (ClientState &state, bool showHiddenApps)
	Enter the apps screen for the currently selected host after authorization has been refreshed.
ClientState	app::create_initial_state ()
	Create the initial app state shown after startup.
std::string	app::current_add_host_address (const ClientState &state)
	Return the current host address shown in the add-host flow.
uint16_t	app::current_add_host_port (const ClientState &state)
	Return the effective TCP port for the current add-host draft.
std::string	app::current_pairing_pin (const ClientState &state)
	Return the current pairing PIN shown in the pairing flow.
HostRecord *	app::find_app_list_result_host (ClientState &state, const std::string &address, uint16_t port)
	Finds the host that should receive an app-list refresh result.
bool	app::handle_add_host_keypad_command (ClientState &state, input::UiCommand command)
	Handles commands while the add-host keypad modal is visible.
void	app::handle_add_host_menu_activation (ClientState &state, std::string_view activatedItemId, AppUpdate *update)
	Handles activation of add-host screen menu actions.
bool	app::handle_apps_screen_command (ClientState &state, input::UiCommand command, AppUpdate *update)
	Handles commands on the apps screen.
AppUpdate	app::handle_command (ClientState &state, input::UiCommand command)
	Apply a UI command to the client shell.
bool	app::handle_hosts_screen_command (ClientState &state, input::UiCommand command, AppUpdate *update)
	Handles commands on the hosts screen.
bool	app::handle_overlay_command (ClientState &state, input::UiCommand command, AppUpdate *update)
	Handles overlay toggle and scrolling commands.
void	app::handle_settings_detail_activation (ClientState &state, const ui::MenuUpdate &detailUpdate, AppUpdate *update)
	Handles activation of a settings detail row.
bool	app::handle_settings_screen_command (ClientState &state, input::UiCommand command, AppUpdate *update)
	Handles commands on the settings screen.
bool	app::host_requires_manual_pairing (const ClientState &state, const std::string &address, uint16_t port)
	Return whether a saved host still requires a manual pairing flow.
void	app::mark_cover_art_cached (ClientState &state, const std::string &address, uint16_t port, int appId)
	Mark one cached cover-art entry as available for a host app.
bool	app::merge_discovered_host (ClientState &state, std::string displayName, const std::string &address, uint16_t port)
	Add or refresh one auto-discovered host in the current host list.
std::vector< HostAppRecord >	app::merge_host_app_records (const HostRecord &host, std::vector< HostAppRecord > apps)
	Merges saved app metadata into a freshly fetched app list.
void	app::replace_hosts (ClientState &state, std::vector< HostRecord > hosts, std::string statusMessage={})
	Replace the in-memory host list from a persisted snapshot.
void	app::replace_saved_files (ClientState &state, std::vector< startup::SavedFileEntry > savedFiles)
	Replace the in-memory saved-file inventory shown on the settings page.
void	app::restore_selected_app_after_refresh (ClientState &state, const HostRecord &host, int selectedAppId)
	Restores the previously selected app after a successful refresh.
const HostAppRecord *	app::selected_app (const ClientState &state)
	Return the currently selected app on the Apps screen.
int	app::selected_app_id_for_restore (const ClientState &state)
	Returns the selected app identifier so it can be restored after a refresh.
const HostRecord *	app::selected_host (const ClientState &state)
	Return the currently selected loaded host for the active screen.
void	app::set_log_file_path (ClientState &state, std::string logFilePath)
	Update the log file path tracked by the shell.
const char *	app::to_string (ScreenId screen)
	Return a display label for a screen identifier.

Detailed Description

Implements client state models and transitions.

Function Documentation

activate_hosts_toolbar()

void app::activate_hosts_toolbar	(	ClientState &	state,
		AppUpdate *	update )

Handles activation of the hosts toolbar.

Parameters

state	Client state containing the toolbar selection.
update	Update structure that receives side effects.

activate_selected_host()

void app::activate_selected_host	(	ClientState &	state,
		AppUpdate *	update )

Activates a selected host from the hosts screen.

Parameters

state	Client state containing the selected host.
update	Update structure that receives browse or pairing work.

app_list_result_targets_active_selection()

bool app::app_list_result_targets_active_selection	(	const ClientState &	state,
		const HostRecord *	host )

Returns whether the given host is the active apps-screen selection.

Parameters

state	Client state to inspect.
host	Host potentially backing the apps screen.

Returns

True when the host is the active apps-screen selection.

apply_add_host_validation_error()

void app::apply_add_host_validation_error	(	ClientState &	state,
		std::string_view	validationError )

Applies an invalid add-host draft error to the UI state.

Parameters

state	Client state containing the add-host draft.
validationError	Validation message to display.

apply_app_list_result()

void app::apply_app_list_result	(	ClientState &	state,
		const std::string &	address,
		uint16_t	port,
		std::vector< HostAppRecord >	apps,
		uint64_t	appListContentHash,
		bool	success,
		std::string	message )

Apply a fetched app list to a saved host.

Parameters

state	Mutable app state.
address	Host address used for the fetch.
port	Host port used for the fetch.
apps	Fresh app records returned by the host.
appListContentHash	Stable content hash for the returned app list.
success	Whether the fetch succeeded.
message	User-visible status message.

apply_cached_app_list_failure()

void app::apply_cached_app_list_failure	(	ClientState &	state,
		HostRecord *	host,
		bool	hostIsActiveAppsScreenSelection,
		std::string	message )

Applies a failed app-list refresh that can fall back to cached app data.

Parameters

state	Client state to update.
host	Host receiving the failure.
hostIsActiveAppsScreenSelection	True when the host backs the active apps screen.
message	Failure message returned by the refresh task.

apply_connection_test_result()

void app::apply_connection_test_result	(	ClientState &	state,
		bool	success,
		std::string	message )

Apply the result of a host connection test to the current shell state.

Parameters

state	Mutable app state.
success	Whether the test succeeded.
message	User-visible status message.

apply_log_viewer_contents()

void app::apply_log_viewer_contents	(	ClientState &	state,
		std::vector< std::string >	lines,
		std::string	statusMessage )

Replace the loaded log viewer contents.

Parameters

state	Mutable app state.
lines	Log file lines ready for display.
statusMessage	User-visible status line for the log viewer state.

apply_pairing_result()

bool app::apply_pairing_result	(	ClientState &	state,
		const std::string &	address,
		uint16_t	port,
		bool	success,
		std::string	message )

Apply the result of a pairing attempt to the current shell state.

Parameters

state	Mutable app state.
address	Host address used for pairing.
port	Host port used for pairing.
success	Whether the pairing attempt succeeded.
message	User-visible status message.

Returns

True when the host list changed and should be persisted.

apply_unpaired_app_list_failure()

void app::apply_unpaired_app_list_failure	(	ClientState &	state,
		HostRecord *	host,
		bool	hostIsActiveAppsScreenSelection,
		std::string	message )

Applies a failed app-list refresh for an unpaired host.

Parameters

state	Client state to update.
host	Host receiving the failure.
hostIsActiveAppsScreenSelection	True when the host backs the active apps screen.
message	Failure message returned by the refresh task.

apps_host()

const HostRecord * app::apps_host

(

const ClientState &

state

)

Return the host currently shown by the Apps screen.

Parameters

state

App state containing the selected host.

Returns

Host record backing the apps page, or nullptr when unavailable.

begin_selected_host_app_browse()

bool app::begin_selected_host_app_browse	(	ClientState &	state,
		bool	showHiddenApps )

Enter the apps screen for the currently selected host after authorization has been refreshed.

Parameters

state	Mutable app state.
showHiddenApps	Whether hidden apps should still be shown.

Returns

true when the apps page was entered.

create_initial_state()

ClientState app::create_initial_state

(

)

Create the initial app state shown after startup.

Returns

The initial client state.

current_add_host_address()

std::string app::current_add_host_address

(

const ClientState &

state

)

Return the current host address shown in the add-host flow.

Parameters

state

App state containing the add-host draft.

Returns

Current draft IPv4 address text.

current_add_host_port()

uint16_t app::current_add_host_port

(

const ClientState &

state

)

Return the effective TCP port for the current add-host draft.

Parameters

state

App state containing the add-host draft.

Returns

Effective host port using the default when the field is empty.

current_pairing_pin()

std::string app::current_pairing_pin

(

const ClientState &

state

)

Return the current pairing PIN shown in the pairing flow.

Parameters

state

App state containing the pairing draft.

Returns

Four-digit PIN string.

find_app_list_result_host()

HostRecord * app::find_app_list_result_host	(	ClientState &	state,
		const std::string &	address,
		uint16_t	port )

Finds the host that should receive an app-list refresh result.

Parameters

state	Client state that owns saved and active hosts.
address	Address reported by the background task.
port	Port reported by the background task.

Returns

Pointer to the matching host, or null when no host matches.

handle_add_host_keypad_command()

bool app::handle_add_host_keypad_command	(	ClientState &	state,
		input::UiCommand	command )

Handles commands while the add-host keypad modal is visible.

Parameters

state	Client state containing the keypad draft.
command	Command being processed.

Returns

True when the command was consumed by the keypad.

handle_add_host_menu_activation()

void app::handle_add_host_menu_activation	(	ClientState &	state,
		std::string_view	activatedItemId,
		AppUpdate *	update )

Handles activation of add-host screen menu actions.

Parameters

state	Client state containing the add-host draft.
activatedItemId	Activated menu item identifier.
update	Update structure that receives side effects.

handle_apps_screen_command()

bool app::handle_apps_screen_command	(	ClientState &	state,
		input::UiCommand	command,
		AppUpdate *	update )

Handles commands on the apps screen.

Parameters

state	Client state containing the apps selection.
command	Command being processed.
update	Update structure that receives side effects.

Returns

True when the apps screen consumed the command.

handle_command()

AppUpdate app::handle_command	(	ClientState &	state,
		input::UiCommand	command )

Apply a UI command to the client shell.

Parameters

state	Mutable app state.
command	UI command from controller or keyboard input.

Returns

Summary of the resulting state transition.

handle_hosts_screen_command()

bool app::handle_hosts_screen_command	(	ClientState &	state,
		input::UiCommand	command,
		AppUpdate *	update )

Handles commands on the hosts screen.

Parameters

state	Client state containing the hosts screen selection.
command	Command being processed.
update	Update structure that receives side effects.

Returns

True when the hosts screen consumed the command.

handle_overlay_command()

bool app::handle_overlay_command	(	ClientState &	state,
		input::UiCommand	command,
		AppUpdate *	update )

Handles overlay toggle and scrolling commands.

Parameters

state	Client state containing the overlay state.
command	Command being processed.
update	Update structure that receives overlay changes.

Returns

True when the command was consumed by the overlay.

handle_settings_detail_activation()

void app::handle_settings_detail_activation	(	ClientState &	state,
		const ui::MenuUpdate &	detailUpdate,
		AppUpdate *	update )

Handles activation of a settings detail row.

Parameters

state	Client state containing the settings menus.
detailUpdate	Activated detail-menu update.
update	Update structure that receives side effects.

handle_settings_screen_command()

bool app::handle_settings_screen_command	(	ClientState &	state,
		input::UiCommand	command,
		AppUpdate *	update )

Handles commands on the settings screen.

Parameters

state	Client state containing the settings menus.
command	Command being processed.
update	Update structure that receives side effects.

Returns

True when the settings screen consumed the command.

host_requires_manual_pairing()

bool app::host_requires_manual_pairing	(	const ClientState &	state,
		const std::string &	address,
		uint16_t	port )

Return whether a saved host still requires a manual pairing flow.

Parameters

state	App state containing the saved host list.
address	Host address to inspect.
port	Host port to inspect.

Returns

true when the matching host exists and is not paired.

mark_cover_art_cached()

void app::mark_cover_art_cached	(	ClientState &	state,
		const std::string &	address,
		uint16_t	port,
		int	appId )

Mark one cached cover-art entry as available for a host app.

Parameters

state	Mutable app state.
address	Host address owning the app.
port	Host port owning the app.
appId	App identifier whose cached art is now available.

merge_discovered_host()

bool app::merge_discovered_host	(	ClientState &	state,
		std::string	displayName,
		const std::string &	address,
		uint16_t	port )

Add or refresh one auto-discovered host in the current host list.

Discovery results are normalized to the same saved-host conventions used by manual host entry. When a matching host already exists, transient runtime fields such as reachability are refreshed without overwriting a custom saved name. When no host matches, a new host record is appended and marked dirty so it can be persisted.

Parameters

state	Mutable app state.
displayName	Discovered host name, or an empty string to use the default label.
address	Discovered IPv4 address.
port	Discovered host HTTP port.

Returns

true when persisted host metadata changed or a new host was added.

merge_host_app_records()

std::vector< HostAppRecord > app::merge_host_app_records	(	const HostRecord &	host,
		std::vector< HostAppRecord >	apps )

Merges saved app metadata into a freshly fetched app list.

Parameters

host	Host providing persisted per-app metadata.
apps	Freshly fetched apps to merge.

Returns

Merged app records ready to persist.

replace_hosts()

void app::replace_hosts	(	ClientState &	state,
		std::vector< HostRecord >	hosts,
		std::string	statusMessage = {} )

Replace the in-memory host list from a persisted snapshot.

Parameters

state	Mutable app state.
hosts	Loaded host records.
statusMessage	Optional status line shown in the shell.

replace_saved_files()

void app::replace_saved_files	(	ClientState &	state,
		std::vector< startup::SavedFileEntry >	savedFiles )

Replace the in-memory saved-file inventory shown on the settings page.

Parameters

state	Mutable app state.
savedFiles	Saved files currently found on disk.

restore_selected_app_after_refresh()

void app::restore_selected_app_after_refresh	(	ClientState &	state,
		const HostRecord &	host,
		int	selectedAppId )

Restores the previously selected app after a successful refresh.

Parameters

state	Client state whose selected app should be restored.
host	Host containing the refreshed app list.
selectedAppId	App ID that was selected before the refresh.

selected_app()

const HostAppRecord * app::selected_app

(

const ClientState &

state

)

Return the currently selected app on the Apps screen.

Parameters

state

App state containing the selected host and apps list.

Returns

Selected app record, or nullptr when no visible app is selected.

selected_app_id_for_restore()

int app::selected_app_id_for_restore

(

const ClientState &

state

)

Returns the selected app identifier so it can be restored after a refresh.

Parameters

state

Client state whose selected app should be preserved.

Returns

The selected app ID, or zero when no app is selected.

selected_host()

const HostRecord * app::selected_host

(

const ClientState &

state

)

Return the currently selected loaded host for the active screen.

On the hosts page this returns the selected saved host tile. On host-specific pages such as pairing it may return the lightweight active host snapshot.

Parameters

state

App state containing the loaded host selection.

Returns

Selected host record, or nullptr when no saved host is selected.

set_log_file_path()

void app::set_log_file_path	(	ClientState &	state,
		std::string	logFilePath )

Update the log file path tracked by the shell.

Parameters

state	Mutable app state.
logFilePath	Path to the log file that should be shown in the viewer.

to_string()

const char * app::to_string

(

ScreenId

screen

)

Return a display label for a screen identifier.

Parameters

screen

Screen identifier to stringify.

Returns

Stable lowercase screen name.