1 ;;; notifications.el --- Client interface to desktop notifications.
3 ;; Copyright (C) 2010-2012 Free Software Foundation, Inc.
5 ;; Author: Julien Danjou <julien@danjou.info>
6 ;; Keywords: comm desktop notifications
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;; This package provides an implementation of the Desktop Notifications
26 ;; <http://www.galago-project.org/specs/notification/>.
28 ;; In order to activate this package, you must add the following code
31 ;; (require 'notifications)
33 ;; For proper usage, Emacs must be started in an environment with an
34 ;; active D-Bus session bus.
40 ;; Pacify byte-compiler. D-Bus support in the Emacs core can be
41 ;; disabled with configuration option "--without-dbus". Declare used
42 ;; subroutines and variables of `dbus' therefore.
43 (declare-function dbus-call-method "dbusbind.c")
44 (declare-function dbus-register-signal "dbusbind.c")
48 (defconst notifications-specification-version "1.1"
49 "The version of the Desktop Notifications Specification implemented.")
51 (defconst notifications-application-name "Emacs"
52 "Default application name.")
54 (defconst notifications-application-icon
56 "images/icons/hicolor/scalable/apps/emacs.svg"
58 "Default application icon.")
60 (defconst notifications-service "org.freedesktop.Notifications"
61 "D-Bus notifications service name.")
63 (defconst notifications-path "/org/freedesktop/Notifications"
64 "D-Bus notifications service path.")
66 (defconst notifications-interface "org.freedesktop.Notifications"
67 "D-Bus notifications service path.")
69 (defconst notifications-notify-method "Notify"
70 "D-Bus notifications service path.")
72 (defconst notifications-close-notification-method "CloseNotification"
73 "D-Bus notifications service path.")
75 (defconst notifications-action-signal "ActionInvoked"
76 "D-Bus notifications action signal.")
78 (defconst notifications-closed-signal "NotificationClosed"
79 "D-Bus notifications closed signal.")
81 (defconst notifications-closed-reason
84 (3 close-notification)
86 "List of reasons why a notification has been closed.")
88 (defvar notifications-on-action-map nil
89 "Mapping between notification and action callback functions.")
91 (defvar notifications-on-close-map nil
92 "Mapping between notification and close callback functions.")
94 (defun notifications-on-action-signal (id action)
95 "Dispatch signals to callback functions from `notifications-on-action-map'."
96 (let ((entry (assoc id notifications-on-action-map)))
98 (funcall (cadr entry) id action)
99 (remove entry 'notifications-on-action-map))))
101 (when (fboundp 'dbus-register-signal)
102 (dbus-register-signal
104 notifications-service
106 notifications-interface
107 notifications-action-signal
108 'notifications-on-action-signal))
110 (defun notifications-on-closed-signal (id &optional reason)
111 "Dispatch signals to callback functions from `notifications-on-closed-map'."
112 ;; notification-daemon prior 0.4.0 does not send a reason. So we
113 ;; make it optional, and assume `undefined' as default.
114 (let ((entry (assoc id notifications-on-close-map))
115 (reason (or reason 4)))
117 (funcall (cadr entry)
118 id (cadr (assoc reason notifications-closed-reason)))
119 (remove entry 'notifications-on-close-map))))
121 (when (fboundp 'dbus-register-signal)
122 (dbus-register-signal
124 notifications-service
126 notifications-interface
127 notifications-closed-signal
128 'notifications-on-closed-signal))
130 (defun notifications-notify (&rest params)
131 "Send notification via D-Bus using the Freedesktop notification protocol.
132 Various PARAMS can be set:
134 :title The notification title.
135 :body The notification body text.
136 :app-name The name of the application sending the notification.
137 Default to `notifications-application-name'.
138 :replaces-id The notification ID that this notification replaces.
139 :app-icon The notification icon.
140 Default is `notifications-application-icon'.
141 Set to nil if you do not want any icon displayed.
142 :actions A list of actions in the form:
143 (KEY TITLE KEY TITLE ...)
144 where KEY and TITLE are both strings.
145 The default action (usually invoked by clicking the
146 notification) should have a key named \"default\".
147 The title can be anything, though implementations are free
149 :timeout The timeout time in milliseconds since the display
150 of the notification at which the notification should
152 If -1, the notification's expiration time is dependent
153 on the notification server's settings, and may vary for
154 the type of notification.
155 If 0, the notification never expires.
157 :urgency The urgency level.
158 Either `low', `normal' or `critical'.
159 :category The type of notification this is.
160 :desktop-entry This specifies the name of the desktop filename representing
162 :image-data This is a raw data image format which describes the width,
163 height, rowstride, has alpha, bits per sample, channels and
164 image data respectively.
165 :image-path This is represented either as a URI (file:// is the
166 only URI schema supported right now) or a name
167 in a freedesktop.org-compliant icon theme.
168 :sound-file The path to a sound file to play when the notification pops up.
169 :sound-name A themable named sound from the freedesktop.org sound naming
170 specification to play when the notification pops up.
171 Similar to icon-name,only for sounds. An example would
172 be \"message-new-instant\".
173 :suppress-sound Causes the server to suppress playing any sounds, if it has
175 :x Specifies the X location on the screen that the notification
176 should point to. The \"y\" hint must also be specified.
177 :y Specifies the Y location on the screen that the notification
178 should point to. The \"x\" hint must also be specified.
179 :on-action Function to call when an action is invoked.
180 The notification id and the key of the action are passed
181 as arguments to the function.
182 :on-close Function to call when the notification has been closed
183 by timeout or by the user.
184 The function receive the notification id and the closing
186 - `expired' if the notification has expired
187 - `dismissed' if the notification was dismissed by the user
188 - `close-notification' if the notification was closed
189 by a call to CloseNotification
191 This function returns a notification id, an integer, which can be
192 used to manipulate the notification item with
193 `notifications-close-notification'."
194 (let ((title (plist-get params :title))
195 (body (plist-get params :body))
196 (app-name (plist-get params :app-name))
197 (replaces-id (plist-get params :replaces-id))
198 (app-icon (plist-get params :app-icon))
199 (actions (plist-get params :actions))
200 (timeout (plist-get params :timeout))
203 (urgency (plist-get params :urgency))
204 (category (plist-get params :category))
205 (desktop-entry (plist-get params :desktop-entry))
206 (image-data (plist-get params :image-data))
207 (image-path (plist-get params :image-path))
208 (sound-file (plist-get params :sound-file))
209 (sound-name (plist-get params :sound-name))
210 (suppress-sound (plist-get params :suppress-sound))
211 (x (plist-get params :x))
212 (y (plist-get params :y))
216 (add-to-list 'hints `(:dict-entry
218 (:variant :byte ,(case urgency
223 (add-to-list 'hints `(:dict-entry
225 (:variant :string ,category)) t))
227 (add-to-list 'hints `(:dict-entry
229 (:variant :string ,desktop-entry)) t))
231 (add-to-list 'hints `(:dict-entry
233 (:variant :struct ,image-data)) t))
235 (add-to-list 'hints `(:dict-entry
237 (:variant :string ,image-path)) t))
239 (add-to-list 'hints `(:dict-entry
241 (:variant :string ,sound-file)) t))
243 (add-to-list 'hints `(:dict-entry
245 (:variant :string ,sound-name)) t))
247 (add-to-list 'hints `(:dict-entry
249 (:variant :boolean ,suppress-sound)) t))
251 (add-to-list 'hints `(:dict-entry "x" (:variant :int32 ,x)) t))
253 (add-to-list 'hints `(:dict-entry "y" (:variant :int32 ,y)) t))
255 ;; Call Notify method
257 (dbus-call-method :session
258 notifications-service
260 notifications-interface
261 notifications-notify-method
263 notifications-application-name)
264 :uint32 (or replaces-id 0)
266 (expand-file-name app-icon)
267 ;; If app-icon is nil because user
268 ;; requested it to be so, send the
270 (if (plist-member params :app-icon)
272 ;; Otherwise send the default icon path
273 notifications-application-icon))
274 :string (or title "")
277 (or hints '(:array :signature "{sv}"))
278 :int32 (or timeout -1)))
280 ;; Register close/action callback function
281 (let ((on-action (plist-get params :on-action))
282 (on-close (plist-get params :on-close)))
284 (add-to-list 'notifications-on-action-map (list id on-action)))
286 (add-to-list 'notifications-on-close-map (list id on-close))))
288 ;; Return notification id
291 (defun notifications-close-notification (id)
292 "Close a notification with identifier ID."
293 (dbus-call-method :session
294 notifications-service
296 notifications-interface
297 notifications-close-notification-method
300 (provide 'notifications)