feat(#260,#463): add high-level add_connection wrappers (#465)

Author: cachebag

docs/src/advanced/connection-options.md

@@ -86,7 +86,7 @@ let settings = ConnectionBuilder::new("802-11-wireless", "MyNetwork")
     .build();
 ```
 
-The high-level `NetworkManager` API uses `ConnectionOptions::default()` internally. For custom options, build a settings dictionary with the builder APIs and submit it via [`dbus_connection()`](../api/network-manager.md#advanced-d-bus-access). See [Submitting Builder Output](../api/builders.md#submitting-builder-output).
+The high-level `NetworkManager` API uses `ConnectionOptions::default()` internally. For custom options, build a settings dictionary with the builder APIs and submit it via [`add_connection`](../api/network-manager.md#saving-profiles-without-activating) or [`add_and_activate_connection`](../api/network-manager.md#activating-builder-output).
 
 ## Next Steps
 

docs/src/advanced/dbus.md

@@ -40,13 +40,14 @@ This creates a persistent D-Bus connection that's shared across all operations.
 
 For builder workflows and other low-level D-Bus calls, nmrs exposes the same
 connection through [`NetworkManager::dbus_connection()`](../api/network-manager.md#advanced-d-bus-access).
-Pair it with [`nmrs::raw`](../api/raw.md) (`zbus` / `zvariant` re-exports) so
-the types returned by builders are compatible with the connection nmrs manages.
+Pair it with [`nmrs::raw`](../api/raw.md) (`zbus` / `zvariant` re-exports) when
+you need D-Bus methods that nmrs does not wrap yet.
 
-Most applications should keep using the high-level `NetworkManager` methods.
-Reach for `dbus_connection()` only when you need to call NetworkManager D-Bus
-methods that nmrs does not wrap yet (for example `AddAndActivateConnection`
-with custom builder output).
+For builder output, prefer the high-level
+[`add_connection`](../api/network-manager.md#saving-profiles-without-activating)
+and
+[`add_and_activate_connection`](../api/network-manager.md#activating-builder-output)
+methods instead of calling D-Bus directly.
 
 ### Method Calls
 
@@ -106,7 +107,11 @@ methods.
 
 Advanced callers can define their own minimal `#[zbus::proxy]` traits on top of
 [`dbus_connection()`](../api/network-manager.md#advanced-d-bus-access) and
-[`nmrs::raw`](../api/raw.md). See [Submitting Builder Output](../api/builders.md#submitting-builder-output).
+[`nmrs::raw`](../api/raw.md). For builder output, use
+[`add_connection`](../api/network-manager.md#saving-profiles-without-activating)
+or
+[`add_and_activate_connection`](../api/network-manager.md#activating-builder-output)
+first.
 
 ## D-Bus Errors
 

docs/src/api/builders.md

@@ -1,8 +1,8 @@
 # Builders Module
 
-The `builders` module provides low-level APIs for constructing NetworkManager connection settings. Most users should use the high-level `NetworkManager` API instead — these builders are for advanced use cases where you need fine-grained control over the settings dictionary before calling NetworkManager D-Bus methods directly.
+The `builders` module provides low-level APIs for constructing NetworkManager connection settings. Most users should use the high-level `NetworkManager` API instead — these builders are for advanced use cases where you need fine-grained control over the settings dictionary.
 
-To submit builder output, use [`NetworkManager::dbus_connection()`](./network-manager.md#advanced-d-bus-access) together with [`nmrs::raw`](./raw.md) (`zbus` / `zvariant` re-exports). See [Submitting Builder Output](#submitting-builder-output) below.
+To submit builder output, use [`NetworkManager::add_connection`](./network-manager.md#saving-profiles-without-activating) or [`NetworkManager::add_and_activate_connection`](./network-manager.md#activating-builder-output). See [Submitting Builder Output](#submitting-builder-output) below.
 
 ## ConnectionBuilder
 
@@ -153,64 +153,60 @@ For standard connections, the `NetworkManager` API handles everything automatica
 ## Submitting Builder Output
 
 Builders produce a NetworkManager settings dictionary
-(`HashMap<&str, HashMap<&str, zvariant::Value>>`). To activate that profile you
-need the same system D-Bus connection nmrs already manages, plus compatible
-`zbus` / `zvariant` types from [`nmrs::raw`](./raw.md).
+(`HashMap<&str, HashMap<&str, zvariant::Value>>`). Pass that map to
+[`NetworkManager::add_connection`](./network-manager.md#saving-profiles-without-activating)
+to save a profile, or
+[`NetworkManager::add_and_activate_connection`](./network-manager.md#activating-builder-output)
+to create and bring it up immediately.
 
 ### Wi-Fi hotspot (AP mode)
 
-This is the workflow for cases such as [#260](https://github.com/freedesktop-rs/nmrs/issues/260) where the high-level `connect()` API does not expose every builder knob (for example `WifiMode::Ap`):
+This closes the workflow requested in [#260](https://github.com/freedesktop-rs/nmrs/issues/260) — use `WifiMode::Ap` with the high-level API:
 
 ```rust
 use nmrs::builders::{WifiConnectionBuilder, WifiMode};
-use nmrs::raw::{zbus, zvariant};
-use nmrs::{NetworkManager, Result};
-
-#[zbus::proxy(
-    interface = "org.freedesktop.NetworkManager",
-    default_service = "org.freedesktop.NetworkManager",
-    default_path = "/org/freedesktop/NetworkManager"
-)]
-trait Nm {
-    fn add_and_activate_connection(
-        &self,
-        connection: std::collections::HashMap<
-            &str,
-            std::collections::HashMap<&str, zvariant::Value<'_>>,
-        >,
-        device: zvariant::OwnedObjectPath,
-        specific_object: zvariant::OwnedObjectPath,
-    ) -> zbus::Result<(zvariant::OwnedObjectPath, zvariant::OwnedObjectPath)>;
-}
+use nmrs::NetworkManager;
 
-async fn start_hotspot(nm: &NetworkManager, interface: &str) -> Result<()> {
+async fn start_hotspot(nm: &NetworkManager, interface: &str) -> nmrs::Result<()> {
     let settings = WifiConnectionBuilder::new("Hotspot")
         .wpa_psk("password")
         .mode(WifiMode::Ap)
         .ipv4_shared()
         .ipv6_ignore()
         .build();
 
-    let device = nm.get_device_by_interface(interface).await?;
-    let proxy = NmProxy::new(nm.dbus_connection()).await?;
-    proxy
-        .add_and_activate_connection(settings, device, "/".into())
-        .await?;
-
+    nm.add_and_activate_connection(settings, Some(interface), None).await?;
     Ok(())
 }
 ```
 
-Notes:
-
-- Use `"/"` as `specific_object` for AP mode and other cases where there is no target access point.
-- For client (infrastructure) mode, resolve an access-point object path first (nmrs does this internally in `connect()`).
-- Map D-Bus errors to `ConnectionError::Dbus` (or handle them in your own error type).
-- nmrs does not yet provide a high-level wrapper for `AddConnection` / `AddAndActivateConnection`; `dbus_connection()` is the supported escape hatch.
+`specific_object` defaults to `"/"`, which is correct for AP mode.
 
 ### Saving without activating
 
-To persist a profile without bringing it up immediately, define a proxy method for `AddConnection` instead and pass the same `settings` map. nmrs uses that D-Bus call internally when saving VPN profiles.
+To persist a profile without bringing it up immediately — the workflow from [#463](https://github.com/freedesktop-rs/nmrs/issues/463):
+
+```rust
+use nmrs::builders::build_wifi_connection;
+use nmrs::{ConnectionOptions, NetworkManager, WifiSecurity};
+
+let nm = NetworkManager::new().await?;
+let settings = build_wifi_connection(
+    "GuestWiFi",
+    &WifiSecurity::WpaPsk { psk: "password".into() },
+    &ConnectionOptions::new(true),
+);
+let profile = nm.add_connection(settings).await?;
+```
+
+Activate the saved profile later with `activate_connection` via D-Bus, or use the existing high-level `connect()` APIs when the profile matches a visible network.
+
+### Advanced: direct D-Bus access
+
+If you need an NetworkManager D-Bus method that nmrs does not wrap yet, combine
+[`dbus_connection()`](./network-manager.md#advanced-d-bus-access) with
+[`nmrs::raw`](./raw.md) and define your own `#[zbus::proxy]` trait on top of
+the builder output.
 
 ## OpenVpnBuilder
 
@@ -254,6 +250,6 @@ See [docs.rs/nmrs](https://docs.rs/nmrs) for complete builder documentation.
 
 ## See Also
 
-- [Raw Module](./raw.md) – `zbus` / `zvariant` re-exports for advanced D-Bus work
-- [NetworkManager API](./network-manager.md#advanced-d-bus-access) – `dbus_connection()`
+- [NetworkManager API](./network-manager.md#activating-builder-output) – `add_connection()` / `add_and_activate_connection()`
+- [Raw Module](./raw.md) – `zbus` / `zvariant` re-exports for unwrapped D-Bus calls
 - [D-Bus Architecture](../advanced/dbus.md) – how settings reach NetworkManager

docs/src/api/network-manager.md

@@ -21,6 +21,48 @@ let nm = NetworkManager::with_config(config).await?;
 let config = nm.timeout_config();
 ```
 
+## Saving Profiles Without Activating
+
+```rust
+use nmrs::builders::build_wifi_connection;
+use nmrs::{ConnectionOptions, NetworkManager, WifiSecurity};
+
+let nm = NetworkManager::new().await?;
+let settings = build_wifi_connection(
+    "GuestWiFi",
+    &WifiSecurity::WpaPsk { psk: "password".into() },
+    &ConnectionOptions::new(true),
+);
+let profile = nm.add_connection(settings).await?;
+```
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `add_connection(settings)` | `Result<OwnedObjectPath>` | Save a profile via `Settings.AddConnection` without activating it ([#463](https://github.com/freedesktop-rs/nmrs/issues/463)) |
+
+## Activating Builder Output
+
+```rust
+use nmrs::builders::{WifiConnectionBuilder, WifiMode};
+use nmrs::NetworkManager;
+
+let nm = NetworkManager::new().await?;
+let settings = WifiConnectionBuilder::new("Hotspot")
+    .wpa_psk("password")
+    .mode(WifiMode::Ap)
+    .ipv4_shared()
+    .build();
+
+nm.add_and_activate_connection(settings, Some("wlan0"), None).await?;
+```
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `add_and_activate_connection(settings, interface, specific_object)` | `Result<(OwnedObjectPath, OwnedObjectPath)>` | Create and activate a profile in one step ([#260](https://github.com/freedesktop-rs/nmrs/issues/260)) |
+
+- `interface`: device name such as `"wlan0"`, or `None` to auto-pick the first device matching `connection.type`
+- `specific_object`: access-point path for client Wi-Fi, or `None` for AP mode / Ethernet / VPN (`"/"`)
+
 ## Advanced D-Bus Access
 
 ```rust
@@ -34,8 +76,10 @@ let conn = nm.dbus_connection(); // &zbus::Connection
 | `dbus_connection()` | `&zbus::Connection` | Shared system bus connection for advanced D-Bus calls |
 
 Use this with [`nmrs::raw`](./raw.md) and the [builders](./builders.md) module
-when you need to call NetworkManager methods such as `AddConnection` or
-`AddAndActivateConnection` directly. See [Submitting Builder Output](./builders.md#submitting-builder-output).
+only when you need NetworkManager methods that nmrs does not wrap yet. For
+builder output, prefer
+[`add_connection`](./network-manager.md#saving-profiles-without-activating) and
+[`add_and_activate_connection`](./network-manager.md#activating-builder-output).
 
 ## Wi-Fi Methods
 

docs/src/api/raw.md

@@ -9,7 +9,10 @@ pub mod raw {
 }
 ```
 
-Use it together with [`NetworkManager::dbus_connection()`](./network-manager.md#advanced-d-bus-access) when you need to call NetworkManager D-Bus methods directly — for example after building a settings dictionary with the [`builders`](./builders.md) module.
+Use it together with [`NetworkManager::dbus_connection()`](./network-manager.md#advanced-d-bus-access)
+when you need D-Bus methods that nmrs does not wrap yet. For builder output,
+prefer [`add_connection`](./network-manager.md#saving-profiles-without-activating)
+and [`add_and_activate_connection`](./network-manager.md#activating-builder-output).
 
 ## Why it exists
 
@@ -28,8 +31,8 @@ output and with the connection returned by `dbus_connection()`.
 3. Create a zbus proxy on that connection using `nmrs::raw::zbus`.
 4. Call `AddConnection` or `AddAndActivateConnection` on NetworkManager.
 
-See [Submitting Builder Output](./builders.md#submitting-builder-output) for a
-full Wi-Fi hotspot example and [D-Bus Architecture](../advanced/dbus.md) for
+See [Submitting Builder Output](./builders.md#submitting-builder-output) for the
+preferred high-level workflow and [D-Bus Architecture](../advanced/dbus.md) for
 background on how nmrs talks to NetworkManager.
 
 ## What is not exposed

nmrs/CHANGELOG.md

@@ -7,7 +7,8 @@ All notable changes to the `nmrs` crate will be documented in this file.
 - Expose existing secrets on SecretRequest for re-auth prefill ([#460](https://github.com/freedesktop-rs/nmrs/pull/460))
 - `MonitorHandle` returned by `monitor_network_changes` and `monitor_device_changes` for graceful shutdown ([#461](https://github.com/freedesktop-rs/nmrs/pull/461))
 - `NetworkManager::dbus_connection()` and `nmrs::raw` (`zbus` / `zvariant` re-exports) for advanced builder workflows ([#462](https://github.com/freedesktop-rs/nmrs/pull/464))
-- mdbook docs for `dbus_connection()`, `nmrs::raw`, and submitting builder output ([#462](https://github.com/freedesktop-rs/nmrs/pull/464))
+- `NetworkManager::add_connection()` and `NetworkManager::add_and_activate_connection()` for submitting builder output without custom zbus proxies ([#260](https://github.com/freedesktop-rs/nmrs/issues/260), [#465](https://github.com/freedesktop-rs/nmrs/pull/465))
+- mdbook docs for builder submission workflow, `add_connection()`, and `add_and_activate_connection()` ([#462](https://github.com/freedesktop-rs/nmrs/pull/464))
 
 ### Fixed
 - `monitor_network_changes` now detects hotplugged Wi-Fi devices instead of only monitoring devices present at startup ([#461](https://github.com/freedesktop-rs/nmrs/pull/461))

nmrs/src/api/builders/mod.rs

@@ -35,8 +35,10 @@
 //! need fine-grained control over the raw settings dictionary before
 //! handing it to NetworkManager's `AddConnection` or
 //! `AddAndActivateConnection` D-Bus methods via
-//! [`NetworkManager::dbus_connection`](crate::NetworkManager::dbus_connection)
-//! and [`raw`](crate::raw).
+//! [`NetworkManager::add_connection`](crate::NetworkManager::add_connection),
+//! [`NetworkManager::add_and_activate_connection`](crate::NetworkManager::add_and_activate_connection),
+//! [`NetworkManager::dbus_connection`](crate::NetworkManager::dbus_connection),
+//! or [`raw`](crate::raw).
 //!
 //! # Examples
 //!
@@ -71,8 +73,7 @@
 //!     .build();
 //!
 //! let _conn = nm.dbus_connection();
-//! // Use `settings` with NetworkManager's AddAndActivateConnection on `_conn`
-//! // via `nmrs::raw::zbus` proxies.
+//! // Prefer `nm.add_and_activate_connection(settings, Some("wlan0"), None)` instead.
 //! # Ok(())
 //! # }
 //! ```
@@ -98,9 +99,9 @@
 //!     .expect("WireGuardBuilder is fully configured");
 //! ```
 //!
-//! The returned settings can then be passed to NetworkManager's
-//! `AddConnection` or `AddAndActivateConnection` D-Bus methods through
-//! [`NetworkManager::dbus_connection`](crate::NetworkManager::dbus_connection).
+//! The returned settings can then be passed to
+//! [`NetworkManager::add_connection`](crate::NetworkManager::add_connection) or
+//! [`NetworkManager::add_and_activate_connection`](crate::NetworkManager::add_and_activate_connection).
 
 pub mod bluetooth;
 pub mod connection_builder;