ruma_client_api/profile/
set_avatar_url.rs

1//! `PUT /_matrix/client/*/profile/{userId}/avatar_url`
2//!
3//! Set the avatar URL of the user.
4
5pub mod v3 {
6    //! `/v3/` ([spec])
7    //!
8    //! [spec]: https://spec.matrix.org/v1.15/client-server-api/#put_matrixclientv3profileuseridavatar_url
9
10    use ruma_common::{
11        OwnedMxcUri, OwnedUserId,
12        api::{auth_scheme::AccessToken, request, response},
13        metadata,
14    };
15
16    #[cfg(feature = "unstable-msc4466")]
17    use crate::profile::PropagateTo;
18
19    metadata! {
20        method: PUT,
21        rate_limited: true,
22        authentication: AccessToken,
23        history: {
24            1.0 => "/_matrix/client/r0/profile/{user_id}/avatar_url",
25            1.1 => "/_matrix/client/v3/profile/{user_id}/avatar_url",
26        }
27    }
28
29    /// Request type for the `set_avatar_url` endpoint.
30    #[request]
31    pub struct Request {
32        /// The user whose avatar URL will be set.
33        #[ruma_api(path)]
34        pub user_id: OwnedUserId,
35
36        /// The new avatar URL for the user.
37        ///
38        /// `None` is used to unset the avatar.
39        ///
40        /// If you activate the `compat-empty-string-null` feature, this field being an empty
41        /// string in JSON will result in `None` here during deserialization.
42        ///
43        /// If you active the `compat-unset-avatar` feature, this field being `None` will result
44        /// in an empty string in serialization, which is the same thing Element Web does (c.f.
45        /// <https://github.com/matrix-org/matrix-spec/issues/378#issuecomment-1055831264>).
46        #[cfg_attr(
47            feature = "compat-empty-string-null",
48            serde(default, deserialize_with = "ruma_common::serde::empty_string_as_none")
49        )]
50        #[cfg_attr(
51            feature = "compat-unset-avatar",
52            serde(serialize_with = "ruma_common::serde::none_as_empty_string")
53        )]
54        #[cfg_attr(
55            not(feature = "compat-unset-avatar"),
56            serde(skip_serializing_if = "Option::is_none")
57        )]
58        pub avatar_url: Option<OwnedMxcUri>,
59
60        /// The [BlurHash](https://blurha.sh) for the avatar pointed to by `avatar_url`.
61        ///
62        /// This uses the unstable prefix in
63        /// [MSC2448](https://github.com/matrix-org/matrix-spec-proposals/pull/2448).
64        #[cfg(feature = "unstable-msc2448")]
65        #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
66        pub blurhash: Option<String>,
67
68        /// The propagation mode to use for this profile update.
69        #[cfg(feature = "unstable-msc4466")]
70        #[ruma_api(query)]
71        #[serde(rename = "computer.gingershaped.msc4466.propagate_to")]
72        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
73        pub propagate_to: PropagateTo,
74    }
75
76    /// Response type for the `set_avatar_url` endpoint.
77    #[response]
78    #[derive(Default)]
79    pub struct Response {}
80
81    impl Request {
82        /// Creates a new `Request` with the given user ID and avatar URL.
83        #[deprecated = "Use the set_profile_field endpoint instead."]
84        pub fn new(user_id: OwnedUserId, avatar_url: Option<OwnedMxcUri>) -> Self {
85            Self {
86                user_id,
87                avatar_url,
88                #[cfg(feature = "unstable-msc2448")]
89                blurhash: None,
90                #[cfg(feature = "unstable-msc4466")]
91                propagate_to: PropagateTo::default(),
92            }
93        }
94    }
95
96    impl Response {
97        /// Creates an empty `Response`.
98        pub fn new() -> Self {
99            Self {}
100        }
101    }
102
103    #[cfg(all(test, feature = "server"))]
104    mod tests {
105        use ruma_common::api::IncomingRequest as _;
106
107        use super::Request;
108
109        #[test]
110        fn deserialize_unset_request() {
111            let req = Request::try_from_http_request(
112                http::Request::builder()
113                    .method("PUT")
114                    .uri("https://bar.org/_matrix/client/r0/profile/@foo:bar.org/avatar_url")
115                    .body(&[] as &[u8])
116                    .unwrap(),
117                &["@foo:bar.org"],
118            )
119            .unwrap();
120            assert_eq!(req.user_id, "@foo:bar.org");
121            assert_eq!(req.avatar_url, None);
122
123            #[cfg(feature = "compat-empty-string-null")]
124            {
125                let req = Request::try_from_http_request(
126                    http::Request::builder()
127                        .method("PUT")
128                        .uri("https://bar.org/_matrix/client/r0/profile/@foo:bar.org/avatar_url")
129                        .body(serde_json::to_vec(&serde_json::json!({ "avatar_url": "" })).unwrap())
130                        .unwrap(),
131                    &["@foo:bar.org"],
132                )
133                .unwrap();
134                assert_eq!(req.user_id, "@foo:bar.org");
135                assert_eq!(req.avatar_url, None);
136            }
137        }
138    }
139}
ruma_client_api/profile/set_avatar_url.rs

ruma_client_api/profile/
set_avatar_url.rs
