Function: notifications-notify
notifications-notify is a byte-compiled function defined in
notifications.el.gz.
Signature
(notifications-notify &rest PARAMS)
Documentation
Send notification via D-Bus using the Freedesktop notification protocol.
Various PARAMS can be set:
:bus The D-Bus bus, if different from :session.
: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.
If the value is a string, the function
interprets it as a file name and converts to
absolute by using expand-file-name; if it is a
symbol, the function will use its name (which is
useful when using the Icon Naming
Specification).
: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.
Probably introduced at or before Emacs version 30.1.
Source Code
;; Defined in /usr/src/emacs/lisp/notifications.el.gz
(defun notifications-notify (&rest params)
"Send notification via D-Bus using the Freedesktop notification protocol.
Various PARAMS can be set:
:bus The D-Bus bus, if different from `:session'.
: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.
If the value is a string, the function
interprets it as a file name and converts to
absolute by using `expand-file-name'; if it is a
symbol, the function will use its name (which is
useful when using the Icon Naming
Specification).
: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."
(with-demoted-errors "Notification error: %S"
(let ((bus (or (plist-get params :bus) :session))
(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
(push `(:dict-entry
"urgency"
(:variant :byte ,(pcase urgency
('low 0)
('critical 2)
(_ 1))))
hints))
(when category
(push `(:dict-entry
"category"
(:variant :string ,category))
hints))
(when desktop-entry
(push `(:dict-entry
"desktop-entry"
(:variant :string ,desktop-entry))
hints))
(when image-data
(push `(:dict-entry
"image-data"
(:variant :struct ,image-data))
hints))
(when image-path
(push `(:dict-entry
"image-path"
(:variant :string ,image-path))
hints))
(when action-items
(push `(:dict-entry
"action-items"
(:variant :boolean ,action-items))
hints))
(when sound-file
(push `(:dict-entry
"sound-file"
(:variant :string ,sound-file))
hints))
(when sound-name
(push `(:dict-entry
"sound-name"
(:variant :string ,sound-name))
hints))
(when suppress-sound
(push `(:dict-entry
"suppress-sound"
(:variant :boolean ,suppress-sound))
hints))
(when resident
(push `(:dict-entry
"resident"
(:variant :boolean ,resident))
hints))
(when transient
(push `(:dict-entry
"transient"
(:variant :boolean ,transient))
hints))
(when x
(push `(:dict-entry "x" (:variant :int32 ,x)) hints))
(when y
(push `(:dict-entry "y" (:variant :int32 ,y)) hints))
(setq hints (nreverse hints))
;; Call Notify method.
(setq id
(dbus-call-method bus
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
(if (stringp app-icon)
(expand-file-name app-icon)
;; Convert symbol to string
(symbol-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 bus notifications-service)))
(when on-action
(push (list (list bus unique-name id) on-action)
notifications-on-action-map)
(unless notifications-on-action-object
(setq notifications-on-action-object
(dbus-register-signal
bus
nil
notifications-path
notifications-interface
notifications-action-signal
'notifications-on-action-signal))))
(when on-close
(push (list (list bus unique-name id) on-close)
notifications-on-close-map)
(unless notifications-on-close-object
(setq notifications-on-close-object
(dbus-register-signal
bus
nil
notifications-path
notifications-interface
notifications-closed-signal
'notifications-on-closed-signal)))))
;; Return notification id
id)))