[bpt/emacs.git] / lisp / notifications.el

;;; notifications.el --- Client interface to desktop notifications.

;; Copyright (C) 2010-2012 Free Software Foundation, Inc.

;; Author: Julien Danjou <julien@danjou.info>
;; Keywords: comm desktop notifications

;; This file is part of GNU Emacs.

;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.

;;; Commentary:

;; This package provides an implementation of the Desktop Notifications
;; <http://developer.gnome.org/notification-spec/>.

;; In order to activate this package, you must add the following code
;; into your .emacs:
;;
;;   (require 'notifications)

;; For proper usage, Emacs must be started in an environment with an
;; active D-Bus session bus.

;;; Code:
(eval-when-compile
  (require 'cl))

;; Pacify byte-compiler.  D-Bus support in the Emacs core can be
;; disabled with configuration option "--without-dbus".  Declare used
;; subroutines and variables of `dbus' therefore.
(declare-function dbus-call-method "dbusbind.c")
(declare-function dbus-register-signal "dbusbind.c")

(require 'dbus)

(defconst notifications-specification-version "1.2"
  "The version of the Desktop Notifications Specification implemented.")

(defconst notifications-application-name "Emacs"
  "Default application name.")

(defconst notifications-application-icon
  (expand-file-name
   "images/icons/hicolor/scalable/apps/emacs.svg"
   data-directory)
  "Default application icon.")

(defconst notifications-service "org.freedesktop.Notifications"
  "D-Bus notifications service name.")

(defconst notifications-path "/org/freedesktop/Notifications"
  "D-Bus notifications service path.")

(defconst notifications-interface "org.freedesktop.Notifications"
  "D-Bus notifications service interface.")

(defconst notifications-notify-method "Notify"
  "D-Bus notifications notify method.")

(defconst notifications-close-notification-method "CloseNotification"
  "D-Bus notifications close notification method.")

(defconst notifications-get-capabilities-method "GetCapabilities"
  "D-Bus notifications get capabilities method.")

(defconst notifications-action-signal "ActionInvoked"
  "D-Bus notifications action signal.")

(defconst notifications-closed-signal "NotificationClosed"
  "D-Bus notifications closed signal.")

(defconst notifications-closed-reason
  '((1 expired)
    (2 dismissed)
    (3 close-notification)
    (4 undefined))
  "List of reasons why a notification has been closed.")

(defvar notifications-on-action-map nil
  "Mapping between notification and action callback functions.")

(defvar notifications-on-action-object nil
  "Object for registered on-action signal.")

(defvar notifications-on-close-map nil
  "Mapping between notification and close callback functions.")

(defvar notifications-on-close-object nil
  "Object for registered on-close signal.")

(defun notifications-on-action-signal (id action)
  "Dispatch signals to callback functions from `notifications-on-action-map'."
  (let* ((unique-name (dbus-event-service-name last-input-event))
	 (entry (assoc (cons unique-name id) notifications-on-action-map)))
    (when entry
      (funcall (cadr entry) id action)
      (when (and (not (setq notifications-on-action-map
			    (remove entry notifications-on-action-map)))
		 notifications-on-action-object)
	(dbus-unregister-object notifications-on-action-object)
	(setq notifications-on-action-object nil)))))

(defun notifications-on-closed-signal (id &optional reason)
  "Dispatch signals to callback functions from `notifications-on-closed-map'."
  ;; notification-daemon prior 0.4.0 does not send a reason.  So we
  ;; make it optional, and assume `undefined' as default.
  (let* ((unique-name (dbus-event-service-name last-input-event))
	 (entry (assoc (cons unique-name id) notifications-on-close-map))
	 (reason (or reason 4)))
    (when entry
      (funcall (cadr entry)
	       id (cadr (assoc reason notifications-closed-reason)))
      (when (and (not (setq notifications-on-close-map
			    (remove entry notifications-on-close-map)))
		 notifications-on-close-object)
	(dbus-unregister-object notifications-on-close-object)
	(setq notifications-on-close-object nil)))))

(defun notifications-notify (&rest params)
  "Send notification via D-Bus using the Freedesktop notification protocol.
Various PARAMS can be set:

 :title          The notification title.
 :body           The notification body text.
 :app-name       The name of the application sending the notification.
                 Default to `notifications-application-name'.
 :replaces-id    The notification ID that this notification replaces.
 :app-icon       The notification icon.
                 Default is `notifications-application-icon'.
                 Set to nil if you do not want any icon displayed.
 :actions        A list of actions in the form:
                   (KEY TITLE KEY TITLE ...)
                 where KEY and TITLE are both strings.
                 The default action (usually invoked by clicking the
                 notification) should have a key named \"default\".
                 The title can be anything, though implementations are free
                 not to display it.
 :timeout        The timeout time in milliseconds since the display
                 of the notification at which the notification should
                 automatically close.
                 If -1, the notification's expiration time is dependent
                 on the notification server's settings, and may vary for
                 the type of notification.
                 If 0, the notification never expires.
                 Default value is -1.
 :urgency        The urgency level.
                 Either `low', `normal' or `critical'.
 :action-items   Whether the TITLE of the actions is interpreted as
                 a named icon.
 :category       The type of notification this is.
 :desktop-entry  This specifies the name of the desktop filename representing
                 the calling program.
 :image-data     This is a raw data image format which describes the width,
                 height, rowstride, has alpha, bits per sample, channels and
                 image data respectively.
 :image-path     This is represented either as a URI (file:// is the
                 only URI schema supported right now) or a name
                 in a freedesktop.org-compliant icon theme.
 :sound-file     The path to a sound file to play when the notification pops up.
 :sound-name     A themable named sound from the freedesktop.org sound naming
                 specification to play when the notification pops up.
                 Similar to icon-name,only for sounds. An example would
                 be \"message-new-instant\".
 :suppress-sound Causes the server to suppress playing any sounds, if it has
                 that ability.
 :resident       When set the server will not automatically remove the
                 notification when an action has been invoked.
 :transient      When set the server will treat the notification as transient
                 and by-pass the server's persistence capability, if it
                 should exist. 
 :x              Specifies the X location on the screen that the notification
                 should point to.  The \"y\" hint must also be specified.
 :y              Specifies the Y location on the screen that the notification
                 should point to.  The \"x\" hint must also be specified.
 :on-action      Function to call when an action is invoked.
                 The notification id and the key of the action are passed
                 as arguments to the function.
 :on-close       Function to call when the notification has been closed
                 by timeout or by the user.
                 The function receive the notification id and the closing
                 reason as arguments:
                   - `expired' if the notification has expired
                   - `dismissed' if the notification was dismissed by the user
                   - `close-notification' if the notification was closed
                     by a call to CloseNotification
                   - `undefined' if the notification server hasn't provided
                     a reason

Which parameters are accepted by the notification server can be
checked via `notifications-get-capabilities'.

This function returns a notification id, an integer, which can be
used to manipulate the notification item with
`notifications-close-notification' or the `:replaces-id' argument
of another `notifications-notify' call."
  (let ((title (plist-get params :title))
        (body (plist-get params :body))
        (app-name (plist-get params :app-name))
        (replaces-id (plist-get params :replaces-id))
        (app-icon (plist-get params :app-icon))
        (actions (plist-get params :actions))
        (timeout (plist-get params :timeout))
        ;; Hints
        (hints '())
        (urgency (plist-get params :urgency))
        (category (plist-get params :category))
        (desktop-entry (plist-get params :desktop-entry))
        (image-data (plist-get params :image-data))
        (image-path (plist-get params :image-path))
	(action-items (plist-get params :action-items))
        (sound-file (plist-get params :sound-file))
        (sound-name (plist-get params :sound-name))
        (suppress-sound (plist-get params :suppress-sound))
	(resident (plist-get params :resident))
	(transient (plist-get params :transient))
        (x (plist-get params :x))
        (y (plist-get params :y))
        id)
    ;; Build hints array
    (when urgency
      (add-to-list 'hints `(:dict-entry
                            "urgency"
                            (:variant :byte ,(case urgency
                                               (low 0)
                                               (critical 2)
                                               (t 1)))) t))
    (when category
      (add-to-list 'hints `(:dict-entry
                            "category"
                            (:variant :string ,category)) t))
    (when desktop-entry
      (add-to-list 'hints `(:dict-entry
                            "desktop-entry"
                            (:variant :string ,desktop-entry)) t))
    (when image-data
      (add-to-list 'hints `(:dict-entry
                            "image-data"
                            (:variant :struct ,image-data)) t))
    (when image-path
      (add-to-list 'hints `(:dict-entry
                            "image-path"
                            (:variant :string ,image-path)) t))
    (when action-items
      (add-to-list 'hints `(:dict-entry
                            "action-items"
                            (:variant :boolean ,action-items)) t))
    (when sound-file
      (add-to-list 'hints `(:dict-entry
                            "sound-file"
                            (:variant :string ,sound-file)) t))
    (when sound-name
      (add-to-list 'hints `(:dict-entry
                            "sound-name"
                            (:variant :string ,sound-name)) t))
    (when suppress-sound
      (add-to-list 'hints `(:dict-entry
                            "suppress-sound"
                            (:variant :boolean ,suppress-sound)) t))
    (when resident
      (add-to-list 'hints `(:dict-entry
                            "resident"
                            (:variant :boolean ,resident)) t))
    (when transient
      (add-to-list 'hints `(:dict-entry
                            "transient"
                            (:variant :boolean ,transient)) t))
    (when x
      (add-to-list 'hints `(:dict-entry "x" (:variant :int32 ,x)) t))
    (when y
      (add-to-list 'hints `(:dict-entry "y" (:variant :int32 ,y)) t))

    ;; Call Notify method
    (setq id
          (dbus-call-method :session
                            notifications-service
                            notifications-path
                            notifications-interface
                            notifications-notify-method
                            :string (or app-name
                                        notifications-application-name)
                            :uint32 (or replaces-id 0)
                            :string (if app-icon
                                        (expand-file-name app-icon)
                                      ;; If app-icon is nil because user
                                      ;; requested it to be so, send the
                                      ;; empty string
                                      (if (plist-member params :app-icon)
                                          ""
                                        ;; Otherwise send the default icon path
                                        notifications-application-icon))
                            :string (or title "")
                            :string (or body "")
                            `(:array ,@actions)
                            (or hints '(:array :signature "{sv}"))
                            :int32 (or timeout -1)))

    ;; Register close/action callback function.  We must also remember
    ;; the daemon's unique name, because the daemon could have
    ;; restarted.
    (let ((on-action (plist-get params :on-action))
          (on-close (plist-get params :on-close))
	  (unique-name (dbus-get-name-owner :session notifications-service)))
      (when on-action
        (add-to-list 'notifications-on-action-map
		     (list (cons unique-name id) on-action))
	(unless notifications-on-action-object
	  (setq notifications-on-action-object
		(dbus-register-signal
		 :session
		 nil
		 notifications-path
		 notifications-interface
		 notifications-action-signal
		 'notifications-on-action-signal))))

      (when on-close
        (add-to-list 'notifications-on-close-map
		     (list (cons unique-name id) on-close))
	(unless notifications-on-close-object
	  (setq notifications-on-close-object
		(dbus-register-signal
		 :session
		 nil
		 notifications-path
		 notifications-interface
		 notifications-closed-signal
		 'notifications-on-closed-signal)))))

    ;; Return notification id
    id))

(defun notifications-close-notification (id)
  "Close a notification with identifier ID."
  (dbus-call-method :session
                    notifications-service
                    notifications-path
                    notifications-interface
                    notifications-close-notification-method
                    :int32 id))

(defun notifications-get-capabilities ()
  "Return the capabilities of the notification server, a list of strings.
The following capabilities can be expected:

  `:actions'         The server will provide the specified actions
                     to the user.
  `:action-icons'    Supports using icons instead of text for
                     displaying actions.
  `:body'            Supports body text.
  `:body-hyperlinks' The server supports hyperlinks in the notifications.
  `:body-images'     The server supports images in the notifications.
  `:body-markup'     Supports markup in the body text.
  `:icon-multi'      The server will render an animation of all the
                     frames in a given image array.
  `:icon-static'     Supports display of exactly 1 frame of any
                     given image array.  This value is mutually exclusive
                     with `:icon-multi'.
  `:persistence'     The server supports persistence of notifications.
  `:sound'           The server supports sounds on notifications.

Further vendor-specific caps start with `:x-vendor', like `:x-gnome-foo-cap'."
  (dbus-ignore-errors
   (mapcar
    (lambda (x) (intern (concat ":" x)))
    (dbus-call-method :session
		      notifications-service
		      notifications-path
		      notifications-interface
		      notifications-get-capabilities-method))))

(provide 'notifications)
Commit	Line	Data
41a86354 MA	1	;;; notifications.el --- Client interface to desktop notifications.
41a86354 MA	2
acaf905b	3	;; Copyright (C) 2010-2012 Free Software Foundation, Inc.
41a86354 MA	4
	5	;; Author: Julien Danjou <julien@danjou.info>
	6	;; Keywords: comm desktop notifications
	7
	8	;; This file is part of GNU Emacs.
	9
	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.
	14
	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.
	19
	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/>.
	22
	23	;;; Commentary:
	24
	25	;; This package provides an implementation of the Desktop Notifications
e43042fe	26	;; <http://developer.gnome.org/notification-spec/>.
41a86354 MA	27
	28	;; In order to activate this package, you must add the following code
	29	;; into your .emacs:
	30	;;
	31	;; (require 'notifications)
	32
7f5c46c7 MA	33	;; For proper usage, Emacs must be started in an environment with an
	34	;; active D-Bus session bus.
	35
41a86354 MA	36	;;; Code:
	37	(eval-when-compile
	38	(require 'cl))
	39
	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")
b978141d	44	(declare-function dbus-register-signal "dbusbind.c")
41a86354 MA	45
	46	(require 'dbus)
	47
e43042fe	48	(defconst notifications-specification-version "1.2"
7ea2d383 MA	49	"The version of the Desktop Notifications Specification implemented.")
7ea2d383 MA	50
41a86354 MA	51	(defconst notifications-application-name "Emacs"
	52	"Default application name.")
	53
	54	(defconst notifications-application-icon
	55	(expand-file-name
	56	"images/icons/hicolor/scalable/apps/emacs.svg"
	57	data-directory)
	58	"Default application icon.")
	59
	60	(defconst notifications-service "org.freedesktop.Notifications"
	61	"D-Bus notifications service name.")
	62
	63	(defconst notifications-path "/org/freedesktop/Notifications"
	64	"D-Bus notifications service path.")
	65
	66	(defconst notifications-interface "org.freedesktop.Notifications"
b613912b	67	"D-Bus notifications service interface.")
41a86354 MA	68
41a86354 MA	69	(defconst notifications-notify-method "Notify"
b613912b	70	"D-Bus notifications notify method.")
41a86354 MA	71
41a86354 MA	72	(defconst notifications-close-notification-method "CloseNotification"
b613912b MA	73	"D-Bus notifications close notification method.")
	74
	75	(defconst notifications-get-capabilities-method "GetCapabilities"
	76	"D-Bus notifications get capabilities method.")
41a86354 MA	77
	78	(defconst notifications-action-signal "ActionInvoked"
	79	"D-Bus notifications action signal.")
	80
	81	(defconst notifications-closed-signal "NotificationClosed"
	82	"D-Bus notifications closed signal.")
	83
	84	(defconst notifications-closed-reason
	85	'((1 expired)
	86	(2 dismissed)
	87	(3 close-notification)
	88	(4 undefined))
	89	"List of reasons why a notification has been closed.")
	90
	91	(defvar notifications-on-action-map nil
	92	"Mapping between notification and action callback functions.")
	93
6612a284 MA	94	(defvar notifications-on-action-object nil
	95	"Object for registered on-action signal.")
	96
41a86354 MA	97	(defvar notifications-on-close-map nil
	98	"Mapping between notification and close callback functions.")
	99
6612a284 MA	100	(defvar notifications-on-close-object nil
	101	"Object for registered on-close signal.")
	102
41a86354	103	(defun notifications-on-action-signal (id action)
fa4003da	104	"Dispatch signals to callback functions from `notifications-on-action-map'."
a41a6cf4 MA	105	(let* ((unique-name (dbus-event-service-name last-input-event))
	106	(entry (assoc (cons unique-name id) notifications-on-action-map)))
	107	(when entry
fa4003da	108	(funcall (cadr entry) id action)
6612a284 MA	109	(when (and (not (setq notifications-on-action-map
	110	(remove entry notifications-on-action-map)))
	111	notifications-on-action-object)
	112	(dbus-unregister-object notifications-on-action-object)
	113	(setq notifications-on-action-object nil)))))
41a86354	114
5b77774d	115	(defun notifications-on-closed-signal (id &optional reason)
fa4003da	116	"Dispatch signals to callback functions from `notifications-on-closed-map'."
5b77774d MA	117	;; notification-daemon prior 0.4.0 does not send a reason. So we
5b77774d MA	118	;; make it optional, and assume `undefined' as default.
a41a6cf4 MA	119	(let* ((unique-name (dbus-event-service-name last-input-event))
	120	(entry (assoc (cons unique-name id) notifications-on-close-map))
	121	(reason (or reason 4)))
	122	(when entry
fa4003da MA	123	(funcall (cadr entry)
fa4003da MA	124	id (cadr (assoc reason notifications-closed-reason)))
6612a284 MA	125	(when (and (not (setq notifications-on-close-map
	126	(remove entry notifications-on-close-map)))
	127	notifications-on-close-object)
	128	(dbus-unregister-object notifications-on-close-object)
	129	(setq notifications-on-close-object nil)))))
41a86354 MA	130
	131	(defun notifications-notify (&rest params)
	132	"Send notification via D-Bus using the Freedesktop notification protocol.
	133	Various PARAMS can be set:
	134
	135	:title The notification title.
	136	:body The notification body text.
	137	:app-name The name of the application sending the notification.
	138	Default to `notifications-application-name'.
	139	:replaces-id The notification ID that this notification replaces.
	140	:app-icon The notification icon.
	141	Default is `notifications-application-icon'.
	142	Set to nil if you do not want any icon displayed.
	143	:actions A list of actions in the form:
	144	(KEY TITLE KEY TITLE ...)
	145	where KEY and TITLE are both strings.
b978141d JB	146	The default action (usually invoked by clicking the
b978141d JB	147	notification) should have a key named \"default\".
890a18d6	148	The title can be anything, though implementations are free
b978141d	149	not to display it.
41a86354 MA	150	:timeout The timeout time in milliseconds since the display
	151	of the notification at which the notification should
	152	automatically close.
	153	If -1, the notification's expiration time is dependent
	154	on the notification server's settings, and may vary for
	155	the type of notification.
	156	If 0, the notification never expires.
	157	Default value is -1.
	158	:urgency The urgency level.
	159	Either `low', `normal' or `critical'.
e43042fe MA	160	:action-items Whether the TITLE of the actions is interpreted as
e43042fe MA	161	a named icon.
41a86354 MA	162	:category The type of notification this is.
	163	:desktop-entry This specifies the name of the desktop filename representing
	164	the calling program.
	165	:image-data This is a raw data image format which describes the width,
	166	height, rowstride, has alpha, bits per sample, channels and
	167	image data respectively.
7ea2d383 MA	168	:image-path This is represented either as a URI (file:// is the
	169	only URI schema supported right now) or a name
	170	in a freedesktop.org-compliant icon theme.
41a86354	171	:sound-file The path to a sound file to play when the notification pops up.
40ba43b4	172	:sound-name A themable named sound from the freedesktop.org sound naming
7ea2d383 MA	173	specification to play when the notification pops up.
	174	Similar to icon-name,only for sounds. An example would
	175	be \"message-new-instant\".
41a86354 MA	176	:suppress-sound Causes the server to suppress playing any sounds, if it has
41a86354 MA	177	that ability.
e43042fe MA	178	:resident When set the server will not automatically remove the
	179	notification when an action has been invoked.
	180	:transient When set the server will treat the notification as transient
	181	and by-pass the server's persistence capability, if it
	182	should exist.
41a86354	183	:x Specifies the X location on the screen that the notification
b978141d	184	should point to. The \"y\" hint must also be specified.
41a86354	185	:y Specifies the Y location on the screen that the notification
b978141d	186	should point to. The \"x\" hint must also be specified.
fa4003da MA	187	:on-action Function to call when an action is invoked.
	188	The notification id and the key of the action are passed
	189	as arguments to the function.
41a86354 MA	190	:on-close Function to call when the notification has been closed
41a86354 MA	191	by timeout or by the user.
fa4003da MA	192	The function receive the notification id and the closing
fa4003da MA	193	reason as arguments:
41a86354 MA	194	- `expired' if the notification has expired
	195	- `dismissed' if the notification was dismissed by the user
	196	- `close-notification' if the notification was closed
	197	by a call to CloseNotification
66b907dc MA	198	- `undefined' if the notification server hasn't provided
66b907dc MA	199	a reason
41a86354	200
b613912b MA	201	Which parameters are accepted by the notification server can be
	202	checked via `notifications-get-capabilities'.
	203
41a86354 MA	204	This function returns a notification id, an integer, which can be
41a86354 MA	205	used to manipulate the notification item with
66b907dc MA	206	`notifications-close-notification' or the `:replaces-id' argument
66b907dc MA	207	of another `notifications-notify' call."
41a86354 MA	208	(let ((title (plist-get params :title))
	209	(body (plist-get params :body))
	210	(app-name (plist-get params :app-name))
	211	(replaces-id (plist-get params :replaces-id))
	212	(app-icon (plist-get params :app-icon))
	213	(actions (plist-get params :actions))
	214	(timeout (plist-get params :timeout))
	215	;; Hints
	216	(hints '())
	217	(urgency (plist-get params :urgency))
	218	(category (plist-get params :category))
	219	(desktop-entry (plist-get params :desktop-entry))
	220	(image-data (plist-get params :image-data))
7ea2d383	221	(image-path (plist-get params :image-path))
e43042fe	222	(action-items (plist-get params :action-items))
41a86354	223	(sound-file (plist-get params :sound-file))
7ea2d383	224	(sound-name (plist-get params :sound-name))
41a86354	225	(suppress-sound (plist-get params :suppress-sound))
e43042fe MA	226	(resident (plist-get params :resident))
e43042fe MA	227	(transient (plist-get params :transient))
41a86354 MA	228	(x (plist-get params :x))
	229	(y (plist-get params :y))
	230	id)
	231	;; Build hints array
	232	(when urgency
	233	(add-to-list 'hints `(:dict-entry
	234	"urgency"
	235	(:variant :byte ,(case urgency
0adf5618 SM	236	(low 0)
0adf5618 SM	237	(critical 2)
41a86354 MA	238	(t 1)))) t))
	239	(when category
	240	(add-to-list 'hints `(:dict-entry
	241	"category"
	242	(:variant :string ,category)) t))
	243	(when desktop-entry
	244	(add-to-list 'hints `(:dict-entry
	245	"desktop-entry"
	246	(:variant :string ,desktop-entry)) t))
	247	(when image-data
	248	(add-to-list 'hints `(:dict-entry
e43042fe	249	"image-data"
41a86354	250	(:variant :struct ,image-data)) t))
7ea2d383 MA	251	(when image-path
7ea2d383 MA	252	(add-to-list 'hints `(:dict-entry
e43042fe	253	"image-path"
7ea2d383	254	(:variant :string ,image-path)) t))
e43042fe MA	255	(when action-items
	256	(add-to-list 'hints `(:dict-entry
	257	"action-items"
	258	(:variant :boolean ,action-items)) t))
41a86354 MA	259	(when sound-file
	260	(add-to-list 'hints `(:dict-entry
	261	"sound-file"
	262	(:variant :string ,sound-file)) t))
7ea2d383 MA	263	(when sound-name
	264	(add-to-list 'hints `(:dict-entry
	265	"sound-name"
	266	(:variant :string ,sound-name)) t))
41a86354 MA	267	(when suppress-sound
	268	(add-to-list 'hints `(:dict-entry
	269	"suppress-sound"
	270	(:variant :boolean ,suppress-sound)) t))
e43042fe MA	271	(when resident
	272	(add-to-list 'hints `(:dict-entry
	273	"resident"
	274	(:variant :boolean ,resident)) t))
	275	(when transient
	276	(add-to-list 'hints `(:dict-entry
	277	"transient"
	278	(:variant :boolean ,transient)) t))
41a86354 MA	279	(when x
	280	(add-to-list 'hints `(:dict-entry "x" (:variant :int32 ,x)) t))
	281	(when y
	282	(add-to-list 'hints `(:dict-entry "y" (:variant :int32 ,y)) t))
	283
	284	;; Call Notify method
	285	(setq id
	286	(dbus-call-method :session
	287	notifications-service
	288	notifications-path
	289	notifications-interface
	290	notifications-notify-method
	291	:string (or app-name
	292	notifications-application-name)
	293	:uint32 (or replaces-id 0)
	294	:string (if app-icon
	295	(expand-file-name app-icon)
	296	;; If app-icon is nil because user
	297	;; requested it to be so, send the
	298	;; empty string
	299	(if (plist-member params :app-icon)
	300	""
	301	;; Otherwise send the default icon path
	302	notifications-application-icon))
	303	:string (or title "")
	304	:string (or body "")
	305	`(:array ,@actions)
	306	(or hints '(:array :signature "{sv}"))
	307	:int32 (or timeout -1)))
	308
db976e3c MA	309	;; Register close/action callback function. We must also remember
	310	;; the daemon's unique name, because the daemon could have
	311	;; restarted.
41a86354	312	(let ((on-action (plist-get params :on-action))
a41a6cf4 MA	313	(on-close (plist-get params :on-close))
a41a6cf4 MA	314	(unique-name (dbus-get-name-owner :session notifications-service)))
41a86354	315	(when on-action
a41a6cf4	316	(add-to-list 'notifications-on-action-map
6612a284 MA	317	(list (cons unique-name id) on-action))
	318	(unless notifications-on-action-object
	319	(setq notifications-on-action-object
	320	(dbus-register-signal
	321	:session
	322	nil
	323	notifications-path
	324	notifications-interface
	325	notifications-action-signal
	326	'notifications-on-action-signal))))
	327
41a86354	328	(when on-close
a41a6cf4	329	(add-to-list 'notifications-on-close-map
6612a284 MA	330	(list (cons unique-name id) on-close))
	331	(unless notifications-on-close-object
	332	(setq notifications-on-close-object
	333	(dbus-register-signal
	334	:session
	335	nil
	336	notifications-path
	337	notifications-interface
	338	notifications-closed-signal
	339	'notifications-on-closed-signal)))))
41a86354 MA	340
	341	;; Return notification id
	342	id))
	343
	344	(defun notifications-close-notification (id)
	345	"Close a notification with identifier ID."
	346	(dbus-call-method :session
	347	notifications-service
	348	notifications-path
	349	notifications-interface
	350	notifications-close-notification-method
	351	:int32 id))
	352
b613912b MA	353	(defun notifications-get-capabilities ()
	354	"Return the capabilities of the notification server, a list of strings.
	355	The following capabilities can be expected:
	356
e43042fe MA	357	`:actions' The server will provide the specified actions
	358	to the user.
	359	`:action-icons' Supports using icons instead of text for
	360	displaying actions.
	361	`:body' Supports body text.
	362	`:body-hyperlinks' The server supports hyperlinks in the notifications.
	363	`:body-images' The server supports images in the notifications.
	364	`:body-markup' Supports markup in the body text.
	365	`:icon-multi' The server will render an animation of all the
	366	frames in a given image array.
	367	`:icon-static' Supports display of exactly 1 frame of any
	368	given image array. This value is mutually exclusive
	369	with `:icon-multi'.
	370	`:persistence' The server supports persistence of notifications.
	371	`:sound' The server supports sounds on notifications.
	372
	373	Further vendor-specific caps start with `:x-vendor', like `:x-gnome-foo-cap'."
	374	(dbus-ignore-errors
	375	(mapcar
	376	(lambda (x) (intern (concat ":" x)))
	377	(dbus-call-method :session
	378	notifications-service
	379	notifications-path
	380	notifications-interface
	381	notifications-get-capabilities-method))))
b613912b	382
41a86354	383	(provide 'notifications)