Skip to main content

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

1//! List Microsoft Graph events (`GET /me/events` or
2//! `GET /me/calendars/{id}/events`).
3//!
4//! The listing returns lone events and series masters, never the
5//! occurrences a series expands into; the calendar view and the instances
6//! listing do.
7//!
8//! <https://learn.microsoft.com/en-us/graph/api/user-list-events>
9
10use alloc::format;
11
12use io_http::rfc6750::bearer::HttpAuthBearer;
13use log::{debug, trace};
14use serde::Serialize;
15use url::Url;
16
17use crate::{
18    coroutine::*,
19    msgraph_try,
20    v1::{
21        page::{MsgraphPage, link_url},
22        query::to_query_pairs,
23        rest::users::events::MsgraphEvent,
24        send::{
25            MSGRAPH_API_BASE, MsgraphSend, MsgraphSendError, MsgraphSendOutput, path_segment,
26            user_path,
27        },
28    },
29};
30
31/// One page of events.
32pub type MsgraphEventsListResponse = MsgraphPage<MsgraphEvent>;
33
34/// OData query parameters for listing events.
35#[derive(Debug, Clone, Default, Serialize, Eq, PartialEq)]
36pub struct MsgraphEventsListParams<'a> {
37    /// Maximum number of events per page (`$top`).
38    #[serde(rename = "$top")]
39    pub top: Option<u32>,
40    /// Number of events to skip (`$skip`).
41    #[serde(rename = "$skip")]
42    pub skip: Option<u32>,
43    /// Comma-separated properties to return (`$select`).
44    #[serde(rename = "$select")]
45    pub select: Option<&'a str>,
46    /// OData filter expression (`$filter`).
47    #[serde(rename = "$filter")]
48    pub filter: Option<&'a str>,
49    /// Comma-separated sort properties (`$orderby`).
50    #[serde(rename = "$orderby")]
51    pub orderby: Option<&'a str>,
52    /// Navigation clause to expand (`$expand`).
53    #[serde(rename = "$expand")]
54    pub expand: Option<&'a str>,
55}
56
57/// Lists the Microsoft Graph events of a calendar.
58pub struct MsgraphEventsList {
59    send: MsgraphSend<MsgraphEventsListResponse>,
60}
61
62impl MsgraphEventsList {
63    /// Lists the events of the default calendar, or of `calendar` when
64    /// given (a calendar id).
65    pub fn new(
66        auth: &HttpAuthBearer,
67        user_id: &str,
68        calendar: Option<&str>,
69        params: &MsgraphEventsListParams,
70    ) -> Result<Self, MsgraphSendError> {
71        debug!("prepare microsoft graph events listing");
72        trace!("calendar: {calendar:?}");
73        trace!("params: {params:?}");
74
75        let user = user_path(user_id)?;
76        let path = match calendar {
77            Some(calendar) => format!("{user}/calendars/{}/events", path_segment(calendar)?),
78            None => format!("{user}/events"),
79        };
80        let mut url = Url::parse(MSGRAPH_API_BASE)?.join(&path)?;
81        url.query_pairs_mut().extend_pairs(to_query_pairs(params));
82
83        let send = MsgraphSend::get(auth, url);
84
85        Ok(Self { send })
86    }
87
88    /// Continues a listing from an `@odata.nextLink`, sent as-is. A link
89    /// off the Microsoft Graph origin is refused.
90    pub fn from_link(auth: &HttpAuthBearer, link: &str) -> Result<Self, MsgraphSendError> {
91        debug!("prepare microsoft graph events listing 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 MsgraphEventsList {
112    type Yield = MsgraphYield;
113    type Return = Result<MsgraphSendOutput<MsgraphEventsListResponse>, 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!("events listed");
118        trace!("out: {out:?}");
119        MsgraphCoroutineState::Complete(Ok(out))
120    }
121}