ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
main.h File Reference

ascii-chat Discovery Mode Entry Point Header More...

Go to the source code of this file.

Functions

int discovery_main (void)
 Discovery mode entry point for unified binary.

Detailed Description

ascii-chat Discovery Mode Entry Point Header

This header exposes the discovery mode entry point for the unified binary architecture. The unified binary dispatches to discovery_main() when invoked as ascii-chat discovery.

Discovery Mode Philosophy

"ascii-chat should be as simple as making a phone call."

Discovery mode enables zero-configuration video chat:

  • One command to start: ascii-chat swift-river-mountain
  • Automatic host negotiation: Best NAT quality participant becomes host
  • Dynamic role switching: Participants can become hosts mid-session
  • Seamless failover: If host disconnects, another participant takes over

Mode Entry Point Contract

Each mode entry point (server_main, client_main, discovery_main) must:

  • Accept no arguments: int mode_main(void)
  • Options are already parsed by main dispatcher (available via GET_OPTION())
  • Return 0 on success, non-zero error code on failure
  • Perform mode-specific initialization and main loop
  • Perform complete cleanup before returning

Implementation Notes

Discovery mode combines client and server capabilities:

  • Uses session library (lib/session/) for capture, display, hosting
  • Connects to ACDS for session discovery and NAT quality assessment
  • Can transition between participant and host roles dynamically
Author
Zachary Fogg me@zf.nosp@m.o.gg
Date
January 2026
Version
1.0

Definition in file discovery/main.h.

Function Documentation

◆ discovery_main()

int discovery_main ( void )

Discovery mode entry point for unified binary.

This function implements the complete discovery mode lifecycle:

  • Session discovery via ACDS or LAN mDNS
  • NAT quality assessment for host selection
  • Dynamic role switching (participant <-> host)
  • Media streaming (video/audio capture and display)
  • Graceful shutdown and cleanup

Options are already parsed by the main dispatcher before this function is called, so they are available via GET_OPTION().

Returns
0 on success, non-zero error code on failure
Example
# Join a session (session string as positional argument):
ascii-chat discovery swift-river-mountain
# Or more concisely (session strings are auto-detected):
ascii-chat swift-river-mountain

Run discovery mode using the shared splash, media, and terminal lifecycle.

Definition at line 840 of file discovery/main.c.

840 {
841
842 // Discovery-specific setup: initialize ACDS connection and session negotiation
843 // Note: Shared setup (keepawake, splash, terminal, capture, display, audio)
844 // is handled by session_client_like_run()
845
846 // Get session string from options (command-line argument)
847 const char *session_string = GET_OPTION(session_string);
848 bool is_initiator = (session_string == NULL || session_string[0] == '\0');
849
850 int port_int = GET_OPTION(port);
851
852 log_debug("Discovery: is_initiator=%d, port=%d", is_initiator, port_int);
853
854 char service_url_override[URL_BUFFER_SIZE];
855 const char *service_url = GET_OPTION(discovery_server);
856 if (GET_OPTION(discovery_port) != ACIP_DISCOVERY_DEFAULT_PORT) {
857 asciichat_error_t override_result = connection_endpoint_override_port(service_url, (uint16_t)GET_OPTION(discovery_port), service_url_override, sizeof(service_url_override));
858 if (override_result != ASCIICHAT_OK) {
859 log_fatal("Invalid --discovery-service URL for --discovery-service-port override");
860 return ERROR_USAGE;
861 }
862 service_url = service_url_override;
863 }
864
865 discovery_ui_state_t ui = {0};
866 asciichat_error_t ui_result = mutex_init(&ui.mutex, "discovery_ui");
867 if (ui_result != ASCIICHAT_OK)
868 return ui_result;
869
870 // Create discovery session configuration
871 discovery_config_t discovery_config = {
872 .acds_address = NULL,
873 .acds_port = ACIP_DISCOVERY_DEFAULT_PORT,
874 .acds_url = service_url,
875 .session_string = is_initiator ? NULL : session_string,
876 .password = GET_OPTION(password),
877 .local_port = (uint16_t)port_int,
878 .on_state_change = on_discovery_state_change,
879 .on_session_ready = on_session_ready,
880 .on_error = on_discovery_error,
881 .callback_user_data = &ui,
882 .should_exit_callback = discovery_capture_should_exit_adapter,
883 .exit_callback_data = NULL,
884 };
885
886 acip_websocket_runtime_t *websocket_runtime = NULL;
887 if (service_url && (strncmp(service_url, "ws://", 5) == 0 || strncmp(service_url, "wss://", 6) == 0)) {
888 asciichat_error_t runtime_result = acip_websocket_runtime_create(&websocket_runtime);
889 if (runtime_result != ASCIICHAT_OK) {
890 mutex_destroy(&ui.mutex);
891 return runtime_result;
892 }
893 }
894
895 // Create discovery session (stored in global for discovery_run() to access)
896 g_discovery = discovery_session_create(&discovery_config);
897 if (!g_discovery) {
898 mutex_destroy(&ui.mutex);
899 acip_websocket_runtime_destroy(&websocket_runtime);
900 log_fatal("Failed to create discovery session");
901 return ERROR_MEMORY;
902 }
903
904 splash_set_discovery_session(session_string, !is_initiator);
905
906 // No network interrupt callback needed - discovery session handles its own shutdown
908
909 /* ========================================================================
910 * Configure and Run Shared Client-Like Session Framework
911 * ========================================================================
912 * session_client_like_run() handles all shared initialization:
913 * - Terminal output management
914 * - Keepawake system
915 * - Splash screen lifecycle
916 * - Media source selection
917 * - FPS probing
918 * - Audio initialization
919 * - Display context creation
920 * - Proper cleanup ordering
921 *
922 * Discovery mode provides:
923 * - discovery_run() callback: NAT negotiation, role determination, media handling
924 * - discovery_keyboard_handler: interactive controls for participant role
925 */
926
928 .run_fn = discovery_run,
929 .prepare_fn = discovery_prepare,
930 .run_user_data = NULL,
932 .discovery = (void *)g_discovery, // Opaque pointer to discovery session
933 .custom_should_exit = NULL,
934 .exit_user_data = NULL,
935 .keyboard_handler = discovery_keyboard_handler,
936 .max_reconnect_attempts = 0, // Discovery doesn't retry - role is determined once
937 .should_reconnect_callback = NULL,
938 .reconnect_user_data = NULL,
939 .reconnect_delay_ms = 0,
940 .print_newline_on_tty_exit = false, // Server/participant manages cursor
941 };
942
943 log_debug("Discovery: calling session_client_like_run()");
944 asciichat_error_t session_result = session_client_like_run(&config);
945 log_debug("Discovery: session_client_like_run() returned %d", session_result);
946
947 // Cleanup discovery session
948 log_debug("Discovery: cleaning up");
949
950 if (g_discovery) {
951 discovery_session_stop(g_discovery);
952 while (discovery_session_destroy(g_discovery) != ASCIICHAT_OK) {
953 LOG_ERRNO_IF_SET("Waiting for discovery connection resources");
954 platform_sleep_ms(10);
955 }
956 g_discovery = NULL;
957 }
958
959 acip_websocket_runtime_destroy(&websocket_runtime);
961 char discovery_error[sizeof(ui.error)];
962 mutex_lock(&ui.mutex);
963 SAFE_STRNCPY(discovery_error, ui.error, sizeof(discovery_error));
964 asciichat_error_t discovery_error_code = ui.error_code;
965 mutex_unlock(&ui.mutex);
966
967 if (session_result != ASCIICHAT_OK || discovery_error[0]) {
969 NOTICE(WARNING, "DISCOVERY FAILED", "Discovery failed: %s", discovery_error[0] ? discovery_error : asciichat_error_format(NULL, session_result));
970 if (session_result == ASCIICHAT_OK)
971 session_result = discovery_error_code;
972 }
973 mutex_destroy(&ui.mutex);
974 return (session_result == ASCIICHAT_OK) ? 0 : (int)session_result;
975}
const char * asciichat_error_format(const char *message, asciichat_error_t code)
#define LOG_ERRNO_IF_SET(message)
asciichat_error_t session_client_like_run(const session_client_like_config_t *config)
struct session_client_like_config session_client_like_config_t
@ SESSION_CLIENT_LIKE_KIND_DISCOVERY
Definition client_like.h:66
asciichat_error_t connection_endpoint_override_port(const char *input, uint16_t port, char *output, size_t output_size)
unsigned short uint16_t
#define SAFE_STRNCPY(dst, src, size)
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
@ ERROR_MEMORY
Definition error_codes.h:55
@ ASCIICHAT_OK
Definition error_codes.h:50
@ ERROR_USAGE
Definition error_codes.h:52
#define URL_BUFFER_SIZE
#define log_fatal(...)
Log a FATAL message.
Definition log/log.h:640
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
void log_set_terminal_output(bool enabled)
Control stderr output to terminal.
#define ACIP_DISCOVERY_DEFAULT_PORT
Discovery server default port (use OPT_ACDS_PORT_INT_DEFAULT from options.h).
Definition acds.h:1102
#define GET_OPTION(field)
Definition options.h:1333
struct acip_websocket_runtime acip_websocket_runtime_t
void set_interrupt_callback(void(*cb)(void))
Definition main.c:272
#define NOTICE(severity, title,...)
Definition notice.h:56
void splash_set_discovery_session(const char *session, bool joining)
Definition splash.c:95
void splash_clear_discovery_session(void)
Definition splash.c:105
void discovery_session_stop(discovery_session_t *session)
Stop the discovery session.
discovery_session_t * discovery_session_create(const discovery_config_t *config)
Configuration for discovery session.
asciichat_error_t discovery_session_destroy(discovery_session_t *session)
Destroy discovery session and free resources.
Configuration for discovery session.
This is the handoff point for discovery host audio capture. Callers fill host, audio,...
asciichat_error_t error_code
asciichat_error_t acip_websocket_runtime_create(acip_websocket_runtime_t **out)
void acip_websocket_runtime_destroy(acip_websocket_runtime_t **runtime)

References ACIP_DISCOVERY_DEFAULT_PORT, acip_websocket_runtime_create(), acip_websocket_runtime_destroy(), asciichat_error_format(), ASCIICHAT_OK, connection_endpoint_override_port(), discovery_session_create(), discovery_session_destroy(), discovery_session_stop(), discovery_ui_state_t::error, discovery_ui_state_t::error_code, ERROR_MEMORY, ERROR_USAGE, GET_OPTION, log_debug, LOG_ERRNO_IF_SET, log_fatal, log_set_terminal_output(), discovery_ui_state_t::mutex, NOTICE, SAFE_STRNCPY, SESSION_CLIENT_LIKE_KIND_DISCOVERY, session_client_like_run(), set_interrupt_callback(), splash_clear_discovery_session(), splash_set_discovery_session(), and URL_BUFFER_SIZE.