synapse_admin_api/users/list_users/
v2.rs

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

synapse_admin_api/users/list_users/
v2.rs
