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

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

Discovery mode entry point for unified binary.

Handles session discovery, host negotiation, and media flow.

Returns: 0 on success, non-zero error code on failure

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

                         {
  log_debug("discovery_main() starting");
 
  // Discovery-specific setup: initialize ACDS connection and session negotiation
  // Note: Shared setup (keepawake, splash, terminal, capture, display, audio)
  // is handled by session_client_like_run()
 
  // Get session string from options (command-line argument)
  const char *session_string = GET_OPTION(session_string);
  bool is_initiator = (session_string == NULL || session_string[0] == '\0');
 
  int port_int = GET_OPTION(port);
 
  log_debug("Discovery: is_initiator=%d, port=%d", is_initiator, port_int);
 
  // Validate mutually exclusive options: discovery_service_url vs discovery_port
  const char *service_url = GET_OPTION(discovery_service_url);
  if (service_url && service_url[0] != '\0') {
    int discovery_port = GET_OPTION(discovery_port);
    if (discovery_port != ACIP_DISCOVERY_DEFAULT_PORT) {
      log_fatal("--discovery-service-url and --discovery-service-port are mutually exclusive");
      return ERROR_USAGE;
    }
  }
 
  // Create discovery session configuration
  discovery_config_t discovery_config = {
      .acds_address = GET_OPTION(discovery_server),
      .acds_port = (uint16_t)GET_OPTION(discovery_port),
      .acds_url = service_url,
      .session_string = is_initiator ? NULL : session_string,
      .password = GET_OPTION(password),
      .local_port = (uint16_t)port_int,
      .on_state_change = on_discovery_state_change,
      .on_session_ready = on_session_ready,
      .on_error = on_discovery_error,
      .callback_user_data = NULL,
      .should_exit_callback = discovery_capture_should_exit_adapter,
      .exit_callback_data = NULL,
  };
 
  // Create discovery session (stored in global for discovery_run() to access)
  g_discovery = discovery_session_create(&discovery_config);
  if (!g_discovery) {
    log_fatal("Failed to create discovery session");
    return ERROR_MEMORY;
  }
 
  // Start discovery session (connects to ACDS, creates/joins, initiates NAT negotiation)
  log_debug("Discovery: starting discovery session");
  asciichat_error_t result = discovery_session_start(g_discovery);
  if (result != ASCIICHAT_OK) {
    log_fatal("Failed to start discovery session: %d", result);
    discovery_session_destroy(g_discovery);
    g_discovery = NULL;
    return result;
  }
 
  // No network interrupt callback needed - discovery session handles its own shutdown
  set_interrupt_callback(NULL);
 
  /* ========================================================================
   * Configure and Run Shared Client-Like Session Framework
   * ========================================================================
   * session_client_like_run() handles all shared initialization:
   * - Terminal output management
   * - Keepawake system
   * - Splash screen lifecycle
   * - Media source selection
   * - FPS probing
   * - Audio initialization
   * - Display context creation
   * - Proper cleanup ordering
   *
   * Discovery mode provides:
   * - discovery_run() callback: NAT negotiation, role determination, media handling
   * - discovery_keyboard_handler: interactive controls for participant role
   */
 
  session_client_like_config_t config = {
      .run_fn = discovery_run,
      .run_user_data = NULL,
      .kind = SESSION_CLIENT_LIKE_KIND_DISCOVERY,
      .discovery = (void *)g_discovery, // Opaque pointer to discovery session
      .custom_should_exit = NULL,
      .exit_user_data = NULL,
      .keyboard_handler = discovery_keyboard_handler,
      .max_reconnect_attempts = 0, // Discovery doesn't retry - role is determined once
      .should_reconnect_callback = NULL,
      .reconnect_user_data = NULL,
      .reconnect_delay_ms = 0,
      .print_newline_on_tty_exit = false, // Server/participant manages cursor
  };
 
  log_debug("Discovery: calling session_client_like_run()");
  asciichat_error_t session_result = session_client_like_run(&config);
  log_debug("Discovery: session_client_like_run() returned %d", session_result);
 
  // Cleanup discovery session
  log_debug("Discovery: cleaning up");
 
  if (g_discovery) {
    discovery_session_stop(g_discovery);
    discovery_session_destroy(g_discovery);
    g_discovery = NULL;
  }
 
  return (session_result == ASCIICHAT_OK) ? 0 : (int)session_result;
}