ruma_appservice_api/thirdparty/
get_protocol.rs

Help
1//! `GET /_matrix/app/*/thirdparty/protocol/{protocol}`
2//!
3//! Fetches metadata about the various third party networks that an application service supports.
4
5pub mod v1 {
6    //! `/v1/` ([spec])
7    //!
8    //! [spec]: https://spec.matrix.org/latest/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol
9
10    use std::collections::BTreeMap;
11
12    use ruma_common::{
13        api::{request, response, Metadata},
14        metadata,
15        thirdparty::{Protocol, ProtocolInstance, ProtocolInstanceInit},
16    };
17    use serde::{Deserialize, Serialize};
18
19    const METADATA: Metadata = metadata! {
20        method: GET,
21        rate_limited: false,
22        authentication: AccessToken,
23        history: {
24            1.0 => "/_matrix/app/v1/thirdparty/protocol/:protocol",
25        }
26    };
27
28    /// Request type for the `get_protocol` endpoint.
29    #[request]
30    pub struct Request {
31        /// The name of the protocol.
32        #[ruma_api(path)]
33        pub protocol: String,
34    }
35
36    /// Response type for the `get_protocol` endpoint.
37    #[response]
38    pub struct Response {
39        /// Metadata about the protocol.
40        #[ruma_api(body)]
41        pub protocol: AppserviceProtocol,
42    }
43
44    impl Request {
45        /// Creates a new `Request` with the given protocol name.
46        pub fn new(protocol: String) -> Self {
47            Self { protocol }
48        }
49    }
50
51    impl Response {
52        /// Creates a new `Response` with the given protocol.
53        pub fn new(protocol: AppserviceProtocol) -> Self {
54            Self { protocol }
55        }
56    }
57
58    /// Metadata about a third party protocol, as returned by an appservice to a homeserver.
59    ///
60    /// To create an instance of this type, first create a [`ProtocolInit`] and convert it via
61    /// `AppserviceProtocol::from` / `.into()`.
62    ///
63    /// [`ProtocolInit`]: ruma_common::thirdparty::ProtocolInit
64    pub type AppserviceProtocol = Protocol<AppserviceProtocolInstance>;
65
66    /// Metadata about an instance of a third party protocol, as returned by an appservice to a
67    /// homeserver.
68    ///
69    /// To create an instance of this type, first create a [`ProtocolInstanceInit`] and convert it
70    /// via `AppserviceProtocolInstance::from` / `.into()`.
71    #[derive(Clone, Debug, Deserialize, Serialize)]
72    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
73    pub struct AppserviceProtocolInstance {
74        /// A human-readable description for the protocol, such as the name.
75        pub desc: String,
76
77        /// An optional content URI representing the protocol.
78        #[serde(skip_serializing_if = "Option::is_none")]
79        pub icon: Option<String>,
80
81        /// Preset values for `fields` the client may use to search by.
82        pub fields: BTreeMap<String, String>,
83
84        /// A unique identifier across all instances.
85        pub network_id: String,
86    }
87
88    impl From<ProtocolInstanceInit> for AppserviceProtocolInstance {
89        fn from(init: ProtocolInstanceInit) -> Self {
90            let ProtocolInstanceInit { desc, fields, network_id } = init;
91            Self { desc, icon: None, fields, network_id }
92        }
93    }
94
95    impl From<AppserviceProtocolInstance> for ProtocolInstance {
96        fn from(value: AppserviceProtocolInstance) -> Self {
97            let AppserviceProtocolInstance { desc, icon, fields, network_id } = value;
98            let mut instance =
99                ProtocolInstance::from(ProtocolInstanceInit { desc, fields, network_id });
100            instance.icon = icon;
101            instance
102        }
103    }
104}
ruma_appservice_api/thirdparty/get_protocol.rs

ruma_appservice_api/thirdparty/
get_protocol.rs
