Struct XmlStream

pub struct XmlStream<Io, T: FromXml> { /* private fields */ }

XML stream

This struct represents an RFC 6120 XML stream, where the payload consists of items of type T implementing FromXml and AsXml.

Implementations

impl<Io, T: FromXml> XmlStream<Io, T>

pub fn get_stream(&self) -> &Io

Obtain a reference to the Io stream.

impl<Io: AsyncBufRead + AsyncWrite + Unpin, T: FromXml + AsXml + Debug> XmlStream<Io, T>

pub fn initiate_reset(self) -> InitiatingStream<Io>

Initiate a stream reset

To actually send the stream header, call send_header on the result.

Panics

Attempting to reset the stream while an object is being received will panic. This can generally only happen if you call poll_next directly, as doing that is otherwise prevented by the borrowchecker.

In addition, attempting to reset a stream which has been closed by either side or which has had an I/O error will also cause a panic.

pub async fn accept_reset(self, barrier: &T) -> Result<AcceptedStream<Io>>

Trigger a stream reset on the initiator side and await the new stream header.

This is the responder-side counterpart to initiate_reset. The element which causes the stream reset must be passed as barrier and it will be sent right before resetting the parser state. This way, the race condition outlined in the xmlstream module’s documentation is guaranteed to be avoided.

Note that you should not send the element passed as barrier down the stream yourself, as this function takes care of it.

Stream resets without a triggering element

These are not possible to do safely and not specified in RFC 6120, hence they cannot be done in XmlStream.

Panics

Attempting to reset the stream while an object is being received will panic. This can generally only happen if you call poll_next directly, as doing that is otherwise prevented by the borrowchecker.

In addition, attempting to reset a stream which has been closed by either side or which has had an I/O error will also cause a panic.

pub fn into_inner(self) -> Io

Discard all XML state and return the inner I/O object.

impl<Io: AsyncWrite, T: FromXml + AsXml> XmlStream<Io, T>

pub fn poll_shutdown( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Initiate stream shutdown and poll for completion.

Please see Self::shutdown for details.

impl<Io: AsyncWrite + Unpin, T: FromXml + AsXml> XmlStream<Io, T>

pub fn shutdown(&mut self) -> Shutdown<'_, Io, T>

Send the stream footer and close the sender side of the underlying transport.

Unlike poll_close (from the Sink impls), this will not close the receiving side of the underlying the transport. It is advisable to call poll_close eventually after poll_shutdown in order to gracefully handle situations where the remote side does not close the stream cleanly.

Trait Implementations

impl<'x, Io: AsyncWrite, T: FromXml + AsXml> Sink<&'x T> for XmlStream<Io, T>

type Error = Error

The type of value produced by the sink when an error occurs.

fn poll_ready( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Self::Error>>

Attempts to prepare the Sink to receive a value.

fn poll_flush( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Self::Error>>

Flush any remaining output from this sink.

fn poll_close( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Self::Error>>

Flush any remaining output and close this sink, if necessary.

fn start_send(self: Pin<&mut Self>, item: &'x T) -> Result<(), Self::Error>

Begin the process of sending a value to the sink. Each call to this function must be preceded by a successful call to poll_ready which returned Poll::Ready(Ok(())).

impl<Io: AsyncBufRead, T: FromXml + AsXml + Debug> Stream for XmlStream<Io, T>

type Item = Result<T, ReadError>

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.

impl<'__pin, Io, T: FromXml> Unpin for XmlStream<Io, T>

where PinnedFieldsOf<__Origin<'__pin, Io, T>>: Unpin,