py_canoe.core.application.Application

def attach_to_active_application(self) -> bool:
    """Attach to an already running CANoe application instance."""
    try:
        self._launch_application()
        if self.com_object:
            logger.info("Successfully attached to active CANoe application ")
            self._setup_post_configuration_loading()
            return True
        else:
            logger.error("Failed to attach to active CANoe application")
            return False
    except Exception as e:
        logger.error(f"Error attaching to active CANoe application: {e}")
        return False

def bus(self, bus_type: BusType = BusType.CAN) -> Bus:
    """Returns a Bus object for the given bus type.

    This mirrors the COM Application.Bus([type]) property. The Bus wrapper is
    stateless (it only wraps the COM Bus object), so a fresh wrapper is
    created on each call.

    Args:
        bus_type: The bus type as a BusType enum member. Defaults to BusType.CAN.
    """
    return Bus(self.com_object.GetBus(bus_type.name))

def new(self, auto_save: bool = False, prompt_user: bool = False, timeout: int = 5) -> bool:
    """Create a new empty CANoe configuration."""
    self._launch_application()
    status = False
    try:
        logger.info("Opening new empty CANoe configuration...")
        self.com_object.New(auto_save, prompt_user)
        if self._enable_events:
            cond = lambda: self.application_events.OPENED
        else:
            cond = lambda: self.com_object.FullName != ""
        status = DoEventsUntil(cond, timeout, "New CANoe configuration")
        if status:
            logger.info("New empty CANoe configuration Opened")
            self._setup_post_configuration_loading()
        return status
    except Exception as e:
        logger.error(f"Error creating new configuration: {e}")
        status = False
        return status

def new_configuration_from_yaml(self, configuration_path: str, path_to_yaml_folder: str, scenario_name: str = "") -> None:
    """Creates a new configuration from an existing venvironment.yaml or venvironment-basic.yaml.

    Args:
        configuration_path: The path where the new configuration should be
            located including the configuration name.
        path_to_yaml_folder: The path to the directory which contains the YAML file.
        scenario_name: The scenario for which a configuration should be created.
    """
    self.com_object.NewConfigurationFromYaml(configuration_path, path_to_yaml_folder, scenario_name)

def open(self, canoe_cfg: str | Path, visible: bool = True, auto_save: bool = True, prompt_user: bool = False, timeout: int = 5) -> bool:
    """Open a CANoe configuration file (.cfg) in a new or existing CANoe instance."""
    self._launch_application()
    status = False
    try:
        self.visible = visible
        logger.info("Opening CANoe configuration ...")
        canoe_cfg_str = str(Path(canoe_cfg).resolve())
        self.com_object.Open(canoe_cfg_str, auto_save, prompt_user)
        if self._enable_events:
            cond = lambda: self.application_events.OPENED
        else:
            cond = lambda: self.com_object.FullName.lower() == canoe_cfg_str.lower()
        status = DoEventsUntil(cond, timeout, "Open CANoe configuration")
        if status:
            logger.info(f"CANoe Configuration {canoe_cfg} Opened")
            self._setup_post_configuration_loading()
        return status
    except Exception as e:
        logger.error(f"Error opening configuration: {e}")
        status = False
        return status

def open_config(self, canoe_cfg: str | Path, auto_save: bool = True, prompt_user: bool = False, timeout: int = 60) -> bool:
    """Switch to a different CANoe configuration without restarting CANoe.

    This method switches configurations in an already-running CANoe instance.
    Use this when CANoe is already running and you want to load a different .cfg file.

    For starting CANoe with a configuration from scratch, use open() instead.

    Args:
        canoe_cfg: Path to the CANoe configuration (.cfg) file.
        auto_save: If True, automatically save the current configuration before switching.
        prompt_user: If True, prompt user for confirmation before switching.
        timeout: Maximum time to wait for configuration to load (seconds).

    Returns:
        True if configuration was successfully loaded, False otherwise.
    """
    import time as _time
    status = False
    try:
        abs_path = str(Path(canoe_cfg).resolve())
        logger.info(f"Switching to CANoe configuration: {abs_path}")

        # Reset OPENED flag before calling Open
        self.application_events.OPENED = False

        # Call COM Open() to switch configuration
        self.com_object.Open(abs_path, auto_save, prompt_user)

        if self._enable_events:
            status = DoEventsUntil(
                lambda: self.application_events.OPENED and self.configuration.full_name.lower() == abs_path.lower(),
                timeout,
                f"Switch to configuration {canoe_cfg}"
            )
        else:
            # Poll FullName without PumpWaitingMessages
            poll_deadline = _time.monotonic() + timeout
            while _time.monotonic() < poll_deadline:
                try:
                    if self.configuration.full_name.lower() == abs_path.lower():
                        status = True
                        break
                except Exception:
                    pass
                _time.sleep(0.2)

        if status:
            logger.info(f"Configuration switched successfully to {canoe_cfg}")
            self._setup_post_configuration_loading()
        else:
            logger.warning(f"Configuration switch timed out after {timeout}s")

        return status
    except Exception as e:
        logger.error(f"Error switching configuration: {e}")
        return False

def pump_messages(self) -> None:
    """Pump COM messages to prevent blocking.

    This is a thin wrapper around pythoncom.PumpWaitingMessages().
    Use this in custom wait loops to keep COM responsive.

    Example:
        >>> while not ready():
        >>>     app.pump_messages()
        >>>     time.sleep(0.1)
    """
    pythoncom.PumpWaitingMessages()

def quit(self, timeout: int = 5) -> bool:
    """Quit the CANoe application gracefully."""
    status = False
    try:
        if self._configuration is not None and self.configuration.modified:
            self.configuration.modified = False
        # Do NOT release event sinks before Quit(). CANoe fires OnExit (and
        # potentially OnStop) as part of its internal shutdown sequence after
        # Quit() is called. Releasing sinks beforehand leaves CANoe with a
        # dangling vtable pointer → access violation → crash dialog.
        # Sinks are released in the finally block after CANoe has shut down.
        self.com_object.Quit()
        status = DoEventsUntil(lambda: self.application_events.QUIT, timeout, "Quit CANoe application")
        if status:
            logger.info("CANoe Application Quit Successfully.")
        return status
    except Exception as e:
        logger.error(f"Error during CANoe quit: {e}")
        status = False
        return status
    finally:
        self._release_event_sinks()