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
impl Connection
Sourcepub async fn new<T>(transport: T) -> NetconfClientResult<Connection>where
T: Transport + 'static,
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.
Sourcepub fn set_parse_replies(&mut self, parse_replies: bool)
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.
Sourcepub fn parse_replies(&self) -> bool
pub fn parse_replies(&self) -> bool
True when replies are parsed and error-severity <rpc-error> is surfaced.
Sourcepub fn set_warnings_as_errors(&mut self, warnings_as_errors: bool)
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.
Sourcepub fn warnings_as_errors(&self) -> bool
pub fn warnings_as_errors(&self) -> bool
True when warning-severity <rpc-error> fails the RPC.
Sourcepub fn set_timeout(&mut self, timeout: Option<Duration>)
Available on crate feature tokio only.
pub fn set_timeout(&mut self, timeout: Option<Duration>)
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.
Sourcepub fn session_id(&self) -> Option<u64>
pub fn session_id(&self) -> Option<u64>
Server-assigned session-id from <hello>, if the server sent one.
Sourcepub fn capabilities(&self) -> &[String]
pub fn capabilities(&self) -> &[String]
Server capabilities from the <hello> exchange.
Sourcepub fn has_capability(&self, capability: &str) -> bool
pub fn has_capability(&self, capability: &str) -> bool
True if the server advertised capability (query string ignored).
Sourcepub async fn get_config(
&mut self,
datastore: Datastore,
filter: Option<Filter>,
defaults: Option<WithDefaultsValue>,
) -> NetconfClientResult<String>
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.
Sourcepub async fn get(
&mut self,
filter: Option<Filter>,
defaults: Option<WithDefaultsValue>,
) -> NetconfClientResult<String>
pub async fn get( &mut self, filter: Option<Filter>, defaults: Option<WithDefaultsValue>, ) -> NetconfClientResult<String>
<get> operational state (RFC6241 7.7).
Sourcepub async fn validate(
&mut self,
datastore: Datastore,
) -> NetconfClientResult<String>
pub async fn validate( &mut self, datastore: Datastore, ) -> NetconfClientResult<String>
<validate> (RFC6241 8.6.4.1).
Sourcepub async fn edit_config(
&mut self,
target: Datastore,
content: EditContent,
default_operation: Option<DefaultOperation>,
test_option: Option<TestOption>,
error_option: Option<ErrorOption>,
) -> NetconfClientResult<String>
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.
Sourcepub async fn copy_config(
&mut self,
source: CopySource,
target: Datastore,
) -> NetconfClientResult<String>
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.
Sourcepub async fn delete_config(
&mut self,
target: Datastore,
) -> NetconfClientResult<String>
pub async fn delete_config( &mut self, target: Datastore, ) -> NetconfClientResult<String>
DeleteConfig implements the <delete-config> rpc operation defined in RFC6241 7.4.
Sourcepub async fn lock(&mut self, target: Datastore) -> NetconfClientResult<String>
pub async fn lock(&mut self, target: Datastore) -> NetconfClientResult<String>
Lock implements the <lock> rpc operation defined in RFC6241 7.5.
Sourcepub async fn unlock(&mut self, target: Datastore) -> NetconfClientResult<String>
pub async fn unlock(&mut self, target: Datastore) -> NetconfClientResult<String>
Unlock implements the <unlock> rpc operation defined in RFC6241 7.6.
Sourcepub async fn commit(&mut self) -> NetconfClientResult<String>
pub async fn commit(&mut self) -> NetconfClientResult<String>
<commit> of the candidate datastore (RFC6241 8.3.4.1).
Sourcepub async fn confirmed_commit(
&mut self,
confirm_timeout: Option<i32>,
persist: Option<String>,
persist_id: Option<String>,
) -> NetconfClientResult<String>
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.
Sourcepub async fn confirm_commit(
&mut self,
persist_id: String,
) -> NetconfClientResult<String>
pub async fn confirm_commit( &mut self, persist_id: String, ) -> NetconfClientResult<String>
Confirm a previous persist confirmed-commit (RFC6241 8.4.4.2).
Sourcepub async fn cancel_commit(
&mut self,
persist_id: Option<String>,
) -> NetconfClientResult<String>
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.
Sourcepub async fn discard_changes(&mut self) -> NetconfClientResult<String>
pub async fn discard_changes(&mut self) -> NetconfClientResult<String>
DiscardChanges implements the <discard-changes> rpc operation defined in RFC6241 8.3.4.2.
Sourcepub async fn close_session(&mut self) -> NetconfClientResult<String>
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.
Sourcepub async fn kill_session(
&mut self,
session_id: u64,
) -> NetconfClientResult<String>
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.
Sourcepub async fn raw_rpc(&mut self, xml: &str) -> NetconfClientResult<String>
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.
Sourcepub async fn raw_rpc_with_warnings(
&mut self,
xml: &str,
) -> NetconfClientResult<(String, Vec<Error>)>
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.
Sourcepub async fn create_subscription(
&mut self,
stream: Option<&str>,
filter: Option<Filter>,
start_time: Option<&str>,
stop_time: Option<&str>,
) -> NetconfClientResult<String>
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.
Sourcepub fn drain_notifications(&mut self) -> Vec<String>
pub fn drain_notifications(&mut self) -> Vec<String>
Take every notification buffered during earlier RPCs.
Sourcepub fn has_notifications(&self) -> bool
pub fn has_notifications(&self) -> bool
True when Self::drain_notifications would return a non-empty list.
Sourcepub async fn recv_notification(&mut self) -> NetconfClientResult<String>
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.
Sourcepub 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.
pub async fn notification( &mut self, sender: Sender<String>, stream: Option<&str>, filter: Option<Filter>, start_time: Option<&str>, stop_time: Option<&str>, ) -> NetconfClientResult<()>
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!.