breadcrumbs: Design Documents > chromium_link: Chromium chromium_os_link: Chromium OS home_link: Home page_name: desktop-notifications title: Desktop Notifications title_hdr: |
See also: API Specification for notifications
Design for desktop notifications The Desktop Notifications API allows script to request a small toast to appear on the desktop of the user. The contents of the toast can either be specified as iconUrl/title/text strings, or as a URL to a remote resource which contains the contents of the toast. In Chromium/WebKit, the API is provided to scripts in WebCore by injecting into WebKit (via the Chrome/ChromeClient objects) an implementation of a NotificationPresenter interface, which contains methods to show and cancel toasts, as well as to check and request permission to show toasts. These calls flow via IPC from the renderer process to the browser process, where the toasts are actually created on the screen using a small HtmlView. Event feedback Several events flow in the opposite direction: when a notification is displayed (it may not be immediate if the screen is cluttered), closed, or encounters an error, an event is fired which can be listened for by javascript. These events are detected in the browser process and flow back to the renderer instance which owns the notification object. Tracking is done by notification-id counters in each renderer process, and a map within the browser process which associates a toast on the screen with the corresponding renderer-process-id and notification-id. Since the renderer process chooses the id, the IPC involved can be asynchronous. Lifetime considerations If a page which is showing a desktop notification is closed, the toast should not be automatically removed from the screen. However, as the javascript Notification object has gone out of scope, Chromium must not attempt to invoke events on it. The NotificationPresenter interface supports this via a notificationObjectDestroyed() method which must be called from WebCore when a Notification object is destroyed. For this reason, the renderer process's NotificationPresenter keeps a map of its notification-id values to Notification object pointers; if a Notification pointer goes out of scope, the NotificationPresenter is called and removes that pointer from the map. If the browser subsequently calls with an event on that id it will be ignored.
Calling from JavaScript to create a notification: NotificationCenter object in WebCore v (returned by DOMWindow::webkitNotifications()). v v V8 bindings v WebKit::NotificationPresenterImpl v (WebKit API object which adapts between WebCore::NotificationPresenter interface and matching WebKit API interface) v RendererNotificationPresenter (implements WebKit::WebNotificationPresenter interface, object owned by WebViewDelegate implementation; sends IPC messages to browser, allocates IDs, stores map of ID->Notification objects) Calling back into JavaScript to relay notification events: RendererNotificationPresenter v (receives IPC message from browser process regarding an event) v v (post task onto main thread: lookup in notification-id->Notification object map, discard if invalid) v WebKit::WebNotification (PIMPL wrapper in WebKit API for WebCore::Notification object) v v (invoke event listener) v Notification in WebCore