Home · All Namespaces · All Classes

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:

notificationmanager.png

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

This sink will create a transparent window of type _NET_WM_TYPE_NOTIFICATION and sequentially displays an MBanner for all the queued notifications in that window. MCompositor will identify the notification window by the window type and is responsible for showing the notification window on top of any application. MCompositorNotificationSink hides the notification window after all the currently queued notifications have been shown.

Disabling notification previews

MCompositorNotificationSink can be prevented from showing its window and the banners in two ways:

NGFNotificationSink

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
persistent=false

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.

The genericTextId key and the genericTextCatalogue key can be used to define the translation ID and the translation catalogue of a generic text for the visual notifications of the given type. This generic text can replace the notification content when showing the content is not desired, for instance when the device is locked and privacy is of concern. Both keys are needed to define the generic text. Otherwise the generic text is considered to be empty. The translated string is retrieved from the provided catalogue in either singular or plural form depending on the cardinality of the particular notification. Once the translated string is retrieved the escape sequences "%n" and "%Ln" of the returned string are replaced with the cardinality of the notification. For more information on how translations are provided refer to "internationalisation" in libmeegotouch documentation.

Setting the persistent key to false will discard notification of given event type when device is rebooted. Defaults to true if left out.

Links

See also:

Copyright © 2011 Nokia Corporation Generated on Tue Aug 30 2011 16:38:12
Doxygen 1.7.1
MeeGo Touch