Skip to main content

io_msgraph/v1/rest/users/events/
delta.rs

1//! Microsoft Graph calendar view delta (`GET /me/calendarView/delta` or
2//! `GET /me/calendars/{id}/calendarView/delta`).
3//!
4//! The changes to the lone events, occurrences and exceptions of a window
5//! since the previous round. The window is fixed by the round's first
6//! request and carried by every link after it.
7//!
8//! <https://learn.microsoft.com/en-us/graph/api/event-delta>
9
10use alloc::format;
11
12use io_http::rfc6750::bearer::HttpAuthBearer;
13use log::{debug, trace};
14use serde::{Deserialize, Serialize};
15use url::Url;
16
17use crate::{
18    coroutine::*,
19    msgraph_try,
20    v1::{
21        page::{MsgraphPage, link_url},
22        rest::users::{contacts::delta::MsgraphRemoved, events::MsgraphEvent},
23        send::{
24            MSGRAPH_API_BASE, MsgraphSend, MsgraphSendError, MsgraphSendOutput, path_segment,
25            user_path,
26        },
27    },
28};
29
30/// One page of a calendar view delta round.
31///
32/// More pages follow through `next_link`; the round ends when
33/// `delta_link` arrives (the token of the next round).
34pub type MsgraphEventsDeltaResponse = MsgraphPage<MsgraphEventDelta>;
35
36/// One event row of a delta page: the event (only its id when the row is
37/// a removal), plus the `@removed` marker.
38#[derive(Debug, Clone, Default, Deserialize, Serialize, Eq, PartialEq)]
39pub struct MsgraphEventDelta {
40    /// The changed event.
41    #[serde(flatten)]
42    pub event: MsgraphEvent,
43    /// The removal marker, present when the row is a removal.
44    #[serde(default, rename = "@removed", skip_serializing_if = "Option::is_none")]
45    pub removed: Option<MsgraphRemoved>,
46}
47
48/// I/O-free coroutine for a calendar view delta request, opening a round
49/// with [`new`](Self::new) or continuing one with
50/// [`from_link`](Self::from_link).
51pub struct MsgraphEventsDelta {
52    send: MsgraphSend<MsgraphEventsDeltaResponse>,
53}
54
55impl MsgraphEventsDelta {
56    /// Starts a delta round over the view of the default calendar, or of
57    /// `calendar` when given, between `start` and `end`, ISO 8601
58    /// date-times.
59    pub fn new(
60        auth: &HttpAuthBearer,
61        user_id: &str,
62        calendar: Option<&str>,
63        start: &str,
64        end: &str,
65    ) -> Result<Self, MsgraphSendError> {
66        debug!("prepare microsoft graph calendar view delta");
67        trace!("calendar: {calendar:?}, start: {start}, end: {end}");
68
69        let user = user_path(user_id)?;
70        let path = match calendar {
71            Some(calendar) => format!(
72                "{user}/calendars/{}/calendarView/delta",
73                path_segment(calendar)?
74            ),
75            None => format!("{user}/calendarView/delta"),
76        };
77        let mut url = Url::parse(MSGRAPH_API_BASE)?.join(&path)?;
78        url.query_pairs_mut()
79            .append_pair("startDateTime", start)
80            .append_pair("endDateTime", end);
81
82        let send = MsgraphSend::get(auth, url);
83
84        Ok(Self { send })
85    }
86
87    /// Continues a round from an `@odata.nextLink`, or starts the next
88    /// round from a saved `@odata.deltaLink`, sent as-is. A link off the
89    /// Microsoft Graph origin is refused.
90    pub fn from_link(auth: &HttpAuthBearer, link: &str) -> Result<Self, MsgraphSendError> {
91        debug!("prepare microsoft graph calendar view delta from link");
92        trace!("link: {link}");
93
94        let url = link_url(link)?;
95        let send = MsgraphSend::get(auth, url);
96
97        Ok(Self { send })
98    }
99
100    /// Asks Graph for at most `size` items per page
101    /// (`Prefer: odata.maxpagesize={size}`), see
102    /// [`MsgraphSend::max_page_size`]. Graph keeps no memory of it
103    /// across pages: chain it on every page request, the ones built
104    /// from an `@odata.nextLink` included.
105    pub fn max_page_size(mut self, size: u32) -> Self {
106        self.send = self.send.max_page_size(size);
107        self
108    }
109}
110
111impl MsgraphCoroutine for MsgraphEventsDelta {
112    type Yield = MsgraphYield;
113    type Return = Result<MsgraphSendOutput<MsgraphEventsDeltaResponse>, MsgraphSendError>;
114
115    fn resume(&mut self, arg: Option<&[u8]>) -> MsgraphCoroutineState<Self::Yield, Self::Return> {
116        let out = msgraph_try!(&mut self.send, arg);
117        debug!("calendar view delta received");
118        trace!("out: {out:?}");
119        MsgraphCoroutineState::Complete(Ok(out))
120    }
121}