systemconfiguration-rs 0.5.0

Safe Rust bindings for Apple's SystemConfiguration framework via a Swift bridge on macOS
Documentation

systemconfiguration-rs

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

Version 0.4.0 continues the screencapturekit-rs-style Swift bridge introduced in 0.2.0: Cargo builds a small SwiftPM static library, Rust owns opaque retained handles, and the public API stays ergonomic on the Rust side. If you need async notification streams, enable the async feature. 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 covered by the current bridge release:

  • DynamicStore
  • NetworkConfiguration overview helpers
  • NetworkConnection
  • Reachability / NetworkReachability
  • Preferences
  • Schema
  • NetworkService
  • NetworkSet
  • NetworkInterface
  • BondInterface
  • VlanInterface
  • NetworkProtocol
  • ConsoleUser
  • CaptiveNetwork
  • SystemConfiguration error helpers
  • Optional async_api notification streams (features = ["async"])

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

Installation

[dependencies]
systemconfiguration-rs = "0.4"

Enable async notification streams when needed:

[dependencies]
systemconfiguration-rs = { version = "0.4", features = ["async"] }

Enable raw C access when needed:

[dependencies]
systemconfiguration-rs = { version = "0.4", 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, dynamic-store callbacks, services, sets, interfaces, bond/VLAN configuration, network connections, reachability, captive-network helpers, console-user lookup, and SystemConfiguration error helpers
  • Optional async feature exposing DynamicStoreNotificationStream, ReachabilityStream, and PreferencesNotificationStream backed by doom-fish-utils::stream::BoundedAsyncStream
  • raw-ffi feature preserving direct access to the underlying C APIs already declared by the crate
  • 14 numbered examples under examples/ and 15 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 individual examples as needed:

  • 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
  • cargo run --example 50_async_dynamic_store --features async
  • cargo run --example 51_async_reachability --features async
  • cargo run --example 52_async_preferences --features async

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.
  • Async notification streams own their subscription handles; drop the stream to unsubscribe and tear down the underlying run loop or dispatch queue.
  • CaptiveNetwork does not wrap CNCopyCurrentNetworkInfo, because that API is unavailable on modern macOS and generally entitlement-gated.
  • Schema::catalog() now exposes the full SCSchemaDefinitions.h catalog in SchemaCatalog::all, while keeping the original curated convenience groups.

License

Licensed under either of: