io_webdav/rfc4918/
report.rs

1//! Generic `REPORT` coroutine (RFC 3253 §3.6).
2//!
3//! Sends a `REPORT` against `path` with a caller-built query body (e.g.
4//! a CalDAV `calendar-query` from
5//! [`calendar_query_body`](crate::rfc4791::calendar::calendar_query_body))
6//! and parses the response into a [`Multistatus`].
7//!
8//! # Example
9//!
10//! ```rust,no_run
11//! use std::{
12//!     io::{Read, Write},
13//!     net::TcpStream,
14//! };
15//!
16//! use io_webdav::{
17//!     coroutine::{WebdavCoroutine, WebdavCoroutineState, WebdavYield},
18//!     rfc4791::calendar::calendar_query_body,
19//!     rfc4918::{GETETAG, WebdavAuth, report::Report},
20//! };
21//! use url::Url;
22//!
23//! // Ready stream needed (TCP-connected, TLS-negociated)
24//! let mut stream = TcpStream::connect("dav.example.org:443").unwrap();
25//! let mut buf = [0u8; 4096];
26//!
27//! let base_url: Url = "https://dav.example.org/".parse().unwrap();
28//! let auth = WebdavAuth::None;
29//! let body = calendar_query_body(&[GETETAG], "");
30//! let mut coroutine =
31//!     Report::new(&base_url, &auth, "io-webdav", "/dav/calendars/personal/", 1, body);
32//! let mut arg = None;
33//!
34//! let multistatus = loop {
35//!     match coroutine.resume(arg.take()) {
36//!         WebdavCoroutineState::Yielded(WebdavYield::WantsWrite(bytes)) => {
37//!             stream.write_all(&bytes).unwrap();
38//!         }
39//!         WebdavCoroutineState::Yielded(WebdavYield::WantsRead) => {
40//!             let n = stream.read(&mut buf).unwrap();
41//!             arg = Some(&buf[..n]);
42//!         }
43//!         WebdavCoroutineState::Complete(Ok(multistatus)) => break multistatus,
44//!         WebdavCoroutineState::Complete(Err(err)) => panic!("{err}"),
45//!     }
46//! };
47//!
48//! println!("{} entries", multistatus.responses.len());
49//! ```
50
51use alloc::{string::String, vec::Vec};
52
53use log::trace;
54use url::Url;
55
56use crate::{
57    coroutine::*,
58    rfc4918::{
59        Multistatus, WebdavAuth, parse_multistatus,
60        request::WebdavRequest,
61        send::{SendError, SendRaw},
62    },
63    webdav_try,
64};
65
66/// Coroutine that runs a `REPORT` and parses the multistatus body.
67#[derive(Debug)]
68pub struct Report {
69    state: State,
70}
71
72impl Report {
73    /// Builds a new `REPORT` coroutine against `path` with the given
74    /// `Depth` and query `body`.
75    pub fn new(
76        base_url: &Url,
77        auth: &WebdavAuth,
78        user_agent: &str,
79        path: &str,
80        depth: u8,
81        body: Vec<u8>,
82    ) -> Self {
83        let request = WebdavRequest::report(base_url, auth, user_agent, path)
84            .depth(depth)
85            .content_type_xml()
86            .body(body);
87        Self {
88            state: State::Send(SendRaw::new(request)),
89        }
90    }
91}
92
93impl WebdavCoroutine for Report {
94    type Yield = WebdavYield;
95    type Return = Result<Multistatus, SendError>;
96
97    fn resume(&mut self, arg: Option<&[u8]>) -> WebdavCoroutineState<Self::Yield, Self::Return> {
98        trace!("sending request");
99        match &mut self.state {
100            State::Send(send) => {
101                let ok = webdav_try!(send, arg);
102                let xml = String::from_utf8_lossy(&ok.body);
103                WebdavCoroutineState::Complete(Ok(parse_multistatus(&xml)))
104            }
105        }
106    }
107}
108
109#[derive(Debug)]
110enum State {
111    Send(SendRaw),
112}
io_webdav/rfc4918/report.rs

io_webdav/rfc4918/
report.rs
