Struct Session 

pub struct Session { /* private fields */ }

A NETCONF session with pipelining support.

Architecture:

• Writer: the session holds the write half of the stream and a codec for encoding outgoing RPCs.
• Reader task: a background tokio task reads framed messages from the read half, classifies them (<rpc-reply> vs <notification>), and routes them to the correct handler.
• Pipelining: rpc_send() writes an RPC and returns an RpcFuture without waiting for the reply. Multiple RPCs can be in flight simultaneously.

Implementations

impl Session

pub async fn connect( host: &str, port: u16, username: &str, password: &str, ) -> Result<Self>

Connect to a NETCONF server over SSH with password authentication.

Examples found in repository

examples/basic.rs (line 6)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn connect_with_config( host: &str, port: u16, username: &str, password: &str, config: SessionConfig, ) -> Result<Self>

Connect with custom configuration.

pub async fn from_stream<S: AsyncRead + AsyncWrite + Unpin + Send + 'static>( stream: S, ) -> Result<Self>

Create a session from an existing stream (useful for testing).

pub async fn from_stream_with_config<S: AsyncRead + AsyncWrite + Unpin + Send + 'static>( stream: S, config: SessionConfig, ) -> Result<Self>

Create a session from an existing stream with custom configuration.

pub fn session_id(&self) -> u32

Examples found in repository

examples/basic.rs (line 8)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub fn server_capabilities(&self) -> &[String]

Examples found in repository

examples/basic.rs (line 10)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub fn framing_mode(&self) -> FramingMode

Examples found in repository

examples/basic.rs (line 9)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub fn state(&self) -> SessionState

Examples found in repository

examples/basic.rs (line 126)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn rpc_send(&mut self, inner_xml: &str) -> Result<RpcFuture>

Send a raw RPC and return a future for the reply (pipelining).

This writes the RPC to the server immediately but does not wait for the reply. Call RpcFuture::response() to await the reply. Multiple RPCs can be pipelined by calling this repeatedly before awaiting any of them.

Examples found in repository

examples/basic.rs (line 83)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn rpc_raw(&mut self, inner_xml: &str) -> Result<RpcReply>

Send a raw RPC and wait for the reply.

Examples found in repository

examples/basic.rs (line 110)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn get_config( &mut self, source: Datastore, filter: Option<&str>, ) -> Result<String>

Retrieve configuration from a datastore.

Examples found in repository

examples/basic.rs (line 13)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn get_config_payload( &mut self, source: Datastore, filter: Option<&str>, ) -> Result<DataPayload>

Retrieve configuration as a zero-copy DataPayload.

Same as get_config() but returns a DataPayload instead of String, avoiding a copy of the response body. Use payload.as_str() for a zero-copy &str view, or payload.reader() for streaming XML events.

Examples found in repository

examples/basic.rs (line 26)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn get(&mut self, filter: Option<&str>) -> Result<String>

Retrieve running configuration and state data.

pub async fn get_payload(&mut self, filter: Option<&str>) -> Result<DataPayload>

Retrieve running configuration and state data as a zero-copy DataPayload.

Same as get() but returns a DataPayload instead of String, avoiding a copy of the response body.

pub async fn edit_config( &mut self, target: Datastore, config: &str, ) -> Result<()>

Edit the configuration of a target datastore.

Examples found in repository

examples/basic.rs (lines 48-64)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn lock(&mut self, target: Datastore) -> Result<()>

Lock a datastore

Examples found in repository

examples/basic.rs (line 44)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn unlock(&mut self, target: Datastore) -> Result<()>

Unlock a datastore.

Examples found in repository

examples/basic.rs (line 77)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn commit(&mut self) -> Result<()>

Commit the candidate configuration to running.

Examples found in repository

examples/basic.rs (line 69)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn close_session(&mut self) -> Result<()>

Gracefully close the NETCONF session.

Examples found in repository

examples/basic.rs (line 125)

async fn main() -> netconf_rust::Result<()> {
    // --- Connect ---
    let mut session = Session::connect("localhost", 830, "netconf", "netconf").await?;

    println!("Session ID: {}", session.session_id());
    println!("Framing: {:?}", session.framing_mode());
    println!("Capabilities: {}", session.server_capabilities().join(", "));

    // --- Get full running config ---
    let config = session.get_config(Datastore::Running, None).await?;
    println!("\n=== Running config ===\n{config}");

    // --- Filtered get-config with subtree filter ---
    let interfaces = session
        .get_config(
            Datastore::Running,
            Some(r#"<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>"#),
        )
        .await?;
    println!("\n=== Interfaces ===\n{interfaces}");

    // --- Zero-copy DataPayload ---
    let payload = session.get_config_payload(Datastore::Running, None).await?;
    println!("\n=== Config payload size: {} bytes ===", payload.len());

    // Stream XML events directly from the payload's bytes
    let mut reader = payload.reader();
    let mut element_count = 0;
    loop {
        match reader.read_event() {
            Ok(quick_xml::events::Event::Start(_)) => element_count += 1,
            Ok(quick_xml::events::Event::Eof) => break,
            _ => {}
        }
    }
    println!("Total XML elements: {element_count}");

    // --- Edit config with candidate commit ---
    // Note: NACM may deny access to certain data models depending on the user's
    // permissions. We use the netconf-server model which the netconf user can write.
    session.lock(Datastore::Candidate).await?;
    println!("\n=== Locked candidate ===");

    match session
        .edit_config(
            Datastore::Candidate,
            r#"
        <netconf-server xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-server">
            <listen>
                <endpoint>
                    <name>default-ssh</name>
                    <ssh>
                        <tcp-server-parameters>
                            <local-address>0.0.0.0</local-address>
                        </tcp-server-parameters>
                    </ssh>
                </endpoint>
            </listen>
        </netconf-server>
    "#,
        )
        .await
    {
        Ok(()) => {
            println!("Edited candidate config");
            session.commit().await?;
            println!("Committed");
        }
        Err(e) => {
            eprintln!("edit-config failed (NACM?): {e}");
        }
    }

    session.unlock(Datastore::Candidate).await?;
    println!("Unlocked candidate");

    // --- Pipelining: send 3 RPCs before awaiting any replies ---
    println!("\n=== Pipelining ===");
    let fut1 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut2 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;
    let fut3 = session
        .rpc_send("<get-config><source><running/></source></get-config>")
        .await?;

    println!(
        "Sent 3 RPCs (message-ids: {}, {}, {})",
        fut1.message_id(),
        fut2.message_id(),
        fut3.message_id()
    );

    let reply1 = fut1.response().await?;
    let reply2 = fut2.response().await?;
    let reply3 = fut3.response().await?;
    println!(
        "Got 3 replies (message-ids: {}, {}, {})",
        reply1.message_id, reply2.message_id, reply3.message_id
    );

    // --- Raw RPC for operations not covered by convenience methods ---
    println!("\n=== Raw RPC ===");
    let reply = session
        .rpc_raw("<get-schema><identifier>ietf-interfaces</identifier></get-schema>")
        .await?;
    match reply.body {
        netconf_rust::RpcReplyBody::Data(payload) => {
            println!("Got schema ({} bytes)", payload.len())
        }
        netconf_rust::RpcReplyBody::Ok => println!("ok"),
        netconf_rust::RpcReplyBody::Error(errors) => {
            for e in &errors {
                eprintln!("Error: {}: {}", e.error_tag, e.error_message);
            }
        }
    }

    // --- Graceful close ---
    session.close_session().await?;
    println!("\nSession closed (state: {})", session.state());

    Ok(())
}

pub async fn kill_session(&mut self, session_id: u32) -> Result<()>

Force-close another NETCONF session.

Trait Implementations

impl Drop for Session

fn drop(&mut self)

Executes the destructor for this type.