Skip to main content

Connection

Struct Connection 

Source
pub struct Connection { /* private fields */ }
Expand description

Active NETCONF session on top of a Transport.

Constructed via Connection::new, which exchanges <hello> and upgrades to 1.1 framing when the server advertises crate::NETCONF_BASE_11_CAP.

Call Connection::close_session when finished; dropping a session that is still open only logs a warning, because a clean shutdown needs to await I/O.

Implementations§

Source§

impl Connection

Source

pub async fn new<T>(transport: T) -> NetconfClientResult<Connection>
where T: Transport + 'static,

Open a session: send client <hello>, parse the server hello, upgrade the framer if the server advertised :base:1.1.

Source

pub fn set_parse_replies(&mut self, parse_replies: bool)

Whether replies are parsed as RpcReply; on by default.

With parsing off, raw_rpc and the typed operations return the device’s XML untouched and an <rpc-error> is not turned into NetconfClientError::Netconf. message-id is still checked when the reply can be parsed.

Source

pub fn parse_replies(&self) -> bool

True when replies are parsed and error-severity <rpc-error> is surfaced.

Source

pub fn set_warnings_as_errors(&mut self, warnings_as_errors: bool)

Treat warning-severity <rpc-error> as NetconfClientError::Netconf.

Off by default: <rpc-error severity="warning"> plus <ok/> is success, and the warnings stay in the returned XML (or come back from Self::raw_rpc_with_warnings). Turn this on to fail the RPC instead.

Source

pub fn warnings_as_errors(&self) -> bool

True when warning-severity <rpc-error> fails the RPC.

Source

pub fn set_timeout(&mut self, timeout: Option<Duration>)

Available on crate feature tokio only.

Fail an RPC that gets no reply within timeout; unlimited by default.

A timed-out RPC leaves the session unusable, because the reply may still arrive and would be read as the answer to the next request. Later calls fail with NetconfClientError::SessionDesynchronized.

Source

pub fn session_id(&self) -> Option<u64>

Server-assigned session-id from <hello>, if the server sent one.

Source

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

Server capabilities from the <hello> exchange.

Source

pub fn has_capability(&self, capability: &str) -> bool

True if the server advertised capability (query string ignored).

Source

pub async fn get_config( &mut self, datastore: Datastore, filter: Option<Filter>, defaults: Option<WithDefaultsValue>, ) -> NetconfClientResult<String>

GetConfig implements the <get-config> rpc operation defined in RFC6241 7.1. source is the datastore to query.

Source

pub async fn get( &mut self, filter: Option<Filter>, defaults: Option<WithDefaultsValue>, ) -> NetconfClientResult<String>

<get> operational state (RFC6241 7.7).

Source

pub async fn validate( &mut self, datastore: Datastore, ) -> NetconfClientResult<String>

<validate> (RFC6241 8.6.4.1).

Source

pub async fn edit_config( &mut self, target: Datastore, content: EditContent, default_operation: Option<DefaultOperation>, test_option: Option<TestOption>, error_option: Option<ErrorOption>, ) -> NetconfClientResult<String>

EditConfig implements the <edit-config> rpc operation defined in RFC6241 7.2.

Source

pub async fn copy_config( &mut self, source: CopySource, target: Datastore, ) -> NetconfClientResult<String>

CopyConfig implements the <copy-config> rpc operation defined in RFC6241 7.3.

Source

pub async fn delete_config( &mut self, target: Datastore, ) -> NetconfClientResult<String>

DeleteConfig implements the <delete-config> rpc operation defined in RFC6241 7.4.

Source

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

Lock implements the <lock> rpc operation defined in RFC6241 7.5.

Source

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

Unlock implements the <unlock> rpc operation defined in RFC6241 7.6.

Source

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

<commit> of the candidate datastore (RFC6241 8.3.4.1).

Source

pub async fn confirmed_commit( &mut self, confirm_timeout: Option<i32>, persist: Option<String>, persist_id: Option<String>, ) -> NetconfClientResult<String>

Confirmed <commit> (RFC6241 8.4).

persist lets another session confirm later via Self::confirm_commit.

Source

pub async fn confirm_commit( &mut self, persist_id: String, ) -> NetconfClientResult<String>

Confirm a previous persist confirmed-commit (RFC6241 8.4.4.2).

Source

pub async fn cancel_commit( &mut self, persist_id: Option<String>, ) -> NetconfClientResult<String>

CancelCommit implements the <cancel-commit> rpc operation defined in RFC6241 8.4.4.1.

Source

pub async fn discard_changes(&mut self) -> NetconfClientResult<String>

DiscardChanges implements the <discard-changes> rpc operation defined in RFC6241 8.3.4.2.

Source

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

<close-session> (RFC6241 7.8).

Also tears the transport down. A transport that fails to close is logged rather than returned, because the device has already ended the session.

Source

pub async fn kill_session( &mut self, session_id: u64, ) -> NetconfClientResult<String>

KillSession implements the <kill-session> rpc operation defined in RFC6241 7.9. Terminates another NETCONF session; this connection stays open.

Source

pub async fn raw_rpc(&mut self, xml: &str) -> NetconfClientResult<String>

Sends a raw XML RPC document and returns the reply.

A document whose root is not <rpc> is wrapped in <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="N">. An existing <rpc> (any prefix) is sent as-is.

Source

pub async fn raw_rpc_with_warnings( &mut self, xml: &str, ) -> NetconfClientResult<(String, Vec<Error>)>

Like Self::raw_rpc, but returns warning-severity <rpc-error>s alongside the raw reply XML.

Error-severity replies still become NetconfClientError::Netconf (unless Self::set_parse_replies is off). Warning-only replies succeed even when Self::set_warnings_as_errors is on, because this method exists to collect them.

Source

pub async fn create_subscription( &mut self, stream: Option<&str>, filter: Option<Filter>, start_time: Option<&str>, stop_time: Option<&str>, ) -> NetconfClientResult<String>

<create-subscription> (RFC5277 2.1.1).

Does not take over the session. Later RPCs (get, edit_config, …) stay legal; notifications that arrive while those RPCs wait are buffered and come back from Self::drain_notifications / Self::recv_notification.

Missing :interleave is logged, not refused. Some devices advertise it and then ignore RPCs on the subscribed session — use a second connection there. start_time / stop_time are RFC 3339 replay bounds; stop_time requires start_time.

Source

pub fn drain_notifications(&mut self) -> Vec<String>

Take every notification buffered during earlier RPCs.

Source

pub fn has_notifications(&self) -> bool

True when Self::drain_notifications would return a non-empty list.

Source

pub async fn recv_notification(&mut self) -> NetconfClientResult<String>

Next notification: buffer first, otherwise one framed message.

Unexpected <rpc-reply> / other documents are logged and skipped. Transport EOF is an error. This wait is not bounded by Self::set_timeout.

Source

pub async fn notification( &mut self, sender: Sender<String>, stream: Option<&str>, filter: Option<Filter>, start_time: Option<&str>, stop_time: Option<&str>, ) -> NetconfClientResult<()>

Available on crate feature tokio only.

Subscribe, then forward notifications to sender until the device closes or the receiver is dropped.

Holds &mut self for the whole listen loop, so this connection cannot run other RPCs until the future ends. For interleaved RPCs (MCP, a caller that gets after subscribe) use Self::create_subscription and Self::drain_notifications / Self::recv_notification instead.

Cancel-safe to drop; wire shutdown with tokio::select!.

Trait Implementations§

Source§

impl Debug for Connection

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Drop for Connection

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.