Struct Client

pub struct Client { /* private fields */ }

XMPP client connection and state

This implements the futures crate’s Stream to receive stream state changes as well as stanzas received via the stream.

To send stanzas, the send_stanza method can be used.

Implementations

impl Client

pub fn bound_jid(&self) -> Option<&Jid>

Get the client’s bound JID (the one reported by the XMPP server).

pub async fn send_stanza( &mut self, stanza: Stanza, ) -> Result<StanzaToken, Error>

Send a stanza.

This will automatically allocate an ID if the stanza has no ID set. The returned StanzaToken is awaited up to the StanzaStage::Sent stage, which means that this coroutine only returns once the stanza has actually been written to the XMPP transport.

Note that this does not imply that it has been reeceived by the peer, nor that it has been successfully processed. To confirm that a stanza has been received by a peer, the StanzaToken::wait_for method can be called with StanzaStage::Acked, but that stage will only ever be reached if the server supports XEP-0198 and it has been negotiated successfully (this may change in the future).

For sending Iq request stanzas, it is recommended to use send_iq, which allows awaiting the response.

pub async fn send_iq( &mut self, to: Option<Jid>, req: IqRequest, ) -> IqResponseToken

Send an IQ request and return a token to retrieve the response.

This coroutine method will complete once the Iq has been sent to the server. The returned IqResponseToken can be used to await the response. See also the documentation of IqResponseToken for more information on the behaviour of these tokens.

Important: Even though IQ responses are delivered through the returned token (and never through the Stream), the Stream implementation of the Client must be polled to make progress on the stream and to process incoming stanzas and thus to deliver them to the returned token.

Note: If an IQ response arrives after the token has been dropped (e.g. due to a timeout), it will be delivered through the Stream like any other stanza.

pub fn get_stream_features(&self) -> Option<&StreamFeatures>

Get the stream features (<stream:features/>) of the underlying stream.

If the stream has not completed negotiation yet, this will return None. Note that stream features may change at any point due to a transparent reconnect.

pub async fn send_end(self) -> Result<(), Error>

Close the client cleanly.

This performs an orderly stream shutdown, ensuring that all resources are correctly cleaned up.

impl Client

pub fn new<J: Into<Jid>, P: Into<String>>(jid: J, password: P) -> Self

Available on crate feature starttls only.

Start a new XMPP client using StartTLS transport and autoreconnect

Start polling the returned instance so that it will connect and yield events.

pub fn new_starttls<J: Into<Jid>, P: Into<String>>( jid: J, password: P, dns_config: DnsConfig, timeouts: Timeouts, ) -> Self

Available on crate feature starttls only.

Start a new XMPP client with StartTLS transport and specific DNS config

impl Client

pub fn new_plaintext<J: Into<Jid>, P: Into<String>>( jid: J, password: P, dns_config: DnsConfig, timeouts: Timeouts, ) -> Self

Available on crate feature insecure-tcp only.

Start a new XMPP client with plaintext insecure connection and specific DNS config

impl Client

pub fn new_with_connector<J: Into<Jid>, P: Into<String>, C: ServerConnector>( jid: J, password: P, connector: C, timeouts: Timeouts, ) -> Self

Start a new client given that the JID is already parsed.

Trait Implementations

impl Stream for Client

Incoming XMPP events

In an async fn you may want to use this with use futures::stream::StreamExt;

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Low-level read on the XMPP stream, allowing the underlying machinery to:

• connect,
• starttls,
• authenticate,
• bind a session, and finally
• receive stanzas

…for your client

type Item = Event

Values yielded by the stream.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.