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