synapse_admin_api/users/list_users/
v2.rs

1//! [GET /_synapse/admin/v2/users](https://github.com/element-hq/synapse/blob/master/docs/admin_api/user_admin_api.md#list-accounts)
2
3use ruma::{
4    OwnedUserId, UInt,
5    api::{auth_scheme::AccessToken, metadata, request, response},
6};
7use serde::{Deserialize, Serialize};
8
9metadata! {
10    method: GET,
11    rate_limited: false,
12    authentication: AccessToken,
13    path: "/_synapse/admin/v2/users",
14}
15
16#[request]
17#[derive(Default)]
18pub struct Request {
19    /// Offset in the returned list.
20    ///
21    /// Defaults to 0.
22    #[serde(default, skip_serializing_if = "ruma::serde::is_default")]
23    #[ruma_api(query)]
24    pub from: UInt,
25
26    /// Maximum amount of users to return. Defaults to 100.
27    #[serde(skip_serializing_if = "Option::is_none")]
28    #[ruma_api(query)]
29    pub limit: Option<UInt>,
30
31    /// user_id is optional and filters to only return users with user IDs that contain this value.
32    ///
33    /// This parameter is ignored when using the name parameter.
34    #[serde(skip_serializing_if = "Option::is_none")]
35    #[ruma_api(query)]
36    pub user_id: Option<OwnedUserId>,
37
38    /// name is optional and filters to only return users with user ID localparts or displaynames
39    /// that contain this value.
40    #[serde(skip_serializing_if = "Option::is_none")]
41    #[ruma_api(query)]
42    pub name: Option<String>,
43
44    /// The parameter guests is optional and if false will exclude guest users.
45    ///
46    /// Defaults to true to include guest users.
47    #[serde(default = "ruma::serde::default_true", skip_serializing_if = "ruma::serde::is_true")]
48    #[ruma_api(query)]
49    pub guests: bool,
50
51    /// The parameter deactivated is optional and if true will include deactivated users.
52    ///
53    /// Defaults to false to exclude deactivated users.
54    #[serde(default, skip_serializing_if = "ruma::serde::is_default")]
55    #[ruma_api(query)]
56    pub deactivated: bool,
57
58    /// Whether to include locked users in the response.
59    ///
60    /// Defaults to false to exclude locked users.
61    #[serde(default, skip_serializing_if = "ruma::serde::is_default")]
62    #[ruma_api(query)]
63    pub locked: bool,
64}
65
66#[response]
67pub struct Response {
68    /// List of users containing `UserMinorDetails`.
69    pub users: Vec<UserMinorDetails>,
70
71    /// Token to receive the next `UserMinorDetails` batch.
72    ///
73    /// To paginate, check for next_token and if present, call the endpoint again with from set
74    /// to the value of next_token. This will return a new page. If the endpoint does not return
75    /// a next_token then there are no more users to paginate through.
76    pub next_token: Option<String>,
77
78    /// Total amount of users.
79    pub total: UInt,
80}
81
82impl Request {
83    /// Creates an empty `Request`.
84    pub fn new() -> Self {
85        Default::default()
86    }
87}
88
89impl Response {
90    /// Creates a `Response` with the given `UserMinorDetails` and the total amount of users.
91    pub fn new(users: Vec<UserMinorDetails>, total: UInt) -> Self {
92        Self { users, next_token: None, total }
93    }
94}
95
96/// A minor set of user details.
97#[derive(Serialize, Deserialize, Clone, Debug)]
98#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
99pub struct UserMinorDetails {
100    /// The user's name.
101    pub name: String,
102
103    /// todo: doc but I do not know what this is
104    #[serde(skip_serializing_if = "Option::is_none")]
105    pub user_type: Option<String>,
106
107    /// Is the account a guest
108    #[serde(deserialize_with = "crate::serde::bool_or_uint")]
109    pub is_guest: bool,
110
111    /// Is the user a server admin
112    #[serde(deserialize_with = "crate::serde::bool_or_uint")]
113    pub admin: bool,
114
115    /// Is the account deactivated
116    #[serde(deserialize_with = "crate::serde::bool_or_uint")]
117    pub deactivated: bool,
118
119    /// The user's display name, if set.
120    pub displayname: String,
121
122    /// The user's avatar URL, if set.
123    #[serde(skip_serializing_if = "Option::is_none")]
124    pub avatar_url: Option<String>,
125
126    /// Whether the account is locked.
127    #[serde(default, deserialize_with = "crate::serde::bool_or_uint")]
128    pub locked: bool,
129}
130
131impl UserMinorDetails {
132    /// Construct a `UserMinorDetails` with the given user name and all the other fields set to
133    /// their default value.
134    pub fn new(name: String) -> Self {
135        Self {
136            name,
137            is_guest: false,
138            admin: false,
139            user_type: None,
140            deactivated: false,
141            displayname: String::new(),
142            avatar_url: None,
143            locked: false,
144        }
145    }
146}
synapse_admin_api/users/list_users/v2.rs

synapse_admin_api/users/list_users/
v2.rs
