ruma_appservice_api/thirdparty/
get_protocol.rs

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

ruma_appservice_api/thirdparty/
get_protocol.rs
