System Windows Core Documentation

Provides Windows-specific implementations for system process and service management.

This module offers functionalities tailored for the Windows operating system, primarily focused on managing Bedrock server processes both in the foreground and as background Windows Services. It leverages the pywin32 package for many of its operations, and its availability is checked by the PYWIN32_AVAILABLE flag. Some optional pywin32 modules for cleanup are checked via PYWIN32_HAS_OPTIONAL_MODULES.

Key functionalities include:

Foreground Process Management:

Starting a Bedrock server directly in the foreground with IPC capabilities (_windows_start_server()).

Sending commands to this foreground server via a named pipe (_windows_send_command()).

Stopping the foreground server process using its PID (_windows_stop_server_by_pid()).

Internal mechanisms for named pipe server creation, client handling, and OS signal management for graceful shutdowns.

Windows Service Management (Requires Administrator Privileges):

Checking if a service exists (check_service_exists()).

Creating or updating a Windows Service to run the Bedrock server (create_windows_service()).

Enabling (enable_windows_service()) or disabling (disable_windows_service()) a service.

Deleting a service, including cleanup of associated registry entries like performance counters and event log sources (delete_windows_service()).

The module defines constants like BEDROCK_EXECUTABLE_NAME and PIPE_NAME_TEMPLATE, and uses global variables such as managed_bedrock_servers and _foreground_server_shutdown_event to manage the state of servers started directly.

Note

Functions interacting with the Windows Service Control Manager (SCM) typically require Administrator privileges to execute successfully. The module attempts to handle PermissionsError where appropriate.

bedrock_server_manager.core.system.windows.check_service_exists(service_name: str) → bool

Checks if a Windows service with the given name exists.

Requires Administrator privileges for a definitive check, otherwise, it might return False due to access denied errors.

Parameters:

service_name (str) – The short name of the service to check (e.g., “MyBedrockServer”).

Returns:

True if the service exists, False otherwise. Returns False if pywin32 is not installed or if access is denied (which is logged as a warning).

Return type:

bool

Raises:

MissingArgumentError – If service_name is empty.
SystemError – For unexpected Service Control Manager (SCM) errors other than “service does not exist” or “access denied”.

bedrock_server_manager.core.system.windows.create_windows_service(service_name: str, display_name: str, description: str, command: str) → None

Creates a new Windows service or updates an existing one.

This function interacts with the Windows Service Control Manager (SCM) to either create a new service or modify the configuration of an existing service (specifically its display name, description, and executable command). The service is configured for automatic start (SERVICE_AUTO_START) and runs as LocalSystem by default upon creation.

Requires Administrator privileges.

Parameters:

service_name (str) – The short, unique name for the service (e.g., “MyBedrockServerSvc”).
display_name (str) – The user-friendly name shown in the Services console (e.g., “My Bedrock Server”).
description (str) – A detailed description of the service.
command (str) – The full command line to execute for the service, including the path to the executable and any arguments. Example: "C:\path\to\python.exe C:\path\to\script.py --run-as-service"

Raises:

SystemError – If pywin32 is not available, or for other unexpected SCM errors during service creation/update.
MissingArgumentError – If any of the required string arguments (service_name, display_name, description, command) are empty.
PermissionsError – If the operation fails due to insufficient privileges (typically requires Administrator rights).

bedrock_server_manager.core.system.windows.delete_windows_service(service_name: str) → None

Deletes a Windows service and performs associated cleanup.

This function interacts with the Windows Service Control Manager (SCM) to delete the specified service. It also attempts to perform cleanup operations such as unloading performance counters and removing event log sources from the registry, provided that optional pywin32 modules (like perfmon and win32evtlogutil) are available (checked by PYWIN32_HAS_OPTIONAL_MODULES).

The service should ideally be stopped before deletion, though this function does not explicitly stop it. If the service does not exist or is already marked for deletion, warnings are logged, and the function may proceed with cleanup or return gracefully.

Requires Administrator privileges.

Parameters:

service_name (str) – The short name of the service to delete.

Raises:

SystemError – If pywin32 is not available or for critical SCM errors during deletion (e.g., service cannot be deleted for reasons other than access denied, not existing, or already marked for deletion).
MissingArgumentError – If service_name is empty.
PermissionsError – If the operation fails due to insufficient privileges.

bedrock_server_manager.core.system.windows.disable_windows_service(service_name: str) → None

Disables a Windows service by setting its start type to ‘Disabled’.

This function interacts with the Windows Service Control Manager (SCM) to change the start type of the specified service to SERVICE_DISABLED. If the service does not exist, a warning is logged, and the function returns gracefully.

Requires Administrator privileges.

Parameters:

service_name (str) – The short name of the service to disable.

Raises:

SystemError – If pywin32 is not available or for unexpected SCM errors (other than service not existing).
MissingArgumentError – If service_name is empty.
PermissionsError – If the operation fails due to insufficient privileges.

bedrock_server_manager.core.system.windows.enable_windows_service(service_name: str) → None

Enables a Windows service by setting its start type to ‘Automatic’.

This function interacts with the Windows Service Control Manager (SCM) to change the start type of the specified service to SERVICE_AUTO_START.

Requires Administrator privileges.

Parameters:

service_name (str) – The short name of the service to enable.

Raises:

SystemError – If pywin32 is not available, if the service does not exist, or for other unexpected SCM errors.
MissingArgumentError – If service_name is empty.
PermissionsError – If the operation fails due to insufficient privileges.

bedrock_server_manager.core.system.windows.managed_bedrock_servers: Dict[str, Dict[str, Any]] = {}: A global dictionary to keep track of running foreground server processes and their associated objects (like the Popen instance, pipe listener thread). Structure: {'server_name': {'process': Popen, 'pipe_thread': Thread, ...}} This is primarily used by _windows_start_server and its helper threads.