Struct StanzaStream

pub struct StanzaStream { /* private fields */ }

Frontend interface to a reliable, always-online stanza stream.

Implementations

impl StanzaStream

pub fn new_c2s<C: ServerConnector>( server: C, jid: Jid, password: String, timeouts: Timeouts, queue_depth: usize, ) -> Self

Establish a new client-to-server stream using the given ServerConnector.

jid and password must be the user account’s credentials. jid may either be a bare JID (to let the server choose a resource) or a full JID (to request a specific resource from the server, with no guarantee of succcess).

timeouts controls the responsiveness to connection interruptions on the underlying transports. Please see the Timeouts struct’s documentation for hints on how to correctly configure this.

The queue_depth controls the sizes for the incoming and outgoing stanza queues. If the size is exceeded, the corresponding direction will block until the queues can be flushed. Note that the respective reverse direction is not affected (i.e. if your outgoing queue is full for example because of a slow server, you can still receive data).

pub fn new( connector: Box<dyn FnMut(Option<String>, Sender<Connection>) + Send + 'static>, queue_depth: usize, ) -> Self

Create a new stanza stream.

Stanza streams operate using a connector which is responsible for producing a new stream whenever necessary. It is the connector’s responsibility that:

• It never fails to send to the channel it is given. If the connector drops the channel, the StanzaStream will consider this fatal and fail the stream.

• All streams are authenticated and secured as necessary.

• All streams are authenticated for the same entity. If the connector were to provide streams for different identities, information leaks could occur as queues from previous sessions are being flushed on the new stream on a reconnect.

Most notably, the connector is not responsible for performing resource binding: Resource binding is handled by the StanzaStream.

connector will be called soon after new() was called to establish the first underlying stream for the StanzaStream.

The queue_depth controls the sizes for the incoming and outgoing stanza queues. If the size is exceeded, the corresponding direction will block until the queues can be flushed. Note that the respective reverse direction is not affected (i.e. if your outgoing queue is full for example because of a slow server, you can still receive data).

pub async fn close(self)

Close the stream.

This will initiate a clean shutdown of the stream and will prevent and cancel any more reconnection attempts.

pub async fn send(&self, stanza: Box<Stanza>) -> StanzaToken

Send a stanza via the stream.

Note that completion of this function merely signals that the stanza has been enqueued successfully: it may be stuck in the transmission queue for quite a while if the stream is currently disconnected. The transmission progress can be observed via the returned StanzaToken.

Panics

If the stream has failed catastrophically (i.e. due to a software bug), this function may panic.

Trait Implementations

impl Stream for StanzaStream

type Item = Event

Values yielded by the stream.

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

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

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

Returns the bounds on the remaining length of the stream.