d

Signed-off-by: Timo K <toger5@hotmail.de>

Author: toger5

bindings/matrix-sdk-ffi/src/widget.rs

@@ -125,9 +125,10 @@ pub async fn generate_webview_url(
 ///   call widget.
 #[matrix_sdk_ffi_macros::export]
 pub fn new_virtual_element_call_widget(
-    props: matrix_sdk::widget::VirtualElementCallWidgetOptions,
+    props: matrix_sdk::widget::VirtualElementCallWidgetProperties,
+    config: matrix_sdk::widget::VirtualElementCallWidgetConfig,
 ) -> Result<WidgetSettings, ParseError> {
-    Ok(matrix_sdk::widget::WidgetSettings::new_virtual_element_call_widget(props)
+    Ok(matrix_sdk::widget::WidgetSettings::new_virtual_element_call_widget(props, config)
         .map(|w| w.into())?)
 }
 

crates/matrix-sdk/src/widget/mod.rs

@@ -45,7 +45,8 @@ pub use self::{
     capabilities::{Capabilities, CapabilitiesProvider},
     filter::{Filter, MessageLikeEventFilter, StateEventFilter, ToDeviceEventFilter},
     settings::{
-        ClientProperties, EncryptionSystem, Intent, VirtualElementCallWidgetOptions, WidgetSettings,
+        ClientProperties, EncryptionSystem, Intent, VirtualElementCallWidgetConfig,
+        VirtualElementCallWidgetProperties, WidgetSettings,
     },
 };
 

crates/matrix-sdk/src/widget/settings/element_call.rs

@@ -26,9 +26,9 @@ use super::{url_params, WidgetSettings};
 
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
-/// Parameters for the Element Call widget.
+/// Serialization struct for URL parameters for the Element Call widget.
 /// These are documented at https://github.com/element-hq/element-call/blob/livekit/docs/url-params.md
-struct ElementCallParams {
+struct ElementCallUrlParams {
     user_id: String,
     room_id: String,
     widget_id: String,
@@ -44,13 +44,13 @@ struct ElementCallParams {
     /// compatibility. Set to `true` if intent is `Intent::StartCall`.
     skip_lobby: Option<bool>,
     confine_to_room: bool,
-    app_prompt: bool,
+    app_prompt: Option<bool>,
     /// Supported since Element Call v0.13.0.
-    header: HeaderStyle,
+    header: Option<HeaderStyle>,
     /// Deprecated since Element Call v0.13.0. Included for backwards
     /// compatibility. Use header: "standard"|"none" instead.
     hide_header: Option<bool>,
-    preload: bool,
+    preload: Option<bool>,
     /// Deprecated since Element Call v0.9.0. Included for backwards
     /// compatibility. Set to the same as `posthog_user_id`.
     analytics_id: Option<String>,
@@ -59,7 +59,7 @@ struct ElementCallParams {
     font_scale: Option<f64>,
     font: Option<String>,
     #[serde(rename = "perParticipantE2EE")]
-    per_participant_e2ee: bool,
+    per_participant_e2ee: Option<bool>,
     password: Option<String>,
     /// Supported since Element Call v0.8.0.
     intent: Option<Intent>,
@@ -73,8 +73,10 @@ struct ElementCallParams {
     sentry_dsn: Option<String>,
     /// Supported since Element Call v0.9.0. Only used by the embedded package.
     sentry_environment: Option<String>,
-    hide_screensharing: bool,
-    controlled_media_devices: bool,
+    /// Supported since Element Call v0.9.0.
+    hide_screensharing: Option<bool>,
+    /// Supported since Element Call v0.13.0.
+    controlled_audio_devices: Option<bool>,
     /// Supported since Element Call v0.14.0.
     send_notification_type: Option<NotificationType>,
 }
@@ -110,6 +112,11 @@ pub enum Intent {
     StartCall,
     /// The user wants to join an existing call.
     JoinExisting,
+    /// The user wants to join an existing call that is a "Direct Message" (DM)
+    /// room.
+    JoinExistingDM,
+    /// The user wants to start a call in a "Direct Message" (DM) room.
+    StartCallDM,
 }
 
 /// Defines how (if) element-call renders a header.
@@ -126,40 +133,34 @@ pub enum HeaderStyle {
 }
 
 /// Types of call notifications.
-#[derive(Debug, PartialEq, Serialize, uniffi::Enum, Clone)]
+#[derive(Debug, PartialEq, Serialize, uniffi::Enum, Clone, Default)]
 #[serde(rename_all = "snake_case")]
 pub enum NotificationType {
-    /// The receiving client should display a visual notification.
+    /// The receiving client should display a visual notification.    
+    #[default]
     Notification,
     /// The receiving client should ring with an audible sound.
     Ring,
 }
 
-/// Properties to create a new virtual Element Call widget.
+/// Configuration parameters, to create a new virtual Element Call widget.
+///
+/// If `intent` is provided the appropriate default values for all other
+/// parameters will be used by element call.
+/// In most cases its enough to only set the intent. Use the other properties
+/// only if you want to deviate from the `intent` defaults.
+///
+/// Set [`docs/url-params.md`](https://github.com/element-hq/element-call/blob/livekit/docs/url-params.md)
+/// to find out more about the parameters and their defaults.
 #[derive(Debug, Default, uniffi::Record, Clone)]
-pub struct VirtualElementCallWidgetOptions {
-    /// The url to the app.
-    ///
-    /// E.g. <https://call.element.io>, <https://call.element.dev>, <https://call.element.dev/room>
-    pub element_call_url: String,
+pub struct VirtualElementCallWidgetConfig {
+    /// The intent of showing the call.
+    /// If the user wants to start a call or join an existing one.
+    /// Controls if the lobby is skipped or not.
+    pub intent: Option<Intent>,
 
-    /// The widget id.
-    pub widget_id: String,
-
-    /// The url that is used as the target for the PostMessages sent
-    /// by the widget (to the client).
-    ///
-    /// For a web app client this is the client url. In case of using other
-    /// platforms the client most likely is setup up to listen to
-    /// postmessages in the same webview the widget is hosted. In this case
-    /// the `parent_url` is set to the url of the webview with the widget. Be
-    /// aware that this means that the widget will receive its own postmessage
-    /// messages. The `matrix-widget-api` (js) ignores those so this works but
-    /// it might break custom implementations.
-    ///
-    /// Defaults to `element_call_url` for the non-iframe (dedicated webview)
-    /// usecase.
-    pub parent_url: Option<String>,
+    /// Skip the lobby when joining a call.
+    pub skip_lobby: Option<bool>,
 
     /// Whether the branding header of Element call should be shown or if a
     /// mobile header navbar should be render.
@@ -179,11 +180,6 @@ pub struct VirtualElementCallWidgetOptions {
     /// Default: `false`
     pub preload: Option<bool>,
 
-    /// The font scale which will be used inside element call.
-    ///
-    /// Default: `1`
-    pub font_scale: Option<f64>,
-
     /// Whether element call should prompt the user to open in the browser or
     /// the app.
     ///
@@ -195,6 +191,53 @@ pub struct VirtualElementCallWidgetOptions {
     /// Default: `true`
     pub confine_to_room: Option<bool>,
 
+    /// Do not show the screenshare button.
+    pub hide_screensharing: Option<bool>,
+
+    /// Make the audio devices be controlled by the os instead of the
+    /// element-call webview.
+    pub controlled_audio_devices: Option<bool>,
+
+    /// Whether and what type of notification Element Call should send, when
+    /// starting a call.
+    pub send_notification_type: Option<NotificationType>,
+}
+
+/// Properties to create a new virtual Element Call widget.
+///
+/// All these are required to start the widget in the first place.
+/// This is different from the `VirtualElementCallWidgetConfiguration` which
+/// configures the widgets behavior.
+#[derive(Debug, Default, uniffi::Record, Clone)]
+pub struct VirtualElementCallWidgetProperties {
+    /// The url to the app.
+    ///
+    /// E.g. <https://call.element.io>, <https://call.element.dev>, <https://call.element.dev/room>
+    pub element_call_url: String,
+
+    /// The widget id.
+    pub widget_id: String,
+
+    /// The url that is used as the target for the PostMessages sent
+    /// by the widget (to the client).
+    ///
+    /// For a web app client this is the client url. In case of using other
+    /// platforms the client most likely is setup up to listen to
+    /// postmessages in the same webview the widget is hosted. In this case
+    /// the `parent_url` is set to the url of the webview with the widget. Be
+    /// aware that this means that the widget will receive its own postmessage
+    /// messages. The `matrix-widget-api` (js) ignores those so this works but
+    /// it might break custom implementations.
+    ///
+    /// Defaults to `element_call_url` for the non-iframe (dedicated webview)
+    /// usecase.
+    pub parent_url: Option<String>,
+
+    /// The font scale which will be used inside element call.
+    ///
+    /// Default: `1`
+    pub font_scale: Option<f64>,
+
     /// The font to use, to adapt to the system font.
     pub font: Option<String>,
 
@@ -203,14 +246,6 @@ pub struct VirtualElementCallWidgetOptions {
     /// Use `EncryptionSystem::Unencrypted` to disable encryption.
     pub encryption: EncryptionSystem,
 
-    /// The intent of showing the call.
-    /// If the user wants to start a call or join an existing one.
-    /// Controls if the lobby is skipped or not.
-    pub intent: Option<Intent>,
-
-    /// Do not show the screenshare button.
-    pub hide_screensharing: bool,
-
     /// Can be used to pass a PostHog id to element call.
     pub posthog_user_id: Option<String>,
     /// The host of the posthog api.
@@ -230,14 +265,6 @@ pub struct VirtualElementCallWidgetOptions {
     /// Sentry [environment](https://docs.sentry.io/concepts/key-terms/key-terms/)
     /// This is only used by the embedded package of Element Call.
     pub sentry_environment: Option<String>,
-    //// - `true`: The webview should show the list of media devices it detects using
-    ////   `enumerateDevices`.
-    ///  - `false`: the webview shows a a list of devices injected by the
-    ///    client. (used on ios & android)
-    pub controlled_media_devices: bool,
-    /// Whether and what type of notification Element Call should send, when
-    /// starting a call.
-    pub send_notification_type: Option<NotificationType>,
 }
 
 impl WidgetSettings {
@@ -255,17 +282,13 @@ impl WidgetSettings {
     /// * `props` - A struct containing the configuration parameters for a
     ///   element call widget.
     pub fn new_virtual_element_call_widget(
-        props: VirtualElementCallWidgetOptions,
+        props: VirtualElementCallWidgetProperties,
+        config: VirtualElementCallWidgetConfig,
     ) -> Result<Self, url::ParseError> {
         let mut raw_url: Url = Url::parse(&props.element_call_url)?;
 
-        let skip_lobby = if props.intent.as_ref().is_some_and(|x| x == &Intent::StartCall) {
-            Some(true)
-        } else {
-            None
-        };
         #[allow(deprecated)]
-        let query_params = ElementCallParams {
+        let query_params = ElementCallUrlParams {
             user_id: url_params::USER_ID.to_owned(),
             room_id: url_params::ROOM_ID.to_owned(),
             widget_id: url_params::WIDGET_ID.to_owned(),
@@ -277,30 +300,30 @@ impl WidgetSettings {
             base_url: url_params::HOMESERVER_URL.to_owned(),
 
             parent_url: props.parent_url.unwrap_or(props.element_call_url.clone()),
-            confine_to_room: props.confine_to_room.unwrap_or(true),
-            app_prompt: props.app_prompt.unwrap_or_default(),
-            header: props.header.unwrap_or_default(),
-            hide_header: props.hide_header,
-            preload: props.preload.unwrap_or_default(),
+            confine_to_room: config.confine_to_room.unwrap_or(true),
+            app_prompt: config.app_prompt,
+            header: config.header,
+            hide_header: config.hide_header,
+            preload: config.preload,
             font_scale: props.font_scale,
             font: props.font,
-            per_participant_e2ee: props.encryption == EncryptionSystem::PerParticipantKeys,
+            per_participant_e2ee: Some(props.encryption == EncryptionSystem::PerParticipantKeys),
             password: match props.encryption {
                 EncryptionSystem::SharedSecret { secret } => Some(secret),
                 _ => None,
             },
-            intent: props.intent,
-            skip_lobby,
+            intent: config.intent,
+            skip_lobby: config.skip_lobby,
             analytics_id: props.posthog_user_id.clone(),
             posthog_user_id: props.posthog_user_id,
             posthog_api_host: props.posthog_api_host,
             posthog_api_key: props.posthog_api_key,
             sentry_dsn: props.sentry_dsn,
             sentry_environment: props.sentry_environment,
             rageshake_submit_url: props.rageshake_submit_url,
-            hide_screensharing: props.hide_screensharing,
-            controlled_media_devices: props.controlled_media_devices,
-            send_notification_type: props.send_notification_type,
+            hide_screensharing: config.hide_screensharing,
+            controlled_media_devices: config.controlled_media_devices,
+            send_notification_type: config.send_notification_type,
         };
 
         let query =
@@ -326,7 +349,10 @@ mod tests {
     use ruma::api::client::profile::get_profile;
     use url::Url;
 
-    use crate::widget::{ClientProperties, Intent, WidgetSettings};
+    use crate::widget::{
+        settings::element_call::VirtualElementCallWidgetConfig, ClientProperties, Intent,
+        WidgetSettings,
+    };
 
     const WIDGET_ID: &str = "1/@#w23";
 
@@ -336,36 +362,28 @@ mod tests {
         rageshake: bool,
         sentry: bool,
         intent: Option<Intent>,
-        controlle_output: bool,
+        controlled_output: bool,
     ) -> WidgetSettings {
-        let mut props = VirtualElementCallWidgetOptions {
+        let props = VirtualElementCallWidgetProperties {
             element_call_url: "https://call.element.io".to_owned(),
             widget_id: WIDGET_ID.to_owned(),
-            preload: Some(true),
-            app_prompt: Some(true),
-            confine_to_room: Some(true),
+            posthog_user_id: posthog.then(|| "POSTHOG_USER_ID".to_owned()),
+            posthog_api_host: posthog.then(|| "posthog.element.io".to_owned()),
+            posthog_api_key: posthog.then(|| "POSTHOG_KEY".to_owned()),
+            rageshake_submit_url: rageshake.then(|| "https://rageshake.element.io".to_owned()),
+            sentry_dsn: sentry.then(|| "SENTRY_DSN".to_owned()),
+            sentry_environment: sentry.then(|| "SENTRY_ENV".to_owned()),
             encryption: encryption.unwrap_or(EncryptionSystem::PerParticipantKeys),
-            intent,
-            controlled_media_devices: controlle_output,
-            ..VirtualElementCallWidgetOptions::default()
+            ..VirtualElementCallWidgetProperties::default()
         };
 
-        if posthog {
-            props.posthog_user_id = Some("POSTHOG_USER_ID".to_owned());
-            props.posthog_api_host = Some("posthog.element.io".to_owned());
-            props.posthog_api_key = Some("POSTHOG_KEY".to_owned());
-        }
-
-        if rageshake {
-            props.rageshake_submit_url = Some("https://rageshake.element.io".to_owned());
-        }
-
-        if sentry {
-            props.sentry_dsn = Some("SENTRY_DSN".to_owned());
-            props.sentry_environment = Some("SENTRY_ENV".to_owned());
-        }
+        let config = VirtualElementCallWidgetConfig {
+            controlled_media_devices: Some(controlled_output),
+            intent,
+            ..VirtualElementCallWidgetConfig::default()
+        };
 
-        WidgetSettings::new_virtual_element_call_widget(props)
+        WidgetSettings::new_virtual_element_call_widget(props, config)
             .expect("could not parse virtual element call widget")
     }
 
@@ -385,7 +403,7 @@ mod tests {
 
     use serde_html_form::from_str;
 
-    use super::{EncryptionSystem, VirtualElementCallWidgetOptions};
+    use super::{EncryptionSystem, VirtualElementCallWidgetProperties};
 
     fn get_query_sets(url: &Url) -> Option<(QuerySet, QuerySet)> {
         let fq = from_str::<QuerySet>(url.fragment_query().unwrap_or_default()).ok()?;

crates/matrix-sdk/src/widget/settings/mod.rs

@@ -21,7 +21,9 @@ use crate::Room;
 mod element_call;
 mod url_params;
 
-pub use self::element_call::{EncryptionSystem, Intent, VirtualElementCallWidgetOptions};
+pub use self::element_call::{
+    EncryptionSystem, Intent, VirtualElementCallWidgetConfig, VirtualElementCallWidgetProperties,
+};
 
 /// Settings of the widget.
 #[derive(Debug, Clone)]