src/lib/notification/notification-spec.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE article PUBLIC "-//OASIS/DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   3 <article id="index">
   4  <articleinfo>
   5   <title>Desktop Notifications Specification</title>
   6   <releaseinfo>Version 1.2</releaseinfo>
   7   <date>28 October 2010</date>
   8   <authorgroup>
   9    <author>
  10     <firstname>Mike</firstname>
  11     <surname>Hearn</surname>
  12     <affiliation>
  13      <address>
  14       <email>mike@navi.cx</email>
  15      </address>
  16     </affiliation>
  17    </author>
  18    <author>
  19     <firstname>Christian</firstname>
  20     <surname>Hammond</surname>
  21     <affiliation>
  22      <address>
  23       <email>chipx86@chipx86.com</email>
  24      </address>
  25     </affiliation>
  26    </author>
  27    <author>
  28     <firstname>William Jon</firstname>
  29     <surname>McCann</surname>
  30     <affiliation>
  31      <address>
  32       <email>jmccann@redhat.com</email>
  33      </address>
  34     </affiliation>
  35    </author>
  36   </authorgroup>
  37  </articleinfo>
  38
  39  <sect1 id="introduction">
  40   <title>Introduction</title>
  41   <para>
  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.
  45   </para>
  46   <para>
  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.
  50   </para>
  51   <para>
  52    Example use cases include:
  53   </para>
  54   <itemizedlist>
  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>
  60   </itemizedlist>
  61  </sect1>
  62
  63  <sect1 id="basic-design">
  64   <title>Basic Design</title>
  65   <para>
  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.
  70   </para>
  71   <para>
  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.
  78   </para>
  79   <para>
  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.
  84   </para>
  85   <para>
  86    A notification has the following components:
  87   </para>
  88   <table>
  89    <title>Notification Components</title>
  90    <tgroup cols="2">
  91     <thead>
  92      <row>
  93       <entry>Component</entry>
  94       <entry>Description</entry>
  95      </row>
  96     </thead>
  97     <tbody valign="top">
  98      <row>
  99       <entry>Application Name</entry>
 100       <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."
 105       </entry>
 106      </row>
 107      <row>
 108       <entry>Replaces ID</entry>
 109       <entry>
 110        An optional ID of an existing notification that this
 111        notification is intended to replace.
 112       </entry>
 113      </row>
 114      <row>
 115       <entry>Notification Icon</entry>
 116       <entry>
 117         The notification icon. See <xref linkend="icons-and-images-formats"/>.
 118       </entry>
 119      </row>
 120      <row>
 121       <entry>Summary</entry>
 122       <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.
 128       </entry>
 129      </row>
 130      <row>
 131       <entry>Body</entry>
 132       <entry>
 133        <para>
 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.
 136        </para>
 137        <para>
 138         The body may contain simple markup as specified in
 139         <xref linkend="markup"/>. It must be encoded using UTF-8.
 140        </para>
 141        <para>
 142         If the body is omitted, just the summary is displayed.
 143        </para>
 144       </entry>
 145      </row>
 146      <row>
 147       <entry>Actions</entry>
 148       <entry>
 149        <para>
 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.
 157        </para>
 158        <para>
 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.
 163        </para>
 164        <para>
 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.
 168        </para>
 169       </entry>
 170      </row>
 171      <row>
 172       <entry>Hints</entry>
 173       <entry>
 174        <para>
 175         Hints are a way to provide extra data to a notification server that
 176         the server may be able to make use of.
 177        </para>
 178        <para>See <xref linkend="hints"/> for a list of available hints.</para>
 179       </entry>
 180      </row>
 181      <row>
 182       <entry>Expiration Timeout</entry>
 183       <entry>
 184        <para>
 185         The timeout time in milliseconds since the display of the notification
 186         at which the notification should automatically close.
 187        </para>
 188        <para>
 189         If -1, the notification's expiration time is dependent on the
 190         notification server's settings, and may vary for the type of
 191         notification.
 192        </para>
 193        <para>
 194         If 0, the notification never expires.
 195        </para>
 196       </entry>
 197      </row>
 198     </tbody>
 199    </tgroup>
 200   </table>
 201   <para>
 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
 205    exceeded.
 206   </para>
 207   <para>
 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.
 212   </para>
 213  </sect1>
 214
 215  <sect1 id="backwards-compat" xreflabel="Backwards Compatibility">
 216   <title>Backwards Compatibility</title>
 217   <para>
 218    Clients should try and avoid making assumptions about the presentation and
 219    abilities of the notification server. The message content is the most
 220    important thing.
 221   </para>
 222   <para>
 223    Clients can check with the server what capabilities are supported
 224    using the <literal>GetCapabilities</literal> message. See
 225    <xref linkend="protocol"/>.
 226   </para>
 227   <para>
 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.
 231   </para>
 232  </sect1>
 233
 234  <sect1 id="markup" xreflabel="Markup">
 235   <title>Markup</title>
 236   <para>
 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.
 239   </para>
 240   <para>
 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.
 244   </para>
 245   <informaltable>
 246    <tgroup cols="2">
 247     <tbody valign="top">
 248      <row>
 249       <entry>
 250        <sgmltag class="starttag">b</sgmltag> ...
 251        <sgmltag class="endtag">b</sgmltag>
 252       </entry>
 253       <entry>Bold</entry>
 254      </row>
 255      <row>
 256       <entry>
 257        <sgmltag class="starttag">i</sgmltag> ...
 258        <sgmltag class="endtag">i</sgmltag>
 259       </entry>
 260       <entry>Italic</entry>
 261      </row>
 262      <row>
 263       <entry>
 264        <sgmltag class="starttag">u</sgmltag> ...
 265        <sgmltag class="endtag">u</sgmltag>
 266       </entry>
 267       <entry>Underline</entry>
 268      </row>
 269      <row>
 270       <entry>
 271        <sgmltag class="starttag">a href="..."</sgmltag> ...
 272        <sgmltag class="endtag">a</sgmltag>
 273       </entry>
 274       <entry>Hyperlink</entry>
 275      </row>
 276      <row>
 277       <entry>
 278        <sgmltag class="emptytag">img src="..." alt="..."</sgmltag>
 279       </entry>
 280       <entry>Image</entry>
 281      </row>
 282     </tbody>
 283    </tgroup>
 284   </informaltable>
 285   <para>
 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.
 293   </para>
 294   <para>
 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.
 299   </para>
 300   <para>
 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
 303    content.
 304   </para>
 305
 306   <sect2 id="hyperlinks" xreflabel="Hyperlinks">
 307    <title>Hyperlinks</title>
 308    <para>
 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.
 313    </para>
 314    <para>
 315     Hyperlinked text should appear in the standard blue underline format.
 316    </para>
 317    <para>
 318     Hyperlinks cannot function as a replacement for actions. They are
 319     used to link to local directories or remote sites using standard URI
 320     schemes.
 321    </para>
 322    <para>
 323     Implementations are not required to support hyperlinks.
 324    </para>
 325   </sect2>
 326
 327   <sect2 id="images" xreflabel="Images">
 328    <title>Images</title>
 329    <para>
 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.
 334    </para>
 335    <para>
 336     Image data cannot be embedded in the message itself. Images referenced
 337     must always be local files.
 338    </para>
 339    <para>
 340     Implementations are not required to support images.
 341    </para>
 342   </sect2>
 343  </sect1>
 344
 345  <sect1 id="icons-and-images" xreflabel="Icons and Images">
 346   <title>Icons and Images</title>
 347   <para>
 348    A notification can optionally have an associated icon and/or image.
 349   </para>
 350   <para>
 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.
 354   </para>
 355   <sect2>
 356    <title>Priorities</title>
 357    <para>
 358     An implementation which only displays one image or icon must choose which one
 359     to display using the following order:
 360     <orderedlist>
 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>
 365     </orderedlist>
 366    </para>
 367
 368    <para>
 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
 371     the following order:
 372     <orderedlist>
 373      <listitem><para>"image-data"</para></listitem>
 374      <listitem><para>"image-path"</para></listitem>
 375      <listitem><para>for compatibility reason, "icon_data"</para></listitem>
 376     </orderedlist>
 377    </para>
 378   </sect2>
 379
 380   <sect2 id="icons-and-images-formats" xreflabel="Icons and Images Formats">
 381    <title>Formats</title>
 382    <para>
 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:
 385     <orderedlist>
 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>
 393     </orderedlist>
 394     This image format is derived from <ulink url="http://developer.gnome.org/gdk-pixbuf/stable/">gdk-pixbuf</ulink>.
 395   </para>
 396    <para>
 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).
 400    </para>
 401   </sect2>
 402  </sect1>
 403
 404  <sect1 id="categories" xreflabel="Categories">
 405   <title>Categories</title>
 406   <para>
 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
 411    types.
 412   </para>
 413   <para>
 414    Categories are in
 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
 418    notification.
 419   </para>
 420   <para>
 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.
 424   </para>
 425   <para>
 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>
 430    mailing list at
 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>."
 435   </para>
 436   <para>
 437    The following table lists standard notifications as defined by this spec.
 438    More will be added in time.
 439   </para>
 440   <table>
 441    <title>Categories</title>
 442    <tgroup cols="2">
 443     <thead>
 444      <row>
 445       <entry>Type</entry>
 446       <entry>Description</entry>
 447      </row>
 448     </thead>
 449     <tbody valign="top">
 450      <row>
 451       <entry><literal>"device"</literal></entry>
 452       <entry>
 453        A generic device-related notification that doesn't fit into
 454        any other category.
 455       </entry>
 456      </row>
 457      <row>
 458       <entry><literal>"device.added"</literal></entry>
 459       <entry>A device, such as a USB device, was added to the system.</entry>
 460      </row>
 461      <row>
 462       <entry><literal>"device.error"</literal></entry>
 463       <entry>A device had some kind of error.</entry>
 464      </row>
 465      <row>
 466       <entry><literal>"device.removed"</literal></entry>
 467       <entry>
 468        A device, such as a USB device, was removed from the system.
 469       </entry>
 470      </row>
 471      <row>
 472       <entry><literal>"email"</literal></entry>
 473       <entry>
 474        A generic e-mail-related notification that doesn't fit into any
 475        other category.
 476       </entry>
 477      </row>
 478      <row>
 479       <entry><literal>"email.arrived"</literal></entry>
 480       <entry>A new e-mail notification.</entry>
 481      </row>
 482      <row>
 483       <entry><literal>"email.bounced"</literal></entry>
 484       <entry>A notification stating that an e-mail has bounced.</entry>
 485      </row>
 486      <row>
 487       <entry><literal>"im"</literal></entry>
 488       <entry>
 489        A generic instant message-related notification that doesn't fit
 490        into any other category.
 491       </entry>
 492      </row>
 493      <row>
 494       <entry><literal>"im.error"</literal></entry>
 495       <entry>An instant message error notification.</entry>
 496      </row>
 497      <row>
 498       <entry><literal>"im.received"</literal></entry>
 499       <entry>A received instant message notification.</entry>
 500      </row>
 501      <row>
 502       <entry><literal>"network"</literal></entry>
 503       <entry>
 504        A generic network notification that doesn't fit into any other
 505        category.
 506       </entry>
 507      </row>
 508      <row>
 509       <entry><literal>"network.connected"</literal></entry>
 510       <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.
 514       </entry>
 515      </row>
 516      <row>
 517       <entry><literal>"network.disconnected"</literal></entry>
 518       <entry>
 519        A network disconnected notification. This should not be confused with
 520        <literal>device.removed</literal> for disconnected network devices.
 521       </entry>
 522      </row>
 523      <row>
 524       <entry><literal>"network.error"</literal></entry>
 525       <entry>
 526        A network-related or connection-related error.
 527       </entry>
 528      </row>
 529      <row>
 530       <entry><literal>"presence"</literal></entry>
 531       <entry>
 532        A generic presence change notification that doesn't fit into
 533        any other category, such as going away or idle.
 534       </entry>
 535      </row>
 536      <row>
 537       <entry><literal>"presence.offline"</literal></entry>
 538       <entry>An offline presence change notification.</entry>
 539      </row>
 540      <row>
 541       <entry><literal>"presence.online"</literal></entry>
 542       <entry>An online presence change notification.</entry>
 543      </row>
 544      <row>
 545       <entry><literal>"transfer"</literal></entry>
 546       <entry>
 547        A generic file transfer or download notification that doesn't fit
 548        into any other category.
 549       </entry>
 550      </row>
 551      <row>
 552       <entry><literal>"transfer.complete"</literal></entry>
 553       <entry>A file transfer or download complete notification.</entry>
 554      </row>
 555      <row>
 556       <entry><literal>"transfer.error"</literal></entry>
 557       <entry>A file transfer or download error.</entry>
 558      </row>
 559     </tbody>
 560    </tgroup>
 561   </table>
 562  </sect1>
 563
 564  <sect1 id="urgency-levels" xreflabel="Urgency Levels">
 565   <title>Urgency Levels</title>
 566   <para>
 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
 571    urgency.
 572   </para>
 573   <para>Urgency levels are defined as follows:</para>
 574   <table>
 575    <title>Urgency Levels</title>
 576    <tgroup cols="2">
 577     <thead>
 578      <row>
 579       <entry>Type</entry>
 580       <entry>Description</entry>
 581      </row>
 582     </thead>
 583     <tbody valign="top">
 584      <row>
 585       <entry>0</entry>
 586       <entry>Low</entry>
 587      </row>
 588      <row>
 589       <entry>1</entry>
 590       <entry>Normal</entry>
 591      </row>
 592      <row>
 593       <entry>2</entry>
 594       <entry>Critical</entry>
 595      </row>
 596     </tbody>
 597    </tgroup>
 598   </table>
 599   <para>
 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
 603    them.
 604   </para>
 605   <para>
 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.
 609   </para>
 610   <para>
 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
 614    the notification.
 615   </para>
 616  </sect1>
 617
 618  <sect1 id="hints" xreflabel="Hints">
 619   <title>Hints</title>
 620   <para>
 621    Hints are a way to provide extra data to a notification server that
 622    the server may be able to make use of.
 623   </para>
 624   <para>
 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.
 628   </para>
 629   <para>
 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>
 634    mailing list at
 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>
 639   </para>
 640   <para>
 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.
 646   </para>
 647   <para>
 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.
 651   </para>
 652   <table>
 653    <title>Standard Hints</title>
 654    <tgroup cols="2">
 655     <thead>
 656      <row>
 657       <entry>Name</entry>
 658       <entry>Value Type</entry>
 659       <entry>Description</entry>
 660       <entry>Spec Version</entry>
 661      </row>
 662     </thead>
 663     <tbody valign="top">
 664      <row>
 665       <entry><literal>"action-icons"</literal></entry>
 666       <entry>boolean</entry>
 667       <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.
 673       </entry>
 674       <entry>&gt;= 1.2</entry>
 675      </row>
 676      <row>
 677       <entry><literal>"category"</literal></entry>
 678       <entry>string</entry>
 679       <entry>
 680        The type of notification this is.
 681       </entry>
 682       <entry/>
 683      </row>
 684      <row>
 685       <entry><literal>"desktop-entry"</literal></entry>
 686       <entry>string</entry>
 687       <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.
 693       </entry>
 694       <entry/>
 695      </row>
 696      <row>
 697       <entry><literal>"image-data"</literal></entry>
 698       <entry>(iiibiiay)</entry>
 699       <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
 702         respectively.
 703       </entry>
 704       <entry>&gt;= 1.2</entry>
 705      </row>
 706      <row>
 707       <entry><literal>"image_data"</literal></entry>
 708       <entry>(iiibiiay)</entry>
 709       <entry>
 710         <emphasis>Deprecated</emphasis>. Use image-data instead.
 711       </entry>
 712       <entry>= 1.1</entry>
 713      </row>
 714      <row>
 715       <entry><literal>"image-path"</literal></entry>
 716       <entry>string</entry>
 717       <entry>
 718         Alternative way to define the notification image. See <xref linkend="icons-and-images"/>.
 719       </entry>
 720       <entry>&gt;= 1.2</entry>
 721      </row>
 722      <row>
 723       <entry><literal>"image_path"</literal></entry>
 724       <entry>string</entry>
 725       <entry>
 726         <emphasis>Deprecated</emphasis>. Use image-path instead.
 727       </entry>
 728       <entry>= 1.1</entry>
 729      </row>
 730      <row>
 731       <entry><literal>"icon_data"</literal></entry>
 732       <entry>(iiibiiay)</entry>
 733       <entry>
 734         <emphasis>Deprecated</emphasis>. Use image-data instead.
 735       </entry>
 736       <entry>&lt; 1.1</entry>
 737      </row>
 738      <row>
 739       <entry><literal>"resident"</literal></entry>
 740       <entry>boolean</entry>
 741       <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.
 747       </entry>
 748       <entry>&gt;= 1.2</entry>
 749      </row>
 750      <row>
 751       <entry><literal>"sound-file"</literal></entry>
 752       <entry>string</entry>
 753       <entry>
 754        The path to a sound file to play when the notification pops up.
 755       </entry>
 756       <entry/>
 757      </row>
 758      <row>
 759       <entry><literal>"sound-name"</literal></entry>
 760       <entry>string</entry>
 761       <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".
 766       </entry>
 767       <entry/>
 768      </row>
 769      <row>
 770       <entry><literal>"suppress-sound"</literal></entry>
 771       <entry>boolean</entry>
 772       <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
 775        play its own sound.
 776       </entry>
 777       <entry/>
 778      </row>
 779      <row>
 780       <entry><literal>"transient"</literal></entry>
 781       <entry>boolean</entry>
 782       <entry>
 783        When set the server will treat the notification as transient
 784        and by-pass the server's persistence capability, if it should
 785        exist.
 786       </entry>
 787       <entry>&gt;= 1.2</entry>
 788      </row>
 789      <row>
 790       <entry><literal>"x"</literal></entry>
 791       <entry>int</entry>
 792       <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.
 795       </entry>
 796       <entry/>
 797      </row>
 798      <row>
 799       <entry><literal>"y"</literal></entry>
 800       <entry>int</entry>
 801       <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.
 804       </entry>
 805       <entry/>
 806      </row>
 807      <row>
 808       <entry><literal>"urgency"</literal></entry>
 809       <entry>byte</entry>
 810       <entry>
 811        The urgency level.
 812       </entry>
 813       <entry/>
 814      </row>
 815     </tbody>
 816    </tgroup>
 817   </table>
 818  </sect1>
 819
 820  <sect1 id="protocol" xreflabel="Protocol">
 821   <title>D-BUS Protocol</title>
 822   <para>
 823    The following messages <emphasis>must</emphasis> be supported by all
 824    implementations.
 825   </para>
 826
 827   <sect2 id="commands">
 828    <title>Message commands</title>
 829
 830    <sect3 id="command-get-capabilities">
 831     <title><literal>org.freedesktop.Notifications.GetCapabilities</literal></title>
 832     <funcsynopsis>
 833      <funcprototype>
 834       <funcdef>STRING_ARRAY
 835        <function>org.freedesktop.Notifications.GetCapabilities</function>
 836       </funcdef>
 837       <void/>
 838      </funcprototype>
 839     </funcsynopsis>
 840     <para>
 841      This message takes no parameters.
 842     </para>
 843     <para>
 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:
 847     </para>
 848     <table>
 849      <title>Server Capabilities</title>
 850      <tgroup cols="2">
 851       <tbody valign="top">
 852        <row>
 853         <entry><literal>"action-icons"</literal></entry>
 854         <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.
 858         </entry>
 859        </row>
 860        <row>
 861         <entry><literal>"actions"</literal></entry>
 862         <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.
 866         </entry>
 867        </row>
 868        <row>
 869         <entry><literal>"body"</literal></entry>
 870         <entry>
 871          Supports body text. Some implementations may only show the
 872          summary (for instance, onscreen displays, marquee/scrollers)
 873         </entry>
 874        </row>
 875        <row>
 876         <entry><literal>"body-hyperlinks"</literal></entry>
 877         <entry>
 878          The server supports hyperlinks in the notifications.
 879         </entry>
 880        </row>
 881        <row>
 882         <entry><literal>"body-images"</literal></entry>
 883         <entry>
 884          The server supports images in the notifications.
 885         </entry>
 886        </row>
 887        <row>
 888         <entry><literal>"body-markup"</literal></entry>
 889         <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.
 893         </entry>
 894        </row>
 895        <row>
 896         <entry><literal>"icon-multi"</literal></entry>
 897         <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.
 902         </entry>
 903        </row>
 904        <row>
 905         <entry><literal>"icon-static"</literal></entry>
 906         <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.
 911         </entry>
 912        </row>
 913        <row>
 914         <entry><literal>"persistence"</literal></entry>
 915         <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
 922          icon) of its own.
 923         </entry>
 924        </row>
 925        <row>
 926         <entry><literal>"sound"</literal></entry>
 927         <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.
 931         </entry>
 932        </row>
 933       </tbody>
 934      </tgroup>
 935     </table>
 936     <para>
 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>).
 942     </para>
 943    </sect3>
 944
 945    <sect3 id="command-notify">
 946     <title><literal>org.freedesktop.Notifications.Notify</literal></title>
 947     <funcsynopsis>
 948      <funcprototype>
 949       <funcdef>UINT32
 950        <function>org.freedesktop.Notifications.Notify</function>
 951       </funcdef>
 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>
 960      </funcprototype>
 961     </funcsynopsis>
 962     <para>
 963      Sends a notification to the notification server.
 964     </para>
 965     <table>
 966      <title>Notify Parameters</title>
 967      <tgroup cols="3">
 968       <thead>
 969        <row>
 970         <entry>Name</entry>
 971         <entry>Type</entry>
 972         <entry>Description</entry>
 973        </row>
 974       </thead>
 975       <tbody valign="top">
 976        <row>
 977         <entry><parameter>app_name</parameter></entry>
 978         <entry>STRING</entry>
 979         <entry>
 980          The optional name of the application sending the notification.
 981          Can be blank.
 982         </entry>
 983        </row>
 984        <row>
 985         <entry><parameter>replaces_id</parameter></entry>
 986         <entry>UINT32</entry>
 987         <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.
 994         </entry>
 995        </row>
 996        <row>
 997         <entry><parameter>app_icon</parameter></entry>
 998         <entry>STRING</entry>
 999         <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.
1002         </entry>
1003        </row>
1004        <row>
1005         <entry><parameter>summary</parameter></entry>
1006         <entry>STRING</entry>
1007         <entry>The summary text briefly describing the notification.</entry>
1008        </row>
1009        <row>
1010         <entry><parameter>body</parameter></entry>
1011         <entry>STRING</entry>
1012         <entry>The optional detailed body text. Can be empty.</entry>
1013        </row>
1014        <row>
1015         <entry><parameter>actions</parameter></entry>
1016         <entry>ARRAY</entry>
1017         <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.
1022         </entry>
1023        </row>
1024        <row>
1025         <entry><parameter>hints</parameter></entry>
1026         <entry>DICT</entry>
1027         <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
1033          empty.
1034         </entry>
1035        </row>
1036        <row>
1037         <entry><parameter>expire_timeout</parameter></entry>
1038         <entry>INT32</entry>
1039         <entry>
1040          <para>
1041           The timeout time in milliseconds since the display of the notification at
1042           which the notification should automatically close.
1043          </para>
1044          <para>
1045           If -1, the notification's expiration time is dependent on the
1046           notification server's settings, and may vary for the type of
1047           notification.
1048
1049           If 0, never expire.
1050          </para>
1051         </entry>
1052        </row>
1053       </tbody>
1054      </tgroup>
1055     </table>
1056     <para>
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.
1063     </para>
1064     <para>
1065      If <parameter>replaces_id</parameter> is not 0, the returned value
1066      is the same value as <parameter>replaces_id</parameter>.
1067     </para>
1068    </sect3>
1069
1070    <sect3 id="command-close-notification">
1071     <title><literal>org.freedesktop.Notifications.CloseNotification</literal></title>
1072     <funcsynopsis>
1073      <funcprototype>
1074       <funcdef>void
1075        <function>org.freedesktop.Notifications.CloseNotification</function>
1076       </funcdef>
1077       <paramdef>UINT32 id</paramdef>
1078      </funcprototype>
1079     </funcsynopsis>
1080     <para>
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.
1085     </para>
1086     <para>
1087      The <literal>NotificationClosed</literal> signal is emitted by this
1088      method.
1089     </para>
1090     <para>
1091      If the notification no longer exists, an empty D-BUS Error message is
1092      sent back.
1093     </para>
1094    </sect3>
1095
1096    <sect3 id="command-get-server-information">
1097     <title><literal>org.freedesktop.Notifications.GetServerInformation</literal></title>
1098     <funcsynopsis>
1099      <funcprototype>
1100       <funcdef>
1101        void
1102        <function>org.freedesktop.Notifications.GetServerInformation</function>
1103       </funcdef>
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>
1108      </funcprototype>
1109     </funcsynopsis>
1110     <para>
1111      This message returns the information on the server. Specifically,
1112      the server name, vendor, and version number.
1113     </para>
1114     <table>
1115      <title>GetServerInformation Return Values</title>
1116      <tgroup cols="2">
1117       <thead>
1118        <row>
1119         <entry>Name</entry>
1120         <entry>Type</entry>
1121         <entry>Description</entry>
1122        </row>
1123       </thead>
1124       <tbody valign="top">
1125        <row>
1126         <entry><parameter>name</parameter></entry>
1127         <entry>STRING</entry>
1128         <entry>The product name of the server.</entry>
1129        </row>
1130        <row>
1131         <entry><parameter>vendor</parameter></entry>
1132         <entry>STRING</entry>
1133         <entry>
1134          The vendor name. For example, "KDE," "GNOME,"
1135          "freedesktop.org," or "Microsoft."
1136         </entry>
1137        </row>
1138        <row>
1139         <entry><parameter>version</parameter></entry>
1140         <entry>STRING</entry>
1141         <entry>The server's version number.</entry>
1142        </row>
1143        <row>
1144         <entry><parameter>spec_version</parameter></entry>
1145         <entry>STRING</entry>
1146         <entry>The specification version the server is compliant with.</entry>
1147        </row>
1148       </tbody>
1149      </tgroup>
1150     </table>
1151    </sect3>
1152   </sect2>
1153
1154   <sect2 id="signals">
1155    <title>Signals</title>
1156
1157    <sect3 id="signal-notification-closed">
1158     <title><literal>org.freedesktop.Notifications.NotificationClosed</literal></title>
1159     <funcsynopsis>
1160      <funcprototype>
1161       <funcdef>
1162        <function>org.freedesktop.Notifications.NotificationClosed</function>
1163       </funcdef>
1164       <paramdef>UINT32 <parameter>id</parameter></paramdef>
1165       <paramdef>UINT32 <parameter>reason</parameter></paramdef>
1166      </funcprototype>
1167     </funcsynopsis>
1168     <para>
1169      A completed notification is one that has timed out, or has been
1170      dismissed by the user.
1171     </para>
1172     <table>
1173      <title>NotificationClosed Parameters</title>
1174      <tgroup cols="2">
1175       <thead>
1176        <row>
1177         <entry>Name</entry>
1178         <entry>Type</entry>
1179         <entry>Description</entry>
1180        </row>
1181       </thead>
1182       <tbody valign="top">
1183        <row>
1184         <entry><parameter>id</parameter></entry>
1185         <entry>UINT32</entry>
1186         <entry>The ID of the notification that was closed.</entry>
1187        </row>
1188        <row>
1189         <entry><parameter>reason</parameter></entry>
1190         <entry>UINT32</entry>
1191         <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>
1198         </entry>
1199        </row>
1200       </tbody>
1201      </tgroup>
1202     </table>
1203     <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.
1207     </para>
1208    </sect3>
1209
1210    <sect3 id="signal-action-invoked">
1211     <title><literal>org.freedesktop.Notifications.ActionInvoked</literal></title>
1212     <funcsynopsis>
1213      <funcprototype>
1214       <funcdef>
1215        <function>org.freedesktop.Notifications.ActionInvoked</function>
1216       </funcdef>
1217       <paramdef>UINT32 <parameter>id</parameter></paramdef>
1218       <paramdef>STRING <parameter>action_key</parameter></paramdef>
1219      </funcprototype>
1220     </funcsynopsis>
1221     <para>
1222      This signal is emitted when one of the following occurs:
1223     </para>
1224     <itemizedlist>
1225      <listitem>
1226       <para>
1227        The user performs some global "invoking" action upon a notification.
1228        For instance, clicking somewhere on the notification itself.
1229       </para>
1230      </listitem>
1231      <listitem>
1232       <para>
1233        The user invokes a specific action as specified in the original
1234        Notify request. For example, clicking on an action button.
1235       </para>
1236      </listitem>
1237     </itemizedlist>
1238     <table>
1239      <title>ActionInvoked Parameters</title>
1240      <tgroup cols="2">
1241       <thead>
1242        <row>
1243         <entry>Name</entry>
1244         <entry>Type</entry>
1245         <entry>Description</entry>
1246        </row>
1247       </thead>
1248       <tbody valign="top">
1249        <row>
1250         <entry><parameter>id</parameter></entry>
1251         <entry>UINT32</entry>
1252         <entry>
1253          The ID of the notification emitting the ActionInvoked signal.
1254         </entry>
1255        </row>
1256        <row>
1257         <entry><parameter>action_key</parameter></entry>
1258         <entry>STRING</entry>
1259         <entry>
1260          The key of the action invoked. These match the keys sent over
1261          in the list of actions.
1262         </entry>
1263        </row>
1264       </tbody>
1265      </tgroup>
1266     </table>
1267     <note>
1268      <para>
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.
1272      </para>
1273     </note>
1274    </sect3>
1275   </sect2>
1276  </sect1>
1277 </article>