Skip to main content

quickgui_system/
lib.rs

1//! Bounded, cross-platform operating-system integrations independent of QuickGUI's renderer.
2
3mod app_environment;
4#[cfg(feature = "autostart")]
5mod autostart;
6#[cfg(feature = "crash-reporter")]
7mod crash;
8#[cfg(feature = "file-watcher")]
9mod file_watcher;
10#[cfg(feature = "file-watcher")]
11pub use file_watcher::{FileWatchEvent, FileWatcher, MAX_WATCH_EVENT_PATHS, MAX_WATCH_ROOTS};
12mod metrics;
13mod power;
14mod preferences;
15mod process;
16#[cfg(feature = "protocol")]
17mod protocol;
18#[cfg(feature = "secure-storage")]
19mod secure_storage;
20#[cfg(feature = "updater")]
21mod update;
22
23pub use app_environment::{
24    AppInfo, AppPaths, MAX_APP_IDENTIFIER_BYTES, MAX_APP_NAME_BYTES, MAX_APP_VERSION_BYTES,
25    MAX_PREFERRED_LANGUAGES, MAX_SYSTEM_LOCALE_BYTES, MAX_SYSTEM_LOCALES_TOTAL_BYTES,
26    MAX_SYSTEM_TEXT_BYTES, OperatingSystem, OperatingSystemFamily, SystemBitness, SystemInfo,
27};
28#[cfg(feature = "autostart")]
29pub use autostart::{AutoStart, AutoStartMode, AutoStartOptions};
30#[cfg(feature = "crash-reporter")]
31pub use crash::{
32    BacktracePolicy, CRASH_REPORT_SCHEMA_VERSION, CrashKind, CrashLocation, CrashReport,
33    CrashReporter, CrashReporterOptions, DEFAULT_MAX_CRASH_REPORT_BYTES, DEFAULT_MAX_CRASH_REPORTS,
34    DEFAULT_WATCHDOG_HANG_THRESHOLD, DEFAULT_WATCHDOG_INTERVAL, MAX_CRASH_BACKTRACE_BYTES,
35    MAX_CRASH_EXTRA_PARAMETERS, MAX_CRASH_MESSAGE_BYTES, MAX_CRASH_PARAMETER_KEY_BYTES,
36    MAX_CRASH_PARAMETER_VALUE_BYTES, MAX_CRASH_REPORT_BYTES, MAX_CRASH_REPORTS,
37    MAX_CRASH_UPLOAD_REPORTS, MAX_WATCHDOG_INTERVAL, MIN_WATCHDOG_INTERVAL, UploadSummary,
38    Watchdog, WatchdogOptions,
39};
40pub use metrics::{
41    CpuUsage, CpuUsageSampler, MAX_CPU_SAMPLE_INTERVAL, ProcessMetrics, SystemMemory,
42};
43pub use power::{
44    BatteryState, BatteryStatus, IdleState, MAX_IDLE_THRESHOLD, MAX_POWER_ASSERTION_REASON_BYTES,
45    PowerAssertion, PowerAssertionKind, PowerMonitor, PowerSource, PowerState, SessionState,
46    ThermalState,
47};
48pub use preferences::{
49    ColorScheme, PermissionKind, PermissionManager, PermissionStatus, SystemColor, SystemColorRole,
50    SystemPreferences,
51};
52pub use process::{
53    MAX_RELAUNCH_ARGUMENT_BYTES, MAX_RELAUNCH_ARGUMENTS, MAX_RELAUNCH_VALUE_BYTES, RelaunchOptions,
54    RelaunchRequest, RelaunchedProcess,
55};
56#[cfg(feature = "protocol")]
57pub use protocol::{ProtocolRegistration, ProtocolRegistrationOptions};
58#[cfg(feature = "secure-storage")]
59pub use secure_storage::SecureStorage;
60#[cfg(feature = "updater")]
61pub use update::{
62    AvailableUpdate, DEFAULT_MAX_EXPANDED_UPDATE_BYTES, DEFAULT_MAX_UPDATE_BYTES, InstalledUpdate,
63    MAX_UPDATE_ARCHIVE_ENTRIES, MAX_UPDATE_INSTALLER_ARGUMENT_BYTES,
64    MAX_UPDATE_INSTALLER_ARGUMENTS, MAX_UPDATE_MANIFEST_BYTES, MAX_UPDATE_SIGNATURE_BYTES,
65    UpdateCancellation, UpdateClient, UpdateInstallDisposition, UpdateInstallOptions,
66    UpdateProgress, WindowsUpdateInstallMode, default_update_target,
67};
68
69use std::sync::Arc;
70
71use thiserror::Error;
72
73/// An operating-system integration rejected or failed an operation.
74#[derive(Clone, Debug, Error, Eq, PartialEq)]
75pub enum SystemIntegrationError {
76    #[error("the operating-system integration operation was cancelled")]
77    Cancelled,
78    #[error("this integration is not supported on the current operating system")]
79    Unsupported,
80    #[error("invalid system integration input: {0}")]
81    InvalidInput(Arc<str>),
82    #[error("operating-system integration failed: {0}")]
83    Platform(Arc<str>),
84    #[error("network operation failed: {0}")]
85    Network(Arc<str>),
86    #[error("update metadata is invalid: {0}")]
87    InvalidUpdate(Arc<str>),
88    #[error("update signature verification failed: {0}")]
89    InvalidSignature(Arc<str>),
90}
91
92pub type Result<T> = std::result::Result<T, SystemIntegrationError>;
93
94fn invalid(message: impl Into<Arc<str>>) -> SystemIntegrationError {
95    SystemIntegrationError::InvalidInput(message.into())
96}
97
98fn platform(error: impl ToString) -> SystemIntegrationError {
99    SystemIntegrationError::Platform(Arc::from(error.to_string()))
100}
101
102#[cfg(any(
103    feature = "autostart",
104    feature = "protocol",
105    feature = "secure-storage"
106))]
107fn validate_text(value: &str, name: &str, maximum: usize) -> Result<()> {
108    if value.is_empty() || value.contains('\0') || value.len() > maximum {
109        return Err(invalid(format!(
110            "{name} must be nonempty, NUL-free, and at most {maximum} UTF-8 bytes"
111        )));
112    }
113    Ok(())
114}