2 <!DOCTYPE article PUBLIC "-//OASIS/DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
5 <title>Desktop Notifications Specification</title>
6 <releaseinfo>Version 1.2</releaseinfo>
7 <date>28 October 2010</date>
10 <firstname>Mike</firstname>
11 <surname>Hearn</surname>
14 <email>mike@navi.cx</email>
19 <firstname>Christian</firstname>
20 <surname>Hammond</surname>
23 <email>chipx86@chipx86.com</email>
28 <firstname>William Jon</firstname>
29 <surname>McCann</surname>
32 <email>jmccann@redhat.com</email>
39 <sect1 id="introduction">
40 <title>Introduction</title>
42 This is a draft standard for a desktop notifications service,
43 through which applications can generate passive popups to notify
44 the user in an asynchronous manner of events.
47 This specification explicitly does not include other types of
48 notification presentation such as modal message boxes, window manager
49 decorations or window list annotations.
52 Example use cases include:
55 <listitem><para>Messages from chat programs</para> </listitem>
56 <listitem><para>Scheduled alarm</para></listitem>
57 <listitem><para>Completed file transfer</para></listitem>
58 <listitem><para>New mail notification</para></listitem>
59 <listitem><para>Low disk space/battery warnings</para></listitem>
63 <sect1 id="basic-design">
64 <title>Basic Design</title>
66 In order to ensure that multiple notifications can easily be
67 displayed at once, and to provide a convenient implementation, all
68 notifications are controlled by a single session-scoped service which
69 exposes a D-BUS interface.
72 On startup, a conforming implementation should take the
73 <literal>org.freedesktop.Notifications</literal> service on
74 the session bus. This service will be referred to as the "notification
75 server" or just "the server" in this document. It can optionally be
76 activated automatically by the bus process, however this is not required
77 and notification server clients must not assume that it is available.
80 The server should implement the
81 <literal>org.freedesktop.Notifications</literal> interface on
82 an object with the path <literal>"/org/freedesktop/Notifications"</literal>.
83 This is the only interface required by this version of the specification.
86 A notification has the following components:
89 <title>Notification Components</title>
93 <entry>Component</entry>
94 <entry>Description</entry>
99 <entry>Application Name</entry>
101 This is the optional name of the application sending the notification.
102 This should be the application's formal name, rather than some sort
103 of ID. An example would be "FredApp E-Mail Client," rather than
104 "fredapp-email-client."
108 <entry>Replaces ID</entry>
110 An optional ID of an existing notification that this
111 notification is intended to replace.
115 <entry>Notification Icon</entry>
117 The notification icon. See <xref linkend="icons-and-images-formats"/>.
121 <entry>Summary</entry>
123 This is a single line overview of the notification. For instance,
124 "You have mail" or "A friend has come online". It should generally
125 not be longer than 40 characters, though this is not a requirement,
126 and server implementations should word wrap if necessary. The summary
127 must be encoded using UTF-8.
134 This is a multi-line body of text. Each line is a paragraph, server
135 implementations are free to word wrap them as they see fit.
138 The body may contain simple markup as specified in
139 <xref linkend="markup"/>. It must be encoded using UTF-8.
142 If the body is omitted, just the summary is displayed.
147 <entry>Actions</entry>
150 The actions send a request message back to the notification client
151 when invoked. This functionality may not be implemented by the
152 notification server, conforming clients should check if it is available
153 before using it (see the GetCapabilities message in
154 <xref linkend="protocol"/>). An implementation is free to ignore any
155 requested by the client. As an example one possible rendering of
156 actions would be as buttons in the notification popup.
159 Actions are sent over as a list of pairs. Each even element in the
160 list (starting at index 0) represents the identifier for the action.
161 Each odd element in the list is the localized string that will be
162 displayed to the user.
165 The default action (usually invoked my clicking the notification)
166 should have a key named <literal>"default"</literal>. The name can
167 be anything, though implementations are free not to display it.
175 Hints are a way to provide extra data to a notification server that
176 the server may be able to make use of.
178 <para>See <xref linkend="hints"/> for a list of available hints.</para>
182 <entry>Expiration Timeout</entry>
185 The timeout time in milliseconds since the display of the notification
186 at which the notification should automatically close.
189 If -1, the notification's expiration time is dependent on the
190 notification server's settings, and may vary for the type of
194 If 0, the notification never expires.
202 Each notification displayed is allocated a unique ID by the server.
203 This is unique within the session. While the notification server is
204 running, the ID will not be recycled unless the capacity of a uint32 is
208 This can be used to hide the notification before the expiration timeout
209 is reached. It can also be used to atomically replace the notification
210 with another. This allows you to (for instance) modify the contents of
211 a notification while it's on-screen.
215 <sect1 id="backwards-compat" xreflabel="Backwards Compatibility">
216 <title>Backwards Compatibility</title>
218 Clients should try and avoid making assumptions about the presentation and
219 abilities of the notification server. The message content is the most
223 Clients can check with the server what capabilities are supported
224 using the <literal>GetCapabilities</literal> message. See
225 <xref linkend="protocol"/>.
228 If a client requires a response from a passive popup, it should be
229 coded such that a non-focus-stealing message box can be used in the
230 case that the notification server does not support this feature.
234 <sect1 id="markup" xreflabel="Markup">
235 <title>Markup</title>
237 Body text may contain markup. The markup is XML-based, and consists
238 of a small subset of HTML along with a few additional tags.
241 The following tags should be supported by the notification server.
242 Though it is optional, it is recommended. Notification servers that do
243 not support these tags should filter them out.
250 <sgmltag class="starttag">b</sgmltag> ...
251 <sgmltag class="endtag">b</sgmltag>
257 <sgmltag class="starttag">i</sgmltag> ...
258 <sgmltag class="endtag">i</sgmltag>
260 <entry>Italic</entry>
264 <sgmltag class="starttag">u</sgmltag> ...
265 <sgmltag class="endtag">u</sgmltag>
267 <entry>Underline</entry>
271 <sgmltag class="starttag">a href="..."</sgmltag> ...
272 <sgmltag class="endtag">a</sgmltag>
274 <entry>Hyperlink</entry>
278 <sgmltag class="emptytag">img src="..." alt="..."</sgmltag>
286 A full-blown HTML implementation is not required of this spec, and
287 notifications should never take advantage of tags that are not listed
288 above. As notifications are not a substitute for web browsers or complex
289 dialogs, advanced layout is not necessary, and may in fact limit the
290 number of systems that notification services can run on, due to memory
291 usage and screen space. Such examples are PDAs, certain cell phones, and
292 slow PCs or laptops with little memory.
295 For the same reason, a full XML or XHTML implementation using XSLT or
296 CSS stylesheets is not part of this specification. Information that
297 must be presented in a more complex form should use an application-specific
298 dialog, a web browser, or some other display mechanism.
301 The tags specified above mark up the content in a way that allows them
302 to be stripped out on some implementations without impacting the actual
306 <sect2 id="hyperlinks" xreflabel="Hyperlinks">
307 <title>Hyperlinks</title>
309 Hyperlinks allow for linking one or more words to a URI. There is no
310 requirement to allow for images to be linked, and it is highly suggested
311 that implementations do not allow this, as there is no clean-looking,
312 standard visual indicator for a hyperlinked image.
315 Hyperlinked text should appear in the standard blue underline format.
318 Hyperlinks cannot function as a replacement for actions. They are
319 used to link to local directories or remote sites using standard URI
323 Implementations are not required to support hyperlinks.
327 <sect2 id="images" xreflabel="Images">
328 <title>Images</title>
330 Images may be placed in the notification, but this should be done with
331 caution. The image should never exceed 200x100, but this should be thought
332 of as a maximum size. Images should always have alternative text
333 provided through the <literal>alt="..."</literal> attribute.
336 Image data cannot be embedded in the message itself. Images referenced
337 must always be local files.
340 Implementations are not required to support images.
345 <sect1 id="icons-and-images" xreflabel="Icons and Images">
346 <title>Icons and Images</title>
348 A notification can optionally have an associated icon and/or image.
351 The icon is defined by the "app_icon" parameter.
352 The image can be defined by the "image-path", the "image-data" hint or the
353 deprecated "icon_data" hint.
356 <title>Priorities</title>
358 An implementation which only displays one image or icon must choose which one
359 to display using the following order:
361 <listitem><para>"image-data"</para></listitem>
362 <listitem><para>"image-path"</para></listitem>
363 <listitem><para>app_icon parameter</para></listitem>
364 <listitem><para>for compatibility reason, "icon_data"</para></listitem>
369 An implementation which can display both the image and icon must show the
370 icon from the "app_icon" parameter and choose which image to display using
373 <listitem><para>"image-data"</para></listitem>
374 <listitem><para>"image-path"</para></listitem>
375 <listitem><para>for compatibility reason, "icon_data"</para></listitem>
380 <sect2 id="icons-and-images-formats" xreflabel="Icons and Images Formats">
381 <title>Formats</title>
383 The "image-data" and "icon_data" hints should be a DBus structure
384 of signature (iiibiiay). The components of this structure are as follows:
386 <listitem><para>width (i): Width of image in pixels</para></listitem>
387 <listitem><para>height (i): Height of image in pixels</para></listitem>
388 <listitem><para>rowstride (i): Distance in bytes between row starts</para></listitem>
389 <listitem><para>has_alpha (b): Whether the image has an alpha channel</para></listitem>
390 <listitem><para>bits_per_sample (i): Must always be 8</para></listitem>
391 <listitem><para>channels (i): If has_alpha is TRUE, must be 4, otherwise 3</para></listitem>
392 <listitem><para>data (ay): The image data, in RGB byte order</para></listitem>
394 This image format is derived from <ulink url="http://developer.gnome.org/gdk-pixbuf/stable/">gdk-pixbuf</ulink>.
397 The "app_icon" parameter and "image-path" hint should be either an URI
398 (file:// is the only URI schema supported right now) or a name in a
399 freedesktop.org-compliant icon theme (not a GTK+ stock ID).
404 <sect1 id="categories" xreflabel="Categories">
405 <title>Categories</title>
407 Notifications can optionally have a type indicator. Although neither
408 client or nor server must support this, some may choose to. Those servers
409 implementing categories may use them to intelligently display
410 the notification in a certain way, or group notifications of similar
415 <literal><replaceable>class.specific</replaceable></literal> form.
416 <literal>class</literal> specifies the generic type of notification, and
417 <literal>specific</literal> specifies the more specific type of
421 If a specific type of notification does not exist for your notification,
422 but the generic kind does, a notification of type
423 <literal><replaceable>class</replaceable></literal> is acceptable.
426 Third parties, when defining their own categories, should discuss
427 the possibility of standardizing on the hint with other parties, preferably
428 in a place such as the
429 <ulink url="http://freedesktop.org/mailman/listinfo/xdg">xdg</ulink>
431 <ulink url="http://freedesktop.org/">freedesktop.org</ulink>. If it
432 warrants a standard, it will be added to the table above. If no
433 consensus is reached, the category should be in the form of
434 "<literal>x-<replaceable>vendor</replaceable>.<replaceable>class</replaceable>.<replaceable>name</replaceable></literal>."
437 The following table lists standard notifications as defined by this spec.
438 More will be added in time.
441 <title>Categories</title>
446 <entry>Description</entry>
451 <entry><literal>"device"</literal></entry>
453 A generic device-related notification that doesn't fit into
458 <entry><literal>"device.added"</literal></entry>
459 <entry>A device, such as a USB device, was added to the system.</entry>
462 <entry><literal>"device.error"</literal></entry>
463 <entry>A device had some kind of error.</entry>
466 <entry><literal>"device.removed"</literal></entry>
468 A device, such as a USB device, was removed from the system.
472 <entry><literal>"email"</literal></entry>
474 A generic e-mail-related notification that doesn't fit into any
479 <entry><literal>"email.arrived"</literal></entry>
480 <entry>A new e-mail notification.</entry>
483 <entry><literal>"email.bounced"</literal></entry>
484 <entry>A notification stating that an e-mail has bounced.</entry>
487 <entry><literal>"im"</literal></entry>
489 A generic instant message-related notification that doesn't fit
490 into any other category.
494 <entry><literal>"im.error"</literal></entry>
495 <entry>An instant message error notification.</entry>
498 <entry><literal>"im.received"</literal></entry>
499 <entry>A received instant message notification.</entry>
502 <entry><literal>"network"</literal></entry>
504 A generic network notification that doesn't fit into any other
509 <entry><literal>"network.connected"</literal></entry>
511 A network connection notification, such as successful sign-on to a
512 network service. This should not be confused with
513 <literal>device.added</literal> for new network devices.
517 <entry><literal>"network.disconnected"</literal></entry>
519 A network disconnected notification. This should not be confused with
520 <literal>device.removed</literal> for disconnected network devices.
524 <entry><literal>"network.error"</literal></entry>
526 A network-related or connection-related error.
530 <entry><literal>"presence"</literal></entry>
532 A generic presence change notification that doesn't fit into
533 any other category, such as going away or idle.
537 <entry><literal>"presence.offline"</literal></entry>
538 <entry>An offline presence change notification.</entry>
541 <entry><literal>"presence.online"</literal></entry>
542 <entry>An online presence change notification.</entry>
545 <entry><literal>"transfer"</literal></entry>
547 A generic file transfer or download notification that doesn't fit
548 into any other category.
552 <entry><literal>"transfer.complete"</literal></entry>
553 <entry>A file transfer or download complete notification.</entry>
556 <entry><literal>"transfer.error"</literal></entry>
557 <entry>A file transfer or download error.</entry>
564 <sect1 id="urgency-levels" xreflabel="Urgency Levels">
565 <title>Urgency Levels</title>
567 Notifications have an urgency level associated with them. This defines
568 the importance of the notification. For example, "Joe Bob signed on"
569 would be a low urgency. "You have new mail" or "A USB device was unplugged"
570 would be a normal urgency. "Your computer is on fire" would be a critical
573 <para>Urgency levels are defined as follows:</para>
575 <title>Urgency Levels</title>
580 <entry>Description</entry>
590 <entry>Normal</entry>
594 <entry>Critical</entry>
600 Developers must use their own judgement when deciding the urgency of a
601 notification. Typically, if the majority of programs are using the same
602 level for a specific type of urgency, other applications should follow
606 For low and normal urgencies, server implementations may display the
607 notifications how they choose. They should, however, have a sane
608 expiration timeout dependent on the urgency level.
611 Critical notifications should not automatically expire, as they are
612 things that the user will most likely want to know about. They should
613 only be closed when the user dismisses them, for example, by clicking on
618 <sect1 id="hints" xreflabel="Hints">
621 Hints are a way to provide extra data to a notification server that
622 the server may be able to make use of.
625 Neither clients nor notification servers are required to support any
626 hints. Both sides should assume that hints are not passed, and should
627 ignore any hints they do not understand.
630 Third parties, when defining their own hints, should discuss the
631 possibility of standardizing on the hint with other parties, preferably
632 in a place such as the
633 <ulink url="http://freedesktop.org/mailman/listinfo/xdg">xdg</ulink>
635 <ulink url="http://freedesktop.org/">freedesktop.org</ulink>. If it
636 warrants a standard, it will be added to the table above. If no
637 consensus is reached, the hint name should be in the form of
638 <literal>"x-<replaceable>vendor</replaceable>-<replaceable>name</replaceable>."</literal>
641 The value type for the hint dictionary in D-BUS is of the
642 <literal>DBUS_TYPE_VARIANT</literal> container type. This allows different
643 data types (string, integer, boolean, etc.) to be used for hints. When
644 adding a dictionary of hints, this type must be used, rather than putting
645 the actual hint value in as the dictionary value.
648 The following table lists the standard hints as defined by this
649 specification. Future hints may be proposed and added to this list
650 over time. Once again, implementations are not required to support these.
653 <title>Standard Hints</title>
658 <entry>Value Type</entry>
659 <entry>Description</entry>
660 <entry>Spec Version</entry>
665 <entry><literal>"action-icons"</literal></entry>
666 <entry>boolean</entry>
668 When set, a server that has the "action-icons" capability will
669 attempt to interpret any action identifier as a named icon.
670 The localized display name will be used to annotate the icon
671 for accessibility purposes. The icon name should be compliant
672 with the Freedesktop.org Icon Naming Specification.
674 <entry>>= 1.2</entry>
677 <entry><literal>"category"</literal></entry>
678 <entry>string</entry>
680 The type of notification this is.
685 <entry><literal>"desktop-entry"</literal></entry>
686 <entry>string</entry>
688 This specifies the name of the desktop filename representing the
689 calling program. This should be the same as the prefix used for the
690 application's .desktop file. An example would be "rhythmbox" from
691 "rhythmbox.desktop". This can be used by the daemon to retrieve the
692 correct icon for the application, for logging purposes, etc.
697 <entry><literal>"image-data"</literal></entry>
698 <entry>(iiibiiay)</entry>
700 This is a raw data image format which describes the width, height,
701 rowstride, has alpha, bits per sample, channels and image data
704 <entry>>= 1.2</entry>
707 <entry><literal>"image_data"</literal></entry>
708 <entry>(iiibiiay)</entry>
710 <emphasis>Deprecated</emphasis>. Use image-data instead.
715 <entry><literal>"image-path"</literal></entry>
716 <entry>string</entry>
718 Alternative way to define the notification image. See <xref linkend="icons-and-images"/>.
720 <entry>>= 1.2</entry>
723 <entry><literal>"image_path"</literal></entry>
724 <entry>string</entry>
726 <emphasis>Deprecated</emphasis>. Use image-path instead.
731 <entry><literal>"icon_data"</literal></entry>
732 <entry>(iiibiiay)</entry>
734 <emphasis>Deprecated</emphasis>. Use image-data instead.
736 <entry>< 1.1</entry>
739 <entry><literal>"resident"</literal></entry>
740 <entry>boolean</entry>
742 When set the server will not automatically remove the
743 notification when an action has been invoked. The notification
744 will remain resident in the server until it is explicitly
745 removed by the user or by the sender. This hint is likely only
746 useful when the server has the "persistence" capability.
748 <entry>>= 1.2</entry>
751 <entry><literal>"sound-file"</literal></entry>
752 <entry>string</entry>
754 The path to a sound file to play when the notification pops up.
759 <entry><literal>"sound-name"</literal></entry>
760 <entry>string</entry>
762 A themeable named sound from the freedesktop.org
763 <ulink url="http://0pointer.de/public/sound-naming-spec.html">sound naming specification</ulink>
764 to play when the notification pops up. Similar to icon-name, only for
765 sounds. An example would be "message-new-instant".
770 <entry><literal>"suppress-sound"</literal></entry>
771 <entry>boolean</entry>
773 Causes the server to suppress playing any sounds, if it has that
774 ability. This is usually set when the client itself is going to
780 <entry><literal>"transient"</literal></entry>
781 <entry>boolean</entry>
783 When set the server will treat the notification as transient
784 and by-pass the server's persistence capability, if it should
787 <entry>>= 1.2</entry>
790 <entry><literal>"x"</literal></entry>
793 Specifies the X location on the screen that the notification should
794 point to. The <literal>"y"</literal> hint must also be specified.
799 <entry><literal>"y"</literal></entry>
802 Specifies the Y location on the screen that the notification should
803 point to. The <literal>"x"</literal> hint must also be specified.
808 <entry><literal>"urgency"</literal></entry>
820 <sect1 id="protocol" xreflabel="Protocol">
821 <title>D-BUS Protocol</title>
823 The following messages <emphasis>must</emphasis> be supported by all
827 <sect2 id="commands">
828 <title>Message commands</title>
830 <sect3 id="command-get-capabilities">
831 <title><literal>org.freedesktop.Notifications.GetCapabilities</literal></title>
834 <funcdef>STRING_ARRAY
835 <function>org.freedesktop.Notifications.GetCapabilities</function>
841 This message takes no parameters.
844 It returns an array of strings. Each string describes an optional
845 capability implemented by the server. The following values are
846 defined by this spec:
849 <title>Server Capabilities</title>
853 <entry><literal>"action-icons"</literal></entry>
855 Supports using icons instead of text for displaying actions.
856 Using icons for actions must be enabled on a per-notification
857 basis using the "action-icons" hint.
861 <entry><literal>"actions"</literal></entry>
863 The server will provide the specified actions to the user. Even if
864 this cap is missing, actions may still be specified by the client,
865 however the server is free to ignore them.
869 <entry><literal>"body"</literal></entry>
871 Supports body text. Some implementations may only show the
872 summary (for instance, onscreen displays, marquee/scrollers)
876 <entry><literal>"body-hyperlinks"</literal></entry>
878 The server supports hyperlinks in the notifications.
882 <entry><literal>"body-images"</literal></entry>
884 The server supports images in the notifications.
888 <entry><literal>"body-markup"</literal></entry>
890 Supports markup in the body text. If marked up text is sent
891 to a server that does not give this cap, the markup will show
892 through as regular text so must be stripped clientside.
896 <entry><literal>"icon-multi"</literal></entry>
898 The server will render an animation of all the frames in a given
899 image array. The client may still specify multiple frames even if
900 this cap and/or <literal>"icon-static"</literal> is missing, however
901 the server is free to ignore them and use only the primary frame.
905 <entry><literal>"icon-static"</literal></entry>
907 Supports display of exactly 1 frame of any given image array.
908 This value is mutually exclusive with
909 <literal>"icon-multi"</literal>, it is a protocol error for the
910 server to specify both.
914 <entry><literal>"persistence"</literal></entry>
916 The server supports persistence of notifications.
917 Notifications will be retained until they are acknowledged or
918 removed by the user or recalled by the sender. The presence
919 of this capability allows clients to depend on the server to
920 ensure a notification is seen and eliminate the need for
921 the client to display a reminding function (such as a status
926 <entry><literal>"sound"</literal></entry>
928 The server supports sounds on notifications. If returned, the
929 server must support the <literal>"sound-file"</literal> and
930 <literal>"suppress-sound"</literal> hints.
937 New vendor-specific caps may be specified as long as they start with
938 <literal>"x-<replaceable>vendor</replaceable>"</literal>. For instance,
939 <literal>"x-gnome-foo-cap"</literal>. Capability names must not
940 contain spaces. They are limited to alpha-numeric characters and dashes
941 (<literal>"-"</literal>).
945 <sect3 id="command-notify">
946 <title><literal>org.freedesktop.Notifications.Notify</literal></title>
950 <function>org.freedesktop.Notifications.Notify</function>
952 <paramdef>STRING <parameter>app_name</parameter></paramdef>
953 <paramdef>UINT32 <parameter>replaces_id</parameter></paramdef>
954 <paramdef>STRING <parameter>app_icon</parameter></paramdef>
955 <paramdef>STRING <parameter>summary</parameter></paramdef>
956 <paramdef>STRING <parameter>body</parameter></paramdef>
957 <paramdef>ARRAY <parameter>actions</parameter></paramdef>
958 <paramdef>DICT <parameter>hints</parameter></paramdef>
959 <paramdef>INT32 <parameter>expire_timeout</parameter></paramdef>
963 Sends a notification to the notification server.
966 <title>Notify Parameters</title>
972 <entry>Description</entry>
977 <entry><parameter>app_name</parameter></entry>
978 <entry>STRING</entry>
980 The optional name of the application sending the notification.
985 <entry><parameter>replaces_id</parameter></entry>
986 <entry>UINT32</entry>
988 The optional notification ID that this notification replaces. The
989 server must atomically (ie with no flicker or other visual cues)
990 replace the given notification with this one. This allows clients to
991 effectively modify the notification while it's active. A value of
992 value of 0 means that this notification won't replace any
993 existing notifications.
997 <entry><parameter>app_icon</parameter></entry>
998 <entry>STRING</entry>
1000 The optional program icon of the calling application. See <xref linkend="icons-and-images"/>.
1001 Can be an empty string, indicating no icon.
1005 <entry><parameter>summary</parameter></entry>
1006 <entry>STRING</entry>
1007 <entry>The summary text briefly describing the notification.</entry>
1010 <entry><parameter>body</parameter></entry>
1011 <entry>STRING</entry>
1012 <entry>The optional detailed body text. Can be empty.</entry>
1015 <entry><parameter>actions</parameter></entry>
1016 <entry>ARRAY</entry>
1018 Actions are sent over as a list of pairs. Each even element in
1019 the list (starting at index 0) represents the identifier for the
1020 action. Each odd element in the list is the localized string
1021 that will be displayed to the user.
1025 <entry><parameter>hints</parameter></entry>
1028 Optional hints that can be passed to the server from the client
1029 program. Although clients and servers should never assume each other
1030 supports any specific hints, they can be used to pass along
1031 information, such as the process PID or window ID, that the server
1032 may be able to make use of. See <xref linkend="hints"/>. Can be
1037 <entry><parameter>expire_timeout</parameter></entry>
1038 <entry>INT32</entry>
1041 The timeout time in milliseconds since the display of the notification at
1042 which the notification should automatically close.
1045 If -1, the notification's expiration time is dependent on the
1046 notification server's settings, and may vary for the type of
1057 If <parameter>replaces_id</parameter> is 0, the return value is a
1058 UINT32 that represent the notification. It is unique, and will not be
1059 reused unless a <constant>MAXINT</constant> number of notifications
1060 have been generated. An acceptable implementation may just use an
1061 incrementing counter for the ID. The returned ID is always greater than
1062 zero. Servers must make sure not to return zero as an ID.
1065 If <parameter>replaces_id</parameter> is not 0, the returned value
1066 is the same value as <parameter>replaces_id</parameter>.
1070 <sect3 id="command-close-notification">
1071 <title><literal>org.freedesktop.Notifications.CloseNotification</literal></title>
1075 <function>org.freedesktop.Notifications.CloseNotification</function>
1077 <paramdef>UINT32 id</paramdef>
1081 Causes a notification to be forcefully closed and removed from the user's
1082 view. It can be used, for example, in the event that what the
1083 notification pertains to is no longer relevant, or to cancel a
1084 notification with no expiration time.
1087 The <literal>NotificationClosed</literal> signal is emitted by this
1091 If the notification no longer exists, an empty D-BUS Error message is
1096 <sect3 id="command-get-server-information">
1097 <title><literal>org.freedesktop.Notifications.GetServerInformation</literal></title>
1102 <function>org.freedesktop.Notifications.GetServerInformation</function>
1104 <paramdef>out STRING <parameter>name</parameter></paramdef>
1105 <paramdef>out STRING <parameter>vendor</parameter></paramdef>
1106 <paramdef>out STRING <parameter>version</parameter></paramdef>
1107 <paramdef>out STRING <parameter>spec_version</parameter></paramdef>
1111 This message returns the information on the server. Specifically,
1112 the server name, vendor, and version number.
1115 <title>GetServerInformation Return Values</title>
1121 <entry>Description</entry>
1124 <tbody valign="top">
1126 <entry><parameter>name</parameter></entry>
1127 <entry>STRING</entry>
1128 <entry>The product name of the server.</entry>
1131 <entry><parameter>vendor</parameter></entry>
1132 <entry>STRING</entry>
1134 The vendor name. For example, "KDE," "GNOME,"
1135 "freedesktop.org," or "Microsoft."
1139 <entry><parameter>version</parameter></entry>
1140 <entry>STRING</entry>
1141 <entry>The server's version number.</entry>
1144 <entry><parameter>spec_version</parameter></entry>
1145 <entry>STRING</entry>
1146 <entry>The specification version the server is compliant with.</entry>
1154 <sect2 id="signals">
1155 <title>Signals</title>
1157 <sect3 id="signal-notification-closed">
1158 <title><literal>org.freedesktop.Notifications.NotificationClosed</literal></title>
1162 <function>org.freedesktop.Notifications.NotificationClosed</function>
1164 <paramdef>UINT32 <parameter>id</parameter></paramdef>
1165 <paramdef>UINT32 <parameter>reason</parameter></paramdef>
1169 A completed notification is one that has timed out, or has been
1170 dismissed by the user.
1173 <title>NotificationClosed Parameters</title>
1179 <entry>Description</entry>
1182 <tbody valign="top">
1184 <entry><parameter>id</parameter></entry>
1185 <entry>UINT32</entry>
1186 <entry>The ID of the notification that was closed.</entry>
1189 <entry><parameter>reason</parameter></entry>
1190 <entry>UINT32</entry>
1192 <para>The reason the notification was closed.</para>
1193 <para>1 - The notification expired.</para>
1194 <para>2 - The notification was dismissed by the user.</para>
1195 <para>3 - The notification was closed by a call to
1196 <literal>CloseNotification</literal>.</para>
1197 <para>4 - Undefined/reserved reasons.</para>
1204 The ID specified in the signal is invalidated
1205 <emphasis>before</emphasis> the signal is sent and may not be used
1206 in any further communications with the server.
1210 <sect3 id="signal-action-invoked">
1211 <title><literal>org.freedesktop.Notifications.ActionInvoked</literal></title>
1215 <function>org.freedesktop.Notifications.ActionInvoked</function>
1217 <paramdef>UINT32 <parameter>id</parameter></paramdef>
1218 <paramdef>STRING <parameter>action_key</parameter></paramdef>
1222 This signal is emitted when one of the following occurs:
1227 The user performs some global "invoking" action upon a notification.
1228 For instance, clicking somewhere on the notification itself.
1233 The user invokes a specific action as specified in the original
1234 Notify request. For example, clicking on an action button.
1239 <title>ActionInvoked Parameters</title>
1245 <entry>Description</entry>
1248 <tbody valign="top">
1250 <entry><parameter>id</parameter></entry>
1251 <entry>UINT32</entry>
1253 The ID of the notification emitting the ActionInvoked signal.
1257 <entry><parameter>action_key</parameter></entry>
1258 <entry>STRING</entry>
1260 The key of the action invoked. These match the keys sent over
1261 in the list of actions.
1269 Clients should not assume the server will generate this signal. Some
1270 servers may not support user interaction at all, or may not support
1271 the concept of being able to "invoke" a notification.