- Introduction
- Configuration
- C++ Implementation
- Build Instructions
- Deployment and Updates
- Usage
- Simplified Version without Update Checking
#Introduction
This document outlines the process of creating a browser launcher, a wrapper executable designed to launch a web browser with predefined settings, including permanently integrated command-line flags. This approach offers several benefits, such as centralized configuration management, persistent flag integration without modifying the original browser executable, and the ability to manage multiple browser configurations from a single point. The launcher is particularly useful for users who frequently use specific browser flags or need to manage different browser profiles for various tasks.
#Configuration
The browser launcher utilizes a configuration file named browser_config.ini
to manage browser settings and launch parameters. This file is divided into sections:
[Browser]
Section:Executable
: Specifies the path to the browser executable (e.g.,G:\05-portable\IronPortable64\Iron\chrome.exe
).VersionUrl
: Provides a URL for checking updates. For example, for Thorium, you might usehttps://api.github.com/repos/Alex313031/Thorium-Win/releases/latest
. The launcher fetches the latest version information from this URL and compares it with the current browser version.Flags
: Contains custom command-line flags to be passed to the browser:
[General]
Section:UpdateCheck
: A boolean value (true
orfalse
) that determines whether the launcher should check for updates.
Multiple [Browser]
sections (e.g., [Browser2]
, [Browser3]
) can be added to define settings for different browsers. The launcher can handle multiple [Browser]
sections, and the user can select a specific browser using the --browser=
command-line argument followed by the number of the browser section (e.g., --browser=2
to use [Browser2]
).
Example browser_config.ini
:
An alternative configuration method using browser.conf
and browser_flags.conf
is also available, where browser.conf
specifies the browser executable and user data directory, and browser_flags.conf
contains additional flags. However, the browser_config.ini
approach is recommended for its flexibility and ability to manage multiple browsers.
#C++ Implementation
The core functionality of the browser launcher is implemented in C++. The following code provides a comprehensive example:
Key Features:
read_config_file
: Reads thebrowser_config.ini
file and parses the specified section, returning a vector of key-value pairs. It handles missing or invalid configuration files by logging an error and returning an empty vector. It also checks if the configuration section is empty or invalid after parsing.get_browser_version
: Retrieves the version of the specified browser executable using the Windows Version API. It handles cases where the version information cannot be retrieved or is invalid.check_for_updates
: Performs an update check by fetching the latest version from the specifiedVersionUrl
(if provided) and comparing it with the current version. It uses WinHTTP for making HTTP requests and includes error handling for various stages of the process, such as network issues, URL parsing, and JSON parsing.sanitize_command
: Sanitizes command-line arguments by removing potentially dangerous characters that could be used for command injection, such as&
,|
,;
,`
,$
,<
,>
,^
,(
,)
,[
,]
,{
,}
.WinMain
: The main entry point of the application. It performs the following actions:- Sets the error mode to prevent error dialogs from appearing.
- Gets the current working directory.
- Determines the browser section to use based on command-line arguments (if provided) using the
--browser=
argument. - Reads the configuration from
browser_config.ini
. - Validates the browser path, logging an error and exiting if the path is invalid or the executable is not found.
- Retrieves and displays the browser version.
- Performs an update check if enabled.
- Constructs the final command line by combining the browser path, flags, and user-provided arguments.
- Appends sanitized user-provided arguments to the command line.
- Checks for command-line length, logging an error and exiting if the command line is too long.
- Creates a new process to launch the browser using
CreateProcessA
, logging an error and exiting if the process creation fails. - Closes the process and thread handles.
- Includes exception handling to catch and log any exceptions that occur during the process.
#Build Instructions
To build the browser launcher, you’ll need a C++ compiler that supports Windows development, such as MinGW or Visual Studio.
- Using Visual Studio:
- Open the Visual Studio Developer Command Prompt.
- Navigate to the directory where you saved the C++ code (e.g.,
browser_launcher.cpp
). -
Compile using the following command:
- Using MinGW:
- Open the MinGW command prompt.
- Navigate to the directory where you saved the C++ code.
-
Compile using the following command:
#Deployment and Updates
After building the launcher, you can deploy it by placing the executable (browser_launcher.exe
) and the browser_config.ini
file in the desired location. To update the browser, you can use the following script:
This script assumes that the new browser executable is named .exe.new
and the wrapper executable is named wrapper.exe
. It renames the existing browser executable, moves the new executable into place, and copies the wrapper executable over the original browser executable. You may need to modify this script based on your specific browser and directory structure. For example, for Iron Portable, the script would be:
Update Process:
- The launcher checks for updates if
UpdateCheck
is set totrue
in the[General]
section ofbrowser_config.ini
and aVersionUrl
is provided in the[Browser]
section. - The
check_for_updates
function fetches the latest version information from theVersionUrl
using WinHTTP. - It parses the JSON response (assuming the response is in JSON format) to extract the latest version number.
- It compares the latest version with the current browser version.
- If a newer version is available, it notifies the user.
- The actual download and installation of the new version are not handled by the launcher and would typically be performed manually or through a separate update mechanism.
Error Handling:
The launcher includes error handling for various scenarios:
- Missing or Invalid Configuration File: If
browser_config.ini
is missing or cannot be opened, the launcher logs an error and terminates. If a specific section is missing or invalid, it logs an error and uses default values or terminates, depending on the criticality of the missing information. - Missing Browser Executable: If the specified browser executable is not found, the launcher logs an error and terminates.
- Failed Update Check: If the update check fails (e.g., due to network issues or invalid URL), the launcher logs an error and continues launching the browser with the existing version.
- Failed Version Retrieval: If the launcher cannot retrieve the browser version, it logs an error and uses a default version or terminates, depending on whether the version information is critical.
- Command-line Arguments Too Long: If the combined length of the command line exceeds the maximum allowed length, the launcher logs an error, truncates the arguments, or terminates.
- Failed Process Creation: If the launcher fails to create a new process for the browser, it logs an error and terminates.
- Log File Error: If the launcher cannot open the log file, it logs an error to the standard error stream.
#Usage
To use the launcher:
- Modify Configuration: Edit
browser_config.ini
to specify the browser executable, flags, and update settings for each browser you want to manage. - Run Launcher: Execute
browser_launcher.exe
to start the browser with custom configurations. - Additional Arguments: Pass extra command-line arguments; they are sanitized and forwarded to the browser.
-
Select Browser Configuration: Use the
--browser=
argument to choose a specific browser configuration:This selects the
[Browser2]
section from the configuration file. - Update Checks: Ensure
UpdateCheck=true
in the[General]
section to enable update checking. Provide a validVersionUrl
in the browser section for update verification.
#Simplified Version without Update Checking
If you don’t need the update checking functionality, you can use a simplified version of the C++ code without the check_for_updates
function and the related code in WinMain
. This will reduce the complexity of the launcher and remove the dependency on the WinHTTP
library. You can remove the VersionUrl
parameter from the configuration file in this case.
Here’s the simplified C++ code without the update checking functionality:
Building the Simplified Version:
The build instructions for the simplified version are the same as for the full version, except that you don’t need to link the winhttp.lib
library.
Using Visual Studio:
Using MinGW: