Draft: docs/notification: Write XML interface definition for version 2 #1304
Conversation
This takes the discussion in flatpak#983 and turns it into an actual possible v2 of the notification interface. The permission part was intentionally left out since it's tangential to the new properties and features proposed here.
| * ``cellbroadcast.danger.extreme`` | ||
|
|
||
| Intended to be used to display extreme danger warnings broadcasted by the cell network. | ||
|
|
||
| * ``cellbroadcast.danger.severe`` | ||
|
|
||
| Intended to be used to display severe danger warnings broadcasted by the cell network. | ||
|
|
||
| * ``cellbroadcast.amberalert`` | ||
|
|
||
| Intended to be used to display amber alerts broadcasted by the cell network. | ||
|
|
||
| * ``cellbroadcast.test`` | ||
|
|
||
| Intended to be used to display tests broadcasted by the cell network. |
There was a problem hiding this comment.
Is it specifically designed not to support push notification based warn apps, like EUwarn, Katwarn, or NINA? Wouldn't it make sense to broaden the scope from cellbroadcast.* to any type of broadcast.*?
There was a problem hiding this comment.
Cell broadcast is standardized, so it was easy to find the 5 kinds of alerts that can be sent via cell broadcast, and it made sense to add them here as they are unlikely to change.
For all those warn-apps, afaik there's no standard, and I'm not sure which different kinds of alerts they are sending. Possibly the alerts are grouped into kinds similar to the cell broadcasts ones, but here someone would have to do the research.
There was a problem hiding this comment.
@jonas2515: So what is their relationship with their use by apps?
There was a problem hiding this comment.
Cell broadcast itself doesn't have those, doesn't it? It is used for all kinds of things, including public warning messages. AfaIk, those specified entirely elsewhere, incl. in the Wireless Emergency Alerts, or EU-Alert specifications. They can be serialised as XML with the Common Alerting Protocol. All those share similar urgency and importance definitions. And at least all those specifications listed above are used outside cell-broadcasted, as well. (Maybe I'm missing something. I tried to find relevant specifications and protocols, but it feels like the big picture is complicated, with essentially compatible, but in different jurisdictions re-defined systems.)
There was a problem hiding this comment.
Cell broadcast is standardized, so it was easy to find the 5 kinds of alerts that can be sent via cell broadcast, and it made sense to add them here as they are unlikely to change.
Cell broadcasts has a lot of possible channels, also additional information on whether this should be a popup or not. As the apps that provide that information will be rather a few than many woudln't it be better to have this in a separate portal that is then also easier to tweak rather than in a very generic portal used by many apps that will be harder to change / agree on changes?
Co-authored-by: Markus Göllnitz <[email protected]>
|
|
||
| The format of the serialized notification is a vardict, with | ||
| the following supported keys, all of which are optional: | ||
|
|
||
| * ``application-id`` (``s``) |
There was a problem hiding this comment.
Why have this property? Isn't it already picked up for flatpak? Or it is not retrieved in case of postfix? What is the goal?
The description is also confusing: mandatory, optional, with optionally a postfix...
There was a problem hiding this comment.
Flatpaks: We can get an app-id from Flatpak, so it's optional to specify it here. But if you want to ship a app-id w/ postfix, we can't automatically determine it so you must specify it
Non-flatpaks: We can't get an app-id from anywhere so it's required
IMO I agree that it is a bit complicated seemingly pointlessly. We can probably just mark it required in the spec and just error out if a Flatpak tries to lie about who it is
There was a problem hiding this comment.
What about desktop files if an app is lying (assuming the app isn't sandboxed and can perhaps guess installed apps)? Furthermore, shouldn't such identification be elsewhere than in a specific portal?
There was a problem hiding this comment.
What about desktop files if an app is lying (assuming the app isn't sandboxed and can perhaps guess installed apps)? Furthermore, shouldn't such identification be elsewhere than in a specific portal?
Host applications don't need to guess they can just look up the desktop files. We can't force anything on them.
I think renaming this to desktop-file-id makes the distinction between app id and this property much better. We can have something similar to already existing portals https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.DynamicLauncher.html
There was a problem hiding this comment.
What is the purpose of this? If it's about getting the app name, this might be problematic if the app is lying, because the app name is useful for users to attribute a problem to the correct app. However, I don't know what the current status of notifications is with non-sandboxed apps.
|
|
||
| Enable the speakerphone for the ongoing call. | ||
|
|
||
| * ``call.disable-speakerphone``: |
There was a problem hiding this comment.
As mentioned in the other thread, we should be able to pause/unpause the call
I also think it makes sense to give a mute/unmute button too
|
|
||
| Intended for alarm clock apps | ||
|
|
||
| * ``call.incoming`` |
There was a problem hiding this comment.
call.incoming.video?
I guess my video call proposals would require more work in the spec, for example to pass around camera preview FD and such
|
|
||
| * ``bytes`` (``ay``) | ||
|
|
||
| A bytes sound containing a bytestring with the sound data. |
There was a problem hiding this comment.
sound data in what format? MP3? OGG? Raw PCM?
There was a problem hiding this comment.
OGA and WAV, in "Supported image formats" (wrong word). 😉
| A bytes sound containing a bytestring with the sound data. | ||
|
|
||
| This is the same format as a serialized `GBytesIcon | ||
| <https://docs.gtk.org/gio/class.BytesIcon.html>`_. |
There was a problem hiding this comment.
this is unclear. The docs you're linking here talk about GBytesIcon holding a "common image file format like PNG". Doesn't make sense for sound bytes...
There was a problem hiding this comment.
The sound property inspired by GIcon and has mostly the same serialization format. GBytesIcon don't actually care about the content they don't even know about it. But yes reading this sounds odd.
|
|
||
| Additional types may be defined by notification servers. | ||
|
|
||
| * ``sound`` (``v``) |
There was a problem hiding this comment.
Did you mean (sv) here? rather than just v and then saying it's an (sv) below?
There was a problem hiding this comment.
The idea is to make it the same structure as icon just to reduce confusion, but the wording cold be better especially if we really go with the slient sound thing.
| This can be a long description but note that if it is too long | ||
| it may not be fully displayed. | ||
|
|
||
| Any markup is removed from the string including new lines. |
There was a problem hiding this comment.
This makes it sound like if the client gives a string like <i>foobar</i> the notification server will just render foobar (just without making it italics). That's not what we want, though. We want an app to say <i>foobar</i> and the server should render <i>foobar</i>
There was a problem hiding this comment.
the idea is to filter out markup like FDO notifications requires servers to do.
That's not what we want, though.
@AdrianVovk What is the reason we wouldn't want that?
There was a problem hiding this comment.
Let's say I'm a chat app, sending notifications of user chats. I don't want to think about markup, so I just pipe the message text directly into the body of the notification. But instead of presenting what I need the server mangles it
The only way to send a notification where the body won't be mangled by the server is to escape the markup then pass it to body-with-markup. This makes body-without-markup a lot less useful, IMO. Apps that don't wish to be aware of markup cannot just ignore it, because the server will change message contents if they aren't markup-aware
Also, implementation-wise, filtering out the markup is difficult. It's one thing to parse it and render it (code exists to do that in Pango!) it's a whole other thing to parse it and throw it out (somehow...)
The o.f.Notifications spec doesn't have a separated Body vs Body-with-Markup, and instead just always does body-with-markup. So it makes sense there for markup to be ignored and stripped out if it's unsupported. If an app sends text via body-without-markup, it expects the text to be displayed unprocessed. If the app sends text via body-with-markup, the text it wants to show is contained within the markup tags and the app doesn't expect the tags themselves to be visible, so the server filters them out if it can't actually render them
There was a problem hiding this comment.
i actually implemented it already, but this sounds like it makes a lot of sense to pass body unseen.
| Any markup not supported, e.g. new lines, will be removed from | ||
| the string. In the future, the set of supported markup may be extended. | ||
|
|
||
| This can be a long string but note that it may not be fully displayed. | ||
|
|
||
| * ``icon`` (``v``) |
There was a problem hiding this comment.
As I mention below with the sound file, should we just specify this as (sv) rather than saying it's a v?
There was a problem hiding this comment.
we can't change that, to not break compatibility. The wording could maybe be better.
| The priority for the notification. The notification server may | ||
| ignore this property if it has it's own policy. | ||
|
|
||
| Supported values: | ||
|
|
||
| - ``low`` | ||
| - ``normal`` |
There was a problem hiding this comment.
(GitHub isn't letting me add a comment on default-action so I'll add it here)
I think we should specify that incoming call notifications aren't allowed to have default-actions. Same with incoming alarms. That way we'll be able to do the whole "clicking a notification opens the full-screen incoming call/alarm UI"
| A serialized icon to be added to a button. The format for | ||
| is the same as for the notification ``icon``. | ||
|
|
||
| * ``purpose`` (``s``) |
There was a problem hiding this comment.
Should notification servers be allowed to imply label/icon based on purpose?
In other words, if you have an incoming call should the app be allowed to say just purpose: call.accept and omit label or icon, and safely assume that the notification server will have a default string to answer / decline the call? Or should the app always set a label if it really wants the action to show up?
There was a problem hiding this comment.
that's the reason why i removed the mandatory part of the label and action property. In general the app should still set a label because the server may not understand the purpose or need it even when the button has a purpose.
There was a problem hiding this comment.
I don't know if having a way to fallback to a generic notification (i.e. presenting a normal button) is a good idea. One of the purposes of having specific types of notifications is to provide the user with the option to turn them off. Therefore, notifications must be identifiable as such thanks to their style. If a notification server doesn't support it, then adds their support, then that server should remove their normal display - probably not nice in terms of transition.
However, it is worth noting, in light of @AdrianVovk's proposal regarding apps on the lock screen, that it might not be possible to display the app itself if we think about ensuring privacy (e.g. speaker and microphone toggle, maybe don't show name of important contacts). I mention this because app developers in this case may want to customize the system-styled notification (e.g. using colors), which may or may not impact identification.
There was a problem hiding this comment.
One of the purposes of having specific types of notifications is to provide the user with the option to turn them off
Hmm? No? If a notification server supports incoming call notifications, I don't think it makes much sense to disable support for incoming call notifications. The server either supports them or not
Also Jonas wasn't interested in trying to filter groups of notifications from apps. Apps will either be able to send all notifications or no notifications
If a notification server doesn't support it, then adds their support, then that server should remove their normal display - probably not nice in terms of transition.
This is fine. Software and UI is updated all the time. Presumably updates made by the notification server will improve the UI, and make the notifications better to use, not worsen it.
Notifications servers that don't support a custom UI yet can trivially fall back to generic notification with generic action API. That's simply the best we can do while ensuring the notification is delivered
However, it is worth noting, in light of @AdrianVovk's proposal regarding apps on the lock screen, that it might not be possible to display the app itself if we think about ensuring privacy (e.g. speaker and microphone toggle, maybe don't show name of important contacts).
Sorry I'm confused... Where is the conversation about showing apps themselves coming from?
I mention this because app developers in this case may want to customize the system-styled notification (e.g. using colors), which may or may not impact identification
That's fine. Apps can send whatever information they want to us, like colors/whatever customizations, and we can choose whether or not to present them
There was a problem hiding this comment.
Action property should still be mandatory, no?
If an app says "I support doing this" it needs to be able to actually do it when necessary. What is the server supposed to do if the action property is missing? How is it supposed to notify the app about the action?
There was a problem hiding this comment.
Action property should still be mandatory, no?
Yeah probably.
There was a problem hiding this comment.
Hmm? No? If a notification server supports incoming call notifications, I don't think it makes much sense to disable support for incoming call notifications. The server either supports them or not
Also Jonas wasn't interested in trying to filter groups of notifications from apps. Apps will either be able to send all notifications or no notifications
I thought of that at first, as this was in my mockups to offer a global experience of notifications (https://gitlab.gnome.org/Teams/Design/whiteboards/uploads/cd2437eaa7f0bb486adc9fb67fb4064a/NotificationProfilesv3.png). However, if an app supports multiple types of notifications, users may still want to not receive some of them. In case of calls, maybe someone wants to never have video call (or not activate the camera accidentaly) and just receive audio calls? Also: what about other desktops? what if the app has other notification types (don't know which, but who knows...) [here for managing]?
This is fine. Software and UI is updated all the time. Presumably updates made by the notification server will improve the UI, and make the notifications better to use, not worsen it.
Notifications servers that don't support a custom UI yet can trivially fall back to generic notification with generic action API. That's simply the best we can do while ensuring the notification is delivered
That does not resolve the privacy issue if apps can do what they want: with a no-constrained type they have no obligation to offer speaker and microphone enabling/disabling.
Sorry I'm confused... Where is the conversation about showing apps themselves coming from?
I re-read, and misinterpretation, sorry. I mixed that with the other apps (calculator, etc.).
There was a problem hiding this comment.
I thought of that at first, as this was in my mockups to offer a global experience of notifications (https://gitlab.gnome.org/Teams/Design/whiteboards/uploads/cd2437eaa7f0bb486adc9fb67fb4064a/NotificationProfilesv3.png).
That mockup seems really complicated and probably better served by something like https://gitlab.gnome.org/bertob/app-ideas/-/issues/247
In other words, GNOME can have basic on/off switches for things like DND, but no support for automating any of it. Instead, we have this "Routines" app that lets you really automate it however you want
However, if an app supports multiple types of notifications, users may still want to not receive some of them. In case of calls, maybe someone wants to never have video call (or not activate the camera accidentaly) and just receive audio calls? Also: what about other desktops? what if the app has other notification types (don't know which, but who knows...) [here for managing]?
I think it's too blurry to ban notifications based on their content type. We either need the app to give us the purpose of the notification (Android calls this "notification channels") so we can toggle them on/off individually, or we don't do it at all and let the app decide what notifications it sends or if it can send notifications at all (thus making our lives easier and nudging apps towards not sending spam notifications lest they get muted entirely by the user)
That does not resolve the privacy issue if apps can do what they want: with a no-constrained type they have no obligation to offer speaker and microphone enabling/disabling.
We can't force apps to support these things anyway. I don't think we should interfere here. If the app doesn't support it users will probably avoid it naturally. We can't solve all privacy issues with API
There was a problem hiding this comment.
As far as I know, there are currently no such notifications; they can therefore be implemented. Additionally, if we can communicate with a stylized notification (how to give permission is currently unknown) and with specific (non-custom) buttons, permission (purpose of portals) can be granted for audio (speaker and microphone) and the camera when the relevant buttons are pressed. The permission can be revoked by clicking on it again and automatically at the end of the call. By having them as generic notifications because support for their content type is lacking, how can we reliably grant permission due to this lack of support? Also, if an app wants to be sandboxed by supporting the content types, it cannot have such dynamic permission, or it means giving the app permission to always access the speaker and the microphone when launched or to have differentiated management of permissions (dynamic if content type supported, general if content type not supported).
There was a problem hiding this comment.
Also Jonas wasn't interested in trying to filter groups of notifications from apps. Apps will either be able to send all notifications or no notifications
(I seem to have misread)
It makes sense to let apps send notifications if they have them. But, regardless of whether the type of content is used or not, this means that the app must first have permission to use the microphone (do we have a portal for this?) and the appropriate camera.
However, having a notification that allows to dynamically manage permissions (audio, video) is better in my opinion because more things can be offered (privacy, buttons do what they say, simply take advantage of dynamic permissions). Is this intended if content type is used?
| A serialized icon to be added to a button. The format for | ||
| is the same as for the notification ``icon``. | ||
|
|
||
| * ``purpose`` (``s``) |
There was a problem hiding this comment.
We should specify explicitly that the purpose allows the notification server to completely ignore any specified label or icon, or any other thing about presentation.
For example, in my call-waiting proposal sometimes call.accept will be displayed as two distinct actions: "Hold and Accept" or "End and Accept". We cannot use the app's label in this case. IMO we shouldn't ever use the app's label/icon for things like incoming calls
|
|
||
| Intended for call apps to notify the user about an incoming call. | ||
|
|
||
| This type has the following button purposes: |
There was a problem hiding this comment.
These can be used as action purposes too, right? We should specify that
There was a problem hiding this comment.
no, actions have a different set of purposes. Maybe action's purpose field should have a different name to make the distinction clear.
There was a problem hiding this comment.
ok then for the call-waiting thing we'd need to define an action for ongoing-call notifications to put the call on hold
There was a problem hiding this comment.
But I'm not really sure why we should have necessarily separated purposes for actions and buttons. Buttons are just actions that we try to show in the notification's UI (especially if the notification server doesn't know about the notification's content type).
There was a problem hiding this comment.
they are pretty different. buttons are always be buttons in the ui, but the placement, styling or labeling may be different then a "normal" button. actions on the other hand are ways to allow the notification server to communicate to the app. Look at the two options we have right now, they can't be displayed as buttons ever.
|
|
||
| * ``vibration`` (``au``) | ||
|
|
||
| Vibration pattern is an array of uint32 to describe |
There was a problem hiding this comment.
Hmm maybe an example here could be useful? Or is the link to the web vibration API enough?
| The priority for the notification. The notification server may | ||
| ignore this property if it has it's own policy. |
There was a problem hiding this comment.
Although this is not a new property and is perhaps a clarification of the documentation, I think ignoring this property would not encourage app developers to use it in case of a cross-desktop UX is wanted. For this, it makes it useless.
Regarding this version of the portal, a priority does not seem necessary or is inherent to the content type, e.g. alarms. If you agree on that, then maybe ignore it or say not to use it when using a content type.
|
For buttons, if custom buttons are ultimately allowed in addition to those added due to content type, perhaps have a limit on their total number. |
|
|
||
| Intended to be used to display tests broadcasted by the cell network. | ||
|
|
||
| * ``os.battery.low`` |
There was a problem hiding this comment.
For applications? If yes, case examples.
|
|
||
| A file descriptor to a sound file. | ||
|
|
||
| * ``silent`` |
There was a problem hiding this comment.
I assume it's for alarms, but, referring to the alarm example mentioned in the issue, it doesn't make sense to me to have one or more alarm notifications in the tray. This risks overloading it or there is wasted space if grouped.
If there are no other cases, then this property should not exist. This is an implicit property for an alarm.
There was a problem hiding this comment.
I mean, still using the example of alarms, it's up to the system to decide where to draw a pending alarm. This is not something an app should control.
There was a problem hiding this comment.
Silent notifications can be used for lots of other things...
"Hey you should reboot your device for an update" should be a silent notification
"hey your ebike battery is running low, you should make sure to charge it" from your bike's companion app is a non-time-sensitive notification that doesn't warrant a noise but still should be a notification just in case the user really needs that reminder
"you have data left over from 15 uninstalled apps, click here to manage" should be silent too.
I can come up with infinitely more use-cases for silent notifications. They're necessary...
There was a problem hiding this comment.
Your examples make sense, but the user may want to be notified with a sound when the battery is low, depending on what is important to them or when they is away from their device. Also don't forget one of the keys: user control.
|
|
||
| This is a similar API to `Web Vibration API <https://developer.mozilla.org/en-US/docs/Web/API/Vibration_API>`_. | ||
|
|
||
| * ``led-color`` (``(yyyy)``) |
There was a problem hiding this comment.
Maybe add a pattern for a silent mode. Colors + alternation between increasing and decreasing brightness, with durations. Brightness intensity (if applicable) should be done on the system side.
|
Additional purposes and types. As far as I know there is nothing in the portals that cannot be evaluated. I believe this idea will be rejected. For vibration and LED color, how can apps present users with an interface to set a custom pattern/color, choose one, or test it? |
| * ``hide-on-lockscreen`` | ||
|
|
||
| Don't show the notification on the lockscreen. | ||
|
|
||
| * ``hide-content-on-lockscreen`` | ||
|
|
||
| Only show the notification ``title`` and ``icon`` on the lockscreen. |
There was a problem hiding this comment.
I'm really wondering how this is user defined, since it's the user's decision whether to show a notification on the lock screen and whether or not to hide the body (and some buttons?). I think this is something that should be controlled by the system through content type or with hints (e.g. calendar type for event notifications - just an example here as these notifications are not covered here).
If you have another idea on how to handle this, please explain. Indeed, when it comes to privacy, I think we need reliability: a mistake or bad behavior is not tolerated.
There was a problem hiding this comment.
Nack. Apps should be able to say that their content is sensitive no matter what the notification server thinks about it, and if the user configures their notifications to appear on the lock screen an app should be able to say "no no, this is actually really sensitive"
There was a problem hiding this comment.
As for controling these things by content type, that's a bad idea. What if I have two calendars, one that's not sensitive for work things and reminders, and another that's sensitive for personal life things? I don't want my personal calendar notifications to appear on the lock screen, but the non-senstiive work/reminder ones should for convenience. Apps should be able to decide how sensitive their content is
If we tie show-on-lockscreen to the content type, we're painting ourselves into a corner: apps sending similar notification types in different situations won't be able to define different behavior
There was a problem hiding this comment.
Adrian, that's the example I have in mind because I worked on that, but they aren't an object of discussion here. Besides you already have the response on how I manage that in the mockup I linked.
If we tie show-on-lockscreen to the content type, we're painting ourselves into a corner: apps sending similar notification types in different situations won't be able to define different behavior
With a global only configuration of notifications, yes we have a problem. However, this problem is resolved by making this setting available per app (which makes sense as it is a per app setting).
Also, for me, sensitive information need reliability, I think we need an interface to agree to let the information be displayed or not. Having notification content type is then needed to have a revocable setting (knowing that we need to define theses types).
You have examples on how I define importance (priority) and sensitivity in the following issues: #1025 and #1026. If you have comments, please comment on those instead to avoid a possible huge flow of comments.
an app should be able to say "no no, this is actually really sensitive"
I'm not against having apps defining such setting if there are cases for that, but examples are needed then. The thing is that a fully controlled app setting also need to be user-controlled (relative to what I already said on sensitivity).
| @@ -53,37 +53,111 @@ | |||
|
|
|||
| The ID can be used to later withdraw the notification. | |||
| If the application reuses the same ID without withdrawing, | |||
| the notification is replaced by the new one. | |||
| the notification is updated with the new one. It's possible | |||
| to set a ``display-hint`` to animate replacing the notification | |||
There was a problem hiding this comment.
| to set a ``display-hint`` to animate replacing the notification | |
| to set a ``show-as-new`` ``display-hint`` to animate replacing the notification |
| There is no reason to set this property if the application uses Flatpak and no postfix is set. | ||
| E.g ``org.libreoffice.LibreOffice.Writer`` where | ||
| ``org.libreoffice.LibreOffice`` is the flatpak application ID. | ||
| If this property isn't set it will be picked up automatically, if possible. |
There was a problem hiding this comment.
Isn't that last sentence redundant. Either it's mandatory (non-flatpak) or not (flatpak).
|
|
||
| The format of the serialized notification is a vardict, with | ||
| the following supported keys, all of which are optional: | ||
|
|
||
| * ``application-id`` (``s``) | ||
|
|
||
| An optional application ID for Flatpak applications, otherwise it's mandatory. |
There was a problem hiding this comment.
Wouldn't it be simpler to always require it and have flatpaks provide the proper value?
| * ``title`` (``s``) | ||
|
|
||
| User-visible string to display as the title. | ||
| The title should be a short string, if is too | ||
| long it may not be fully displayed. |
There was a problem hiding this comment.
What does too long mean? How would an application developer make sense of this information?
There was a problem hiding this comment.
I think that's entirely up to the notification server that will be displaying the notification. So we can't specify what "too long" means here. It means however much fits in the UI of the server
App developer needs to understand that they should avoid sending lots of text. They'll probably want to test the notification on the common desktops
Android doesn't have a defined limit either. It just says that
By default, the notification's text content is truncated to fit one line
We could probably specify something similar
There was a problem hiding this comment.
👍 That would at least give an idea.
There was a problem hiding this comment.
They'll probably want to test the notification on the common desktops
For app developers, I think it would be better for them to avoid testing on different desktops, so taking into account different ways of presenting. Remember that Android has the advantage of just having one thing, not multiple. Also, the developers needs to know what a common desktop is.
Android doesn't have a defined limit either. It just says that
By default, the notification's text content is truncated to fit one line
That's a start. The other concern, if we want to avoid app developers having to test their notifications on multiple DEs, is if there is a way for all text to be displayed (i.e. will all text be displayed?). In GNOME, Julian implemented a button to expand a notification.
| User-visible string to display as the body. | ||
| User-visible string to display as the body of the notification. | ||
| This can be a long description but note that if it is too long | ||
| it may not be fully displayed. |
There was a problem hiding this comment.
What does too long mean? How would an application developer make sense of this information?
| This is the same format as a serialized `GBytesIcon | ||
| <https://docs.gtk.org/gio/class.BytesIcon.html>`_. | ||
|
|
||
| * ``file-descriptor`` (``h``) |
There was a problem hiding this comment.
Is it the responsibility of the receiver to close the file handle? What are the lifetime guarantees for reading the file handle?
There was a problem hiding this comment.
When sending a file handle over dbus it is always the responsibility of the receiver to close the file handle because you get a duplicate. This is true for at least gdbus and sd-bus
Wdym by lifetime guarantees? As long as the FD is open it's possible to read from it - enforced by the kernel
There was a problem hiding this comment.
When sending a file handle over dbus it is always the responsibility of the receiver to close the file handle
I'm aware but would have spelled it out. Looking through other protocols that doesn't seem to be the case there either though so I guess it's fine.
Wdym by lifetime guarantees? As long as the FD is open it's possible to read from it - enforced by the kernel
I was thinking about pipes or similar but rereading the spec it says "to an image file" so that's likely fine too. Thanks for pointing me at it.
There was a problem hiding this comment.
Probably works for pipes too. If you open an anonymous pipe, write into the write end, and hand the read end over dbus, then exit the program, I think the kernel will keep the written data in a buffer in memory until the FD is either closed or read from...
| The priority for the notification. The notification server may | ||
| ignore this property if it has it's own policy. | ||
|
|
||
| Supported values: |
There was a problem hiding this comment.
What would a notification server do with a low priority? Not show a banner?
| * ``cellbroadcast.danger.extreme`` | ||
|
|
||
| Intended to be used to display extreme danger warnings broadcasted by the cell network. | ||
|
|
||
| * ``cellbroadcast.danger.severe`` | ||
|
|
||
| Intended to be used to display severe danger warnings broadcasted by the cell network. | ||
|
|
||
| * ``cellbroadcast.amberalert`` | ||
|
|
||
| Intended to be used to display amber alerts broadcasted by the cell network. | ||
|
|
||
| * ``cellbroadcast.test`` | ||
|
|
||
| Intended to be used to display tests broadcasted by the cell network. |
There was a problem hiding this comment.
Cell broadcast is standardized, so it was easy to find the 5 kinds of alerts that can be sent via cell broadcast, and it made sense to add them here as they are unlikely to change.
Cell broadcasts has a lot of possible channels, also additional information on whether this should be a popup or not. As the apps that provide that information will be rather a few than many woudln't it be better to have this in a separate portal that is then also easier to tweak rather than in a very generic portal used by many apps that will be harder to change / agree on changes?
|
|
||
| This is a similar API to `Web Vibration API <https://developer.mozilla.org/en-US/docs/Web/API/Vibration_API>`_. | ||
|
|
||
| * ``led-color`` (``(yyyy)``) |
There was a problem hiding this comment.
Different devices have different leds. Wouldn't it be better to specify the led type (e.g. the notification led) and have the device pick the right color? Also in most cases it would likely be better to have the notification server pick the right feedback for an event and to use this only for overrides which then would be good to spell out here.
There was a problem hiding this comment.
Wouldn't it be better to specify the led type (e.g. the notification led)
Isn’t it up to the device to use the right LED?
There was a problem hiding this comment.
But what if the right LED if you just give a color if it's not a RGB LED but e.g. a single color status LED. Also you can't give a pattern (as you note). You can also have multiple LEDS in different positions (front/back of the device). That's why I think it's better to say: I'd like to have feedback for this type of notification/event.
Maybe:
If the device has an status LED this is meant as an override for the default LED feedback picked by the notification server. The color pattern might not be representable by the device. The notification server will pick an appropriate, user visible LED if possible.
There was a problem hiding this comment.
Sorry, I'm not sure I understood what you said correctly.
For me, it's :
- Let the server choose the correct LED for feedback.
- For a pattern, let the app specify the colors, then let the server ignore the colors if applicable. If a LED can't handle brightness (like screen brightness), then turn the LED on and off (note: I don't know much about all the LEDs on a smartphone). The use of pattern is reserved for alarms and calls (for a generic notification, logically it is perhaps leaving the LED on?).
Does this correspond to what you want?
There was a problem hiding this comment.
I mean:
- if the app doesn't set
led-color: let the server pick a suitable led, color and pattern - if the app does specify a LED color and the device has a matching LED (either RGB or a fixed color LED matching the color) use that
- if there's no matching LED do the same as in 1.
The use of pattern is reserved for alarms and calls
Is that in the protocol? What about different patterns for SMS and IMs which is e.g. something I use to see at a glance what needs attention without even unblanking the phone's display.
There was a problem hiding this comment.
If the server handles things, no problem. I also have the idea of using the screen brightness to imitate a LED; maybe this can also be a fallback?
The use of pattern is reserved for alarms and calls
Is that in the protocol? What about different patterns for SMS and IMs which is e.g. something I use to see at a glance what needs attention without even unblanking the phone's display.
No, it is not in the protocol, just that it is for me equivalent to a long duration sound (for example a song for a call). That said, if it's important ("needs attention"), it makes sense to use patterns. To define such importance, I thought of using contacts.
|
|
||
| Intended for call apps while a call is ongoing. | ||
|
|
||
| This type has the following button purposes: |
There was a problem hiding this comment.
Instead of trying to munge the call interaction with all it's subtleties into a generic notification API wouldn't it be better to have a specific interface/portal for that? The receiving side is then free to display things in the same way as a notification but that shouldn't be a requirement. Things like switching ongoing calls between different "call providers" (say matrix, signal and regular phone calls) will otherwise be more limited than they need to be. Same goes for audio device selection, etc.
There was a problem hiding this comment.
This notification portal (w/ the small changes I'm asking for) is pretty much a superset of CallKit, which is Apple's special API for dealing with call interaction. In other words, this portal can do everything CallKit can do, and conversely any API we come up with trying to emulate CallKit will end up mostly being a duplicate of this notifications portal. So I see no reason to try and separate the two
There was a problem hiding this comment.
Are we talking about https://developer.apple.com/documentation/callkit ? That has a much wider scope like blocking incoming calls, etc.
There was a problem hiding this comment.
@agx: You can read discussion from https://github.com/flatpak/xdg-desktop-portal/pull/1304/files#r1532019682. We have a different understanding of what this portal is supposed to do.
There was a problem hiding this comment.
Yes I'm talking about CallKit
and no, the scope isn't really that much wider. In theory sure it's a dedicated API to do all these things with calls. But if you look at how it's actually implemented: the app tells CallKit when a call is incoming, or when the app is in an ongoing call. It gives the server a list of actions that the app knows how to handle. The server, in response, implements everything by triggering these actions through the app. This setup just so happens to be extremely similar to this notifications API.
The server side can then implement whatever it wants: cross-app call waiting, do-not-disturb but allowing repeated callers, special incoming and ongoing call UI (that's what content-type is for, after all), etc. If the server side doesn't care then you'll still get basic notifications and bare-minimum functionality for call apps.
There was a problem hiding this comment.
This is the incoming call side. As far as I can tell callkit also handles the outgoing side as well, handles group calls dtmf, etc.
That's why I think it makes more sense to have a call specific portal rather than trying to match it to "notifications" with varying results depending on what the notification server actually implements. If we ever want sandboxed apps to do phone calls without exposing MMs API we need a call specific portal (which is even more desirable if that calls app is e.g. allowed to display content on/above the lock screen).
Initially this "calls" portal might only cover the call specific bits from this MR but it would give us the possibility to add more call specific features that don't map to notifications (like outgoing calls, joining calls together, emergency calling, etc).
There was a problem hiding this comment.
I believe the problem is about how things are structured. When doing a portal, it is generally around a case (or multiple cases that can be grouped) and we have the following structure: method + method properties - which will translates here as, e.g.:
- AddIncomingCall (the method)
- @ contact_id
- @ contact_image
- @ sound: system, ring/song, custom [radio, stream]
- @ vibration_pattern
- @ led_pattern
- @ buttons (supported standardized buttons - perhaps not needed if using standardized buttons with dynamic permissions)
- @ custom_buttons (additional non-standardized buttons - if needed, can only open the app, not available on lockscreen; e.g. opening contact list or just the app)
- All relevant signals depending on what button is activated in order to call another method, e.g. AddOngoingCall, etc.
This also offers clarity when reading the documentation. Here, we have multiple properties that seems structurally disorganized.
There was a problem hiding this comment.
This is the incoming call side. As far as I can tell callkit also handles the outgoing side as well, handles group calls dtmf, etc.
This handles the ongoing call side too! Note the ongoing call content type
Also, CallKit handles DTMF because CallKit is actually what renders the in-call UI for the Phone app on iOS. It's really strange. We're not interested in doing it that way. So we don't need to handle those things
That's why I think it makes more sense to have a call specific portal rather than trying to match it to "notifications" with varying results depending on what the notification server actually implements.
The varying results is exactly what we want, though. We want Skype / Viber / whatever apps to be able to say "hey I'm in an ongoing call" and expect that at least some UI will appear, even if that UI is just a basic notification that everyone has supported forever. Desktop environments that don't care should retain basic functionality
If we ever want sandboxed apps to do phone calls without exposing MMs API we need a call specific portal (which is even more desirable if that calls app is e.g. allowed to display content on/above the lock screen).
The calls app cannot be sandboxed, especially on systems using home directory encryption. It'll be baked into the OS image.
I don't think having a portal to make actual phone calls makes sense. I can't think of any use-case for 3rd party phone apps that aren't solved by the fact that our OS is open source. On proprietary OSs people want third party phone apps to handle missing features from the built-in one
I don't think CallKit lets your app make actual phone calls via the SIM card. CallKit is only a framework for letting apps report to the OS that there's an incoming/ongoing (VOIP/whatever) call and expose some basic controls, no more.
Initially this "calls" portal might only cover the call specific bits from this MR but it would give us the possibility to add more call specific features that don't map to notifications (like outgoing calls, joining calls together, emergency calling, etc).
Ongoing calls do map to notifications. You can't join calls cross-app, and if you're within an app I see no reason for the OS to even know about it. Not sure what you mean by emergency calling - how is that a portal?
There was a problem hiding this comment.
Thanks for the details. I'm aware it does ongoing. I'm after outgoing. This is needed for e.g. quick dialers (which people already implemented) or a separate UI on the car's dashboard when doing Android Auto.
I don't think CallKit lets your app make actual phone calls via the SIM card.
I don't think so either. What I mean is that we currently need to expose all these things to the sandbox if we want to initiate a call. That's why I think a call related portal (which would then also handle the outgoing / ongoing signalling in this portal would make sense.
There was a problem hiding this comment.
Based on the Inhibit flag exported by KDE via DBus in org.freedesktop.notifications, it would be nice to be able to see in the current proposal whether DND is currently active or not.
| * ``transient`` | ||
|
|
||
| The notification is displayed only as a banner and won't be kept | ||
| by the server in a tray. | ||
|
|
||
| It's a programmer error to specify ``tray`` at the same time. | ||
|
|
||
| * ``tray`` | ||
|
|
||
| No banner for the notification will be displayed and | ||
| the notification is placed in the tray. | ||
|
|
||
| It's a programmer error to specify ``transient`` at the same time. | ||
|
|
||
| * ``persistent`` | ||
|
|
||
| Make the notification persistent in the notification tray. | ||
| The user can’t dismiss it using the usual close button or gesture. | ||
|
|
||
| Apps are only allowed to display persistent notifications | ||
| as long as they have a window. Once the last window of an app | ||
| is closed the persistent notification will be removed. |
There was a problem hiding this comment.
- "tray" and "persistent": Apps shouldn't have control over notification UX. If you don't agree, please give example cases for those.
- "transient": Also part of notification UX. However, it seems to be a content type to display, e.g., an action like paste has been done (here equivalent of in-app notification). I don't know what really to think about this, so examples are also welcome here.
This is to be considered the direction I will move the notification portal to.
But it's implementation won't happen in this pull request.
This takes the discussion in
#983 and turns it into an actual possible v2 of the notification interface.
The permission part was intentionally left out since it's tangential to the new properties and features proposed here.
CC: @jonas2515