Notifications System Implementation

The notifications system is implemented by the system UI daemon. This page describes the architecture and internals of the notification system itself and is meant for those developing the notification system. Convenience classes for application developers willing to use the notification system are provided in libmeegotouch. If you're an application developer willing to use notifications, refer to the libmeegotouch documentation for more information. There's a separate page for notifications that contains all the necessary information. However, if you want to define new notification event types for your application, read on.

Components

The notification system is divided into three entities:

Notification sources - Notification sources observe events like D-Bus calls.
Notification manager - Manages the triggered notifications.
Notification sinks - Sinks act based on a notification. Sinks can for instance display a notification widget, play a sound or trigger tactile feedback.

Notification system structure

Notification sources

Notification sources are responsible for triggering notifications based on events and their internal logic. Notification sources are given a notification manager interface instance that they should use to trigger notifications. Notification sources inherit the NotificationSource interface.

Notification sources can use various means to decide whether notifications should be triggered. Notification sources can connect to backends like D-Bus. Notification sources can also publish D-Bus interfaces to allow external parties to launch notifications. The Galago Desktop Notification Specification can for instance be supported by a separate notification source in the system.

Notification manager

Notification manager (NotificationManagerInterface) defines an interface to create notifications. Notification manager interface object is passed to every NotificationSource for them to trigger notifications. Notification manager will create unique IDs for notifications and trigger notification sinks (NotificationSink) depending on the notification.

Notification manager queues notifications so that only one notification is triggered at a time. Notifications that are submitted when a notification is in process are appended to a queue which is then processed in first-in-first-out manner. Notification manager defines maximum size for the queue. If queue size is exceeded all incoming notifications are silently dropped. This is to avoid malicious software from flooding the notifications system and creating a denial-of-service scenario.

The NotificationManagerInterface also supports a concept of notification groups. A notification sender can create notification groups and subsequentially add notifications to the groups it has created. Notifications belonging to a group can be handled differently by some notification sinks. For example the NotificationAreaSink visualizes groupped notifications as a single element. The notification groups have group specific data which can be updated using the NotificationManagerInterface::updateGroup() method.

Notification sinks

Notification sinks (NotificationSink) get notified by notification manager when a notification they should act upon is triggered. Notification sinks can create various feedback when a notification is triggered. For instance a NotificationSink can create and show a notification widget, play a sound or launch haptic feedback upon a notification.

MCompositorNotificationSink communicates to MCompositor when a notification is triggered. This sink will create a special notification window and a MInfoBanner widget. A _NET_WM_TYPE_NOTIFICATION window hint is set to the created window. MCompositor will identify the notification window by the set window hint. MCompositorNotificationSink will handle the showing of preview icon in the notification preview. MCompositorNotificationSink will handle the interaction affecting the notification widget. MCompositorNotificationSink will also destroy the notification widget and close the notification window when required. Notification widget can be either cancelled or it can timeout. MCompositorNotificationSink will communicate the cause that closed the notification window to the MCompositor using custom X Atom. MCompositor is responsible for showing the notification window on top of any application as well as the transition animation of the notification window. After displaying the info banner the sink places the MInfoBanner widget onto the NotificationArea.

NGFNotificationSink (Non Graphical Notification Sink) integrates to the low level notification framework libngf to produce the required notification sound, vibrations, led indications etc. The NGFNotificationSink uses the feedbackId key from the event type to determine which feedback to request from the libngf.

Event types

The event type parameter of a notification is used to describe the overall properties of a notification, such as the icon, preview icon, sound, vibration etc. The event type is a string. Event types should be named using the Desktop Notifications Specification convention x-vendor.class.specific. x-vendor specifies the vendor extending the specification, such as x-nokia, class specifies the generic type of the notification, and specific specifies the more specific type of the notification. For each supported event type there is a configuration file in /usr/share/meegotouch/notifications/eventtypes that defines the properties for that particular type of event. The base name of the file defines the event type name: the properties for an event of type x-nokia.message.received are defined in /usr/share/meegotouch/notifications/eventtypes/x-nokia.message.received.conf and so on. Each configuration file consists of lines with key=value pairs. The keys are notification sink API parameter names such as iconId and feedbackId and the values are the values to be assigned to the notification sink API parameter defined by the key. An example configuration file could be as follows:

iconId=Icon-close
previewIconId=Icon-preview-close
feedbackId=press
userRemovable=false
class=system
genericTextId=qtn_something_happened
genericTextCatalogue=events

The iconId key can be used to define the ID of the icon displayed in the visual notifications of the given type. If the notification sink does not display any visual notifications it can ignore this key. As an example all classes derived from WidgetNotificationSink will use the iconId to show the icon in the notification banner.

The previewIconId key can be used to define the ID of the icon displayed in the preview of visual notifications of the given type. If the notification sink does not display any visual notifications it can ignore this key. As an example class MCompositorNotificationSink uses the previewIconId to show the icon in the notification banner preview.

The feedbackId key can be used to define whether a notification of given type produces a feed back. A notification sink may choose to diregard this key if it is not approprioate behaviour for that sink. As an example the NGFNotificationSink will use the feedbackId to play the associated sound, vibration or led indication or a combination of these. The NGFNotificationSink uses to play these indications.

The userRemovable key can be used to define whether a notification of given type is user removable when the user taps on the notification banner. If userRemovable equals false the notification will not be removed when the banner is tapped. The associated actions are executed but the application needs to remove the notification. If userRemovable equals true or the key is missing the notification is removed when it is tapped.

The class key can be used to define whether a notification of given type is a system notification or an application notification. If class equals system the notification is a system notification. It class equals application or the key is missing the notification is an application notification. System notifications may be treated differently by the notification sinks. For instance, system notifications are not displayed by the NotificationAreaSink. They may also have a higher priority than the application notifications.