Skip to main content

Crate systemconfiguration

Crate systemconfiguration 

Source
Expand description

§systemconfiguration-rs

Safe Rust bindings for Apple’s SystemConfiguration.framework on macOS.

Version 0.2.0 switches the crate to a screencapturekit-rs-style Swift bridge: Cargo builds a small SwiftPM static library, Rust owns opaque retained handles, and the public API stays ergonomic on the Rust side. If you still need low-level C symbols, enable the raw-ffi feature.

§Covered areas

systemconfiguration-rs now ships safe wrappers for the logical areas requested for the 0.2.0 migration:

  • DynamicStore
  • NetworkConfiguration overview helpers
  • Reachability / NetworkReachability
  • Preferences
  • Schema
  • NetworkService
  • NetworkSet
  • NetworkInterface
  • NetworkProtocol
  • ConsoleUser
  • CaptiveNetwork

See COVERAGE.md for the per-header audit, including the APIs that are still partial or intentionally skipped on macOS.

§Installation

[dependencies]
systemconfiguration-rs = "0.2"

Enable raw C access when needed:

[dependencies]
systemconfiguration-rs = { version = "0.2", features = ["raw-ffi"] }

The crate name is systemconfiguration-rs; the Rust library name is systemconfiguration.

§Quick start

use systemconfiguration::{DynamicStore, NetworkConfiguration, Reachability};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = DynamicStore::new("com.example.systemconfiguration-rs")?;
    println!("computer_name={:?}", store.computer_name());

    let reachability = Reachability::with_name("apple.com")?;
    println!("apple.com => {}", reachability.flags()?);

    let overview = NetworkConfiguration::overview()?;
    println!(
        "interfaces={} services={} current_set={:?}",
        overview.interface_count,
        overview.service_count,
        overview.current_set_name
    );

    Ok(())
}

§Highlights

  • Swift bridge primary implementation with one Swift file per logical area
  • Safe Rust wrappers for property lists, preferences sessions, services, sets, interfaces, protocols, reachability, captive-network helpers, and console-user lookup
  • raw-ffi feature preserving direct access to the underlying C APIs already declared by the crate
  • 11 numbered examples under examples/ and 11 per-area smoke tests under tests/

§Architecture

  • build.rs builds swift-bridge/Package.swift into a static library and links it into the Rust crate.
  • Swift bridge entry points are @_cdecl functions returning C primitives or opaque retained pointers.
  • Rust owns those handles via OwnedHandle in src/bridge.rs and releases them through shared bridge retain/release functions.
  • Some structured results are serialized as JSON in Swift and decoded with serde on the Rust side.

§Examples

Run all examples exactly as used during verification:

for ex in examples/*.rs; do
  cargo run --example "$(basename "$ex" .rs)"
done

Handy entry points:

  • cargo run --example 01_dynamic_store_overview
  • cargo run --example 03_network_reachability
  • cargo run --example 06_network_services
  • cargo run --example 11_captive_network

§API notes

  • Writing to the dynamic store or preferences can require elevated privileges; read-only smoke examples are used where the host environment denies mutation.
  • Apple deprecates SCNetworkReachability* in favor of Network.framework, but these APIs remain wrapped because they are still widely deployed.
  • CaptiveNetwork does not wrap CNCopyCurrentNetworkInfo, because that API is unavailable on modern macOS and generally entitlement-gated.
  • Schema::catalog() currently returns a curated high-value subset of SCSchemaDefinitions.h; see COVERAGE.md for details.

§License

Licensed under either of:

Modules§

prelude
raw_ffiraw-ffi

Structs§

CaptiveNetwork
ConsoleUser
DynamicStore
NetworkConfiguration
NetworkConfigurationOverview
NetworkInterface
NetworkProtocol
NetworkService
NetworkSet
Preferences
PropertyList
Reachability
ReachabilityFlags
Schema
SchemaCatalog
SystemConfigurationError

Type Aliases§

NetworkReachability
Result