Crate systemconfiguration 

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:

• MIT license (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

Modules

async_apiasync

Wraps async SystemConfiguration callback streams. Async event streams for SystemConfiguration callbacks.

prelude

Re-exports common SystemConfiguration wrapper types.

raw_ffiraw-ffi

Wraps raw SystemConfiguration FFI exports.

schema_definitions

Wraps constants from SCSchemaDefinitions.h.

Structs

BondInterface

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCBondInterfaceRef.

BondStatus

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCBondStatusRef.

CaptiveNetwork

Re-exports the corresponding SystemConfiguration wrappers. Wraps the CaptiveNetwork support APIs in SystemConfiguration.

ConsoleUser

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCDynamicStoreCopyConsoleUser results.

DynamicStore

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCDynamicStoreRef.

DynamicStoreRunLoopSource

Re-exports the corresponding SystemConfiguration wrappers. Wraps the CFRunLoopSourceRef created by SCDynamicStoreCreateRunLoopSource.

NetworkConfiguration

Re-exports the corresponding SystemConfiguration wrappers. Provides overview helpers for SystemConfiguration network-configuration APIs.

NetworkConfigurationOverview

Re-exports the corresponding SystemConfiguration wrappers. Wraps a summary built from SystemConfiguration network-configuration APIs.

NetworkConnection

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkConnectionRef.

NetworkConnectionUserPreferences

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkConnectionCopyUserPreferences results.

NetworkInterface

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkInterfaceRef.

NetworkInterfaceMediaOptions

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkInterfaceCopyMediaOptions results.

NetworkInterfaceMtuInfo

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkInterfaceCopyMTU results.

NetworkProtocol

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkProtocolRef.

NetworkService

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkServiceRef.

NetworkSet

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkSetRef.

Preferences

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCPreferencesRef.

PreferencesNotification

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCPreferencesNotification.

PropertyList

Re-exports the corresponding SystemConfiguration wrappers. Wraps CFPropertyListRef values used by SystemConfiguration APIs.

Reachability

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkReachabilityRef.

ReachabilityFlags

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkReachabilityFlags.

Schema

Re-exports the corresponding SystemConfiguration wrappers. Wraps the SCSchemaDefinitions.h catalog helpers.

SchemaCatalog

Re-exports the corresponding SystemConfiguration wrappers. Wraps grouped symbols from SCSchemaDefinitions.h.

SystemConfiguration

Re-exports the corresponding SystemConfiguration wrappers. Wraps top-level SystemConfiguration error helpers.

SystemConfigurationError

Re-exports the corresponding SystemConfiguration wrappers. Wraps SystemConfiguration framework failures.

SystemConfigurationLastError

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCCopyLastError details.

VlanInterface

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCVLANInterfaceRef.

Enums

NetworkConnectionPppStatus

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkConnectionPPPStatus.

NetworkConnectionStatus

Re-exports the corresponding SystemConfiguration wrappers. Wraps SCNetworkConnectionStatus.

Type Aliases

NetworkConnectionFlags

Re-exports the corresponding SystemConfiguration wrappers. Alias for SCNetworkConnectionFlags values.

NetworkReachability

Re-exports the corresponding SystemConfiguration wrappers. Alias for the SCNetworkReachabilityRef wrapper.

Result

Re-exports the corresponding SystemConfiguration wrappers. Result alias used by SystemConfiguration wrapper APIs.