jcarr
/
libnotify
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

- Fix some weird argument ordering in the calls to dbus_g_proxy_call_*(). 

- Re-order the arguments as per the spec.
- Change NOTIFY_TIMEOUT_* to NOTIFY_EXPIRES_*.
- Update the spec to 0.9.
This commit is contained in:
Christian Hammond 2006-01-20 10:00:32 +00:00
parent a834c839fc
commit 85342c8619
8 changed files with 207 additions and 195 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
ChangeLog
View File

@ -1,3 +1,18 @@
Fri Jan 20 01:59:26 PST 2006 Christian Hammond <chipx86@chipx86.com>
* docs/notification-spec.xml:
* libnotify/notification.c:
* libnotify/notification.h:
* tests/test-default-action.c:
* tests/test-image.c:
* tests/test-multi-actions.c:
* tools/notify-send.c:
- Fix some weird argument ordering in the calls to
dbus_g_proxy_call_*().
- Re-order the arguments as per the spec.
- Change NOTIFY_TIMEOUT_* to NOTIFY_EXPIRES_*.
- Update the spec to 0.9.
Fri Jan 20 01:37:42 PST 2006 Christian Hammond <chipx86@chipx86.com>
* libnotify/notification.c:

322
docs/notification-spec.xml
View File

@ -1,13 +1,10 @@
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS/DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<!DOCTYPE article PUBLIC "-//OASIS/DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article id="index">
<articleinfo>
<title>Desktop Notifications Specification</title>
<releaseinfo>Version 0.5</releaseinfo>
<date>2 October 2004</date>
<releaseinfo>Version 0.9</releaseinfo>
<date>15 January 2006</date>
<authorgroup>
<author>
<firstname>Mike</firstname>
@ -29,6 +26,34 @@
</author>
</authorgroup>
<revhistory>
<revision>
<revnumber>0.9</revnumber>
<date>15 January 2006</date>
<authorinitials>cdh</authorinitials>
<revremark>
Clarify the naming for the application IDs.
Put back a number of things that probably shouldn't have been removed
from the spec.
</revremark>
</revision>
<revision>
<revnumber>0.8</revnumber>
<date>23 September 2005</date>
<authorinitials>J5</authorinitials>
<revremark>
Major overhaul of spec to work with the newer D-Bus recursive type system.
Simplify protocol.
Changed the verbage notification type to category
</revremark>
</revision>
<revision>
<revnumber>0.7</revnumber>
<date>28 July 2005</date>
<authorinitials>cdh</authorinitials>
<revremark>
Added "x" and "y" hints. Talk about the variant type for hint values.
</revremark>
</revision>
<revision>
<revnumber>0.6</revnumber>
<date>1 April 2005</date>
@ -151,13 +176,6 @@
"fredapp-email-client."
</entry>
</row>
<row>
<entry>Application Icon</entry>
<entry>
The application icon. This is represented either as a path or a name
in an icon theme.
</entry>
</row>
<row>
<entry>Replaces ID</entry>
<entry>
@ -166,16 +184,11 @@
</entry>
</row>
<row>
<entry>Notification Type ID</entry>
<entry>Notification Icon</entry>
<entry>
An optional ID representing the notification type. See
<xref linkend="notification-types"/>.
</entry>
</row>
<row>
<entry>Urgency Level</entry>
<entry>
The urgency of the notification. See <xref linkend="urgency-levels"/>.
The notification icon. 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 (not a GTK+ stock ID).
</entry>
</row>
<row>
@ -204,10 +217,6 @@
</para>
</entry>
</row>
<row>
<entry>Images</entry>
<entry>See <xref linkend="icons"/>.</entry>
</row>
<row>
<entry>Actions</entry>
<entry>
@ -215,37 +224,60 @@
when invoked. This functionality may not be implemented by the
notification server, conforming clients should check if it is available
before using it (see the GetCapabilities message in
<xref linkend="protocol"/>. An implementation is free to ignore any
<xref linkend="protocol"/>). An implementation is free to ignore any
requested by the client. As an example one possible rendering of
actions would be as buttons in the notification popup.
Actions are sent over as a list of pairs. Each even element in the
list (starting at index 0) represents the identifier for the action.
Each odd element in the list is the localized string that will be
displayed to the user.
</entry>
</row>
<row>
<entry>Hints</entry>
<entry>See <xref linkend="hints"/>.</entry>
</row>
<row>
<entry>Expires</entry>
<entry>
<para>
A boolean flag indicating whether or not this notification should
automatically expire.
</para>
</entry>
<entry><para>See <xref linkend="hints"/>.</para></entry>
<para>
Beyond the core protocol is the hints table. A couple of core
elements have been moved to hints mostly because in a huge number
of cases their default values would be sufficent. The elements moved
to hints are:
</para>
<segmentedlist>
<seglistitem>
<seg>Category ID</seg>
<seg>An optional ID representing the type of notification (the name
has been changed from Notification Type ID in pervious versions).
See <xref linkend="categories"/>.</seg>
</seglistitem>
<seglistitem>
<seg>Urgency Level</seg>
<seg>The urgency of the notification. See
<xref linkend="urgency-levels"/>. (Defaults to 1 - Normal)</seg>
</seglistitem>
<seglistitem>
<seg>Icon Data</seg>
<seg>Instead of overloading the icon field we now have an icon_data
field that is used when icon is blank.</seg>
</seglistitem>
</segmentedlist>
</row>
<row>
<entry>Expiration Timeout</entry>
<entry>
<para>
The timeout time in seconds since the display of the notification at
which the notification should automatically close. This is ignored
if the expires flag is set to false.
The timeout time in milliseconds since the display of the notification
at which the notification should automatically close.
</para>
<para>
If zero, the notification's expiration time is dependent on the
If -1, the notification's expiration time is dependent on the
notification server's settings, and may vary for the type of
notification.
</para>
<para>
If 0, the notification never expires.
</para>
</entry>
</row>
</tbody>
@ -398,77 +430,27 @@
<sect1 id="icons" xreflabel="Icons">
<title>Icons</title>
<para>
A notification can optionally include an array of images for use as an
icon representing the notification. The array of images specifies frames
in an animation, which always loop. Implementations are free to ignore the
images data, and implementations that support images need not support
animation.
A notification can optionally have an icon specified by the Notification
Icon field or by the icon_data hint.
</para>
<para>
If the image array has more than one element, a "primary frame" can
be specified. If not specified, it defaults to the first frame. For
implementations that support images but not animation, only the primary
frame will be used.
The icon_data field should be a raw image data structure of signature
(iiibiiay) which describes the width, height, rowstride, has alpha, bits
per sample, channels and image data respectively.
</para>
<para>
Each element of the array must have the same type as the first
element. Mixtures of strings and blobs are not allowed. The element
types can be one of the following:
</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Element</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody valign="top">
<row>
<entry>Icon Theme Name</entry>
<entry>String</entry>
<entry>
Any string that does not begin with the <literal>/</literal>
character is assumed to be an icon theme name and is looked up
according to the spec. The best size to fit the servers chosen
presentation will be used. This is the recommended way of specifying
images.
</entry>
</row>
<row>
<entry>Absolute Path</entry>
<entry>String</entry>
<entry>
Any string that begins with a <literal>/</literal> will be used as
an absolute file path. Implementations should support at minimum
files of type image/png and image/svg.
</entry>
</row>
<row>
<entry>Image Data</entry>
<entry>Binary Data</entry>
<entry>
A data stream may be embedded in the message. This is assumed to be
of type image/png.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect1>
<sect1 id="notification-types" xreflabel="Notification Types">
<title>Notification Types</title>
<sect1 id="categories" xreflabel="Categories">
<title>Categories</title>
<para>
Notifications can optionally have a type indicator. Although neither
client or nor server must support this, some may choose to. Those servers
implementing notification types may use them to intelligently display
implementing categories may use them to intelligently display
the notification in a certain way, or group notifications of similar
types.
</para>
<para>
Notification types are in
Categories are in
<literal><replaceable>class.specific</replaceable></literal> form.
<literal>class</literal> specifies the generic type of notification, and
<literal>specific</literal> specifies the more specific type of
@ -480,14 +462,14 @@
<literal><replaceable>class</replaceable></literal> is acceptable.
</para>
<para>
Third parties, when defining their own notification types, should discuss
Third parties, when defining their own categories, should discuss
the possibility of standardizing on the hint with other parties, preferably
in a place such as the
<ulink url="http://freedesktop.org/mailman/listinfo/xdg">xdg</ulink>
mailing list at
<ulink url="http://freedesktop.org/">freedesktop.org</ulink>. If it
warrants a standard, it will be added to the table above. If no
consensus is reached, the notification type should be in the form of
consensus is reached, the category should be in the form of
"<literal>x-<replaceable>vendor</replaceable>.<replaceable>class</replaceable>.<replaceable>name</replaceable></literal>."
</para>
<para>
@ -495,7 +477,7 @@
More will be added in time.
</para>
<table>
<title>Notification Types</title>
<title>Categories</title>
<tgroup cols="2">
<thead>
<row>
@ -694,6 +676,13 @@
consensus is reached, the hint name should be in the form of
<literal>"x-<replaceable>vendor</replaceable>-<replaceable>name</replaceable>."</literal>
</para>
<para>
The value type for the hint dictionary in D-BUS is of the
<literal>DBUS_TYPE_VARIANT</literal> container type. This allows different
data types (string, integer, boolean, etc.) to be used for hints. When
adding a dictionary of hints, this type must be used, rather than putting
the actual hint value in as the dictionary value.
</para>
<para>
The following table lists the standard hints as defined by this
specification. Future hints may be proposed and added to this list
@ -710,6 +699,40 @@
</row>
</thead>
<tbody valign="top">
<row>
<entry><literal>"urgency"</literal></entry>
<entry>byte</entry>
<entry>
The urgency level.
</entry>
</row>
<row>
<entry><literal>"category"</literal></entry>
<entry>string</entry>
<entry>
The type of notification this is.
</entry>
</row>
<row>
<entry><literal>"desktop-entry"></literal></entry>b
<entry>Application Desktop ID</entry>
<entry>
This specifies the name of the desktop filename representing the
calling program. This should be the same as the prefix used for the
application's .desktop file. An example would be "rhythmbox" from
"rhythmbox.desktop". This can be used by the daemon to retrieve the
correct icon for the application, for logging purposes, etc.
</entry>
</row>
<row>
<entry><literal>"image_data"</literal></entry>
<entry>(iiibiiay)</entry>
<entry>
This is a raw data image format which describes the width, height,
rowstride, has alpha, bits per sample, channels and image data
respectively. We use this value if the icon field is left blank.
</entry>
</row>
<row>
<entry><literal>"sound-file"</literal></entry>
<entry>string</entry>
@ -726,6 +749,22 @@
play its own sound.
</entry>
</row>
<row>
<entry><literal>"x"</literal></entry>
<entry>int</entry>
<entry>
Specifies the X location on the screen that the notification should
point to. The <literal>"y"</literal> hint must also be specified.
</entry>
</row>
<row>
<entry><literal>"y"</literal></entry>
<entry>int</entry>
<entry>
Specifies the Y location on the screen that the notification should
point to. The <literal>"x"</literal> hint must also be specified.
</entry>
</row>
</tbody>
</tgroup>
</table>
@ -844,17 +883,13 @@
<function>org.freedesktop.Notifications.Notify</function>
</funcdef>
<paramdef>STRING <parameter>app_name</parameter></paramdef>
<paramdef>BYTE_ARRAY_OR_STRING <parameter>app_icon</parameter></paramdef>
<paramdef>UINT32 <parameter>replaces_id</parameter></paramdef>
<paramdef>STRING <parameter>notification_type</parameter></paramdef>
<paramdef>BYTE <parameter>urgency_level</parameter></paramdef>
<paramdef>STRING <parameter>app_icon</parameter></paramdef>
<paramdef>STRING <parameter>summary</parameter></paramdef>
<paramdef>STRING <parameter>body</parameter></paramdef>
<paramdef>ARRAY <parameter>images</parameter></paramdef>
<paramdef>DICT <parameter>actions</parameter></paramdef>
<paramdef>ARRAY <parameter>actions</parameter></paramdef>
<paramdef>DICT <parameter>hints</parameter></paramdef>
<paramdef>BOOL <parameter>expires</parameter></paramdef>
<paramdef>UINT32 <parameter>expire_timeout</parameter></paramdef>
<paramdef>INT32 <parameter>expire_timeout</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@ -879,15 +914,6 @@
Can be blank.
</entry>
</row>
<row>
<entry><parameter>app_icon</parameter></entry>
<entry>BYTE_ARRAY or STRING</entry>
<entry>
The optional program icon of the calling application. This is in
the same format as an image frame. See <xref linkend="icons"/>.
Can be an empty string, indicating no icon.
</entry>
</row>
<row>
<entry><parameter>replaces_id</parameter></entry>
<entry>UINT32</entry>
@ -901,19 +927,13 @@
</entry>
</row>
<row>
<entry><parameter>notification_type</parameter></entry>
<entry><parameter>app_icon</parameter></entry>
<entry>STRING</entry>
<entry>
The optional notification type ID, for potential server
categorization and logging purposes. See
<xref linkend="notification-types"/>. Can be empty.
The optional program icon of the calling application. See <xref linkend="icons"/>.
Can be an empty string, indicating no icon.
</entry>
</row>
<row>
<entry><parameter>urgency_level</parameter></entry>
<entry>BYTE</entry>
<entry>The urgency level. See <xref linkend="urgency-levels"/>.</entry>
</row>
<row>
<entry><parameter>summary</parameter></entry>
<entry>STRING</entry>
@ -925,22 +945,12 @@
<entry>The optional detailed body text. Can be empty.</entry>
</row>
<row>
<entry><parameter>images</parameter></entry>
<entry><parameter>actions</parameter></entry>
<entry>ARRAY</entry>
<entry>
The optional array of images. See <xref linkend="icons"/>. Can
be empty.
</entry>
</row>
<row>
<entry><parameter>actions</parameter></entry>
<entry>DICT</entry>
<entry>
A dictionary key of actions. Each key is the localized name of the
action, as it should appear to the user, and maps to a UINT32 value
containing a program-specific action code. This code will be reported
back to the program if the action is invoked by the user. Can be
empty.
Actions are sent over as a list of pairs. Each even element in the list
(starting at index 0) represents the identifier for the action. Each odd
element in the list is the localized string that will be displayed to the user.
</entry>
</row>
<row>
@ -955,27 +965,20 @@
empty.
</entry>
</row>
<row>
<entry><parameter>expires</parameter></entry>
<entry>BOOL</entry>
<entry>
A boolean flag indicating whether or not this notification should
automatically expire.
</entry>
</row>
<row>
<entry><parameter>expire_timeout</parameter></entry>
<entry>UINT32</entry>
<entry>INT32</entry>
<entry>
<para>
The timeout time in seconds since the display of the notification at
which the notification should automatically close. This is ignored
if the expires flag is set to false.
The timeout time in milliseconds since the display of the notification at
which the notification should automatically close.
</para>
<para>
If zero, the notification's expiration time is dependent on the
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, never expire.
</para>
</entry>
</row>
@ -1033,13 +1036,11 @@
<paramdef>out STRING <parameter>name</parameter></paramdef>
<paramdef>out STRING <parameter>vendor</parameter></paramdef>
<paramdef>out STRING <parameter>version</parameter></paramdef>
<paramdef>out STRING <parameter>spec_version</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This message returns the information on the server. Specifically,
the server name, vendor, version number, and specification version number
supported.
the server name, vendor, and version number.
</para>
<table>
<title>GetServerInformation Return Values</title>
@ -1070,11 +1071,6 @@
<entry>STRING</entry>
<entry>The server's version number.</entry>
</row>
<row>
<entry><parameter>spec_version</parameter></entry>
<entry>STRING</entry>
<entry>The supported specification version number.</entry>
</row>
</tbody>
</tgroup>
</table>

53
libnotify/notification.c
View File

@ -124,7 +124,7 @@ notify_notification_init(NotifyNotification *obj)
obj->priv->summary = NULL;
obj->priv->body = NULL;
obj->priv->icon_name = NULL;
obj->priv->timeout = NOTIFY_TIMEOUT_DEFAULT;
obj->priv->timeout = NOTIFY_EXPIRES_DEFAULT;
obj->priv->actions = NULL;
obj->priv->hints = g_hash_table_new_full(g_str_hash, g_str_equal,
g_free,
@ -431,34 +431,35 @@ _notify_notification_show_internal(NotifyNotification *notification,
if (ignore_reply)
{
dbus_g_proxy_call_no_reply(priv->proxy, "Notify",
G_TYPE_STRING, notify_get_app_name(),
G_TYPE_STRING,
(priv->icon_name !=
NULL) ? priv->icon_name : "",
G_TYPE_UINT, priv->id, G_TYPE_STRING,
priv->summary, G_TYPE_STRING,
priv->body, G_TYPE_STRV,
action_array,
dbus_g_type_get_map("GHashTable",
G_TYPE_STRING,
G_TYPE_VALUE),
priv->hints, G_TYPE_INT, priv->timeout,
G_TYPE_INVALID);
dbus_g_proxy_call_no_reply(
priv->proxy, "Notify",
G_TYPE_STRING, notify_get_app_name(),
G_TYPE_UINT, priv->id,
G_TYPE_STRING, priv->icon_name != NULL ? priv->icon_name : "",
G_TYPE_STRING, priv->summary,
G_TYPE_STRING, priv->body,
G_TYPE_STRV, action_array,
dbus_g_type_get_map("GHashTable", G_TYPE_STRING,
G_TYPE_VALUE), priv->hints,
G_TYPE_INT, priv->timeout,
G_TYPE_INVALID);
}
else
{
dbus_g_proxy_call(priv->proxy, "Notify", &tmp_error,
G_TYPE_STRING, notify_get_app_name(),
G_TYPE_STRING,
(priv->icon_name != NULL) ? priv->icon_name : "",
G_TYPE_UINT, priv->id, G_TYPE_STRING,
priv->summary, G_TYPE_STRING, priv->body,
G_TYPE_STRV, action_array,
dbus_g_type_get_map("GHashTable", G_TYPE_STRING,
G_TYPE_VALUE), priv->hints,
G_TYPE_INT, priv->timeout, G_TYPE_INVALID,
G_TYPE_UINT, &priv->id, G_TYPE_INVALID);
dbus_g_proxy_call(
priv->proxy, "Notify", &tmp_error,
G_TYPE_STRING, notify_get_app_name(),
G_TYPE_UINT, priv->id,
G_TYPE_STRING, priv->icon_name != NULL ? priv->icon_name : "",
G_TYPE_STRING, priv->summary,
G_TYPE_STRING, priv->body,
G_TYPE_STRV, action_array,
dbus_g_type_get_map("GHashTable", G_TYPE_STRING,
G_TYPE_VALUE), priv->hints,
G_TYPE_INT, priv->timeout,
G_TYPE_INVALID,
G_TYPE_UINT, &priv->id,
G_TYPE_INVALID);
}
/* Don't free the elements because they are owned by priv->actions */

4
libnotify/notification.h
View File

@ -28,8 +28,8 @@
G_BEGIN_DECLS
#define NOTIFY_TIMEOUT_DEFAULT -1
#define NOTIFY_TIMEOUT_NEVER 0
#define NOTIFY_EXPIRES_DEFAULT -1
#define NOTIFY_EXPIRES_NEVER 0
#define NOTIFY_TYPE_NOTIFICATION (notify_notification_get_type ())
#define NOTIFY_NOTIFICATION(o) \

2
tests/test-default-action.c
View File

@ -59,7 +59,7 @@ main()
dbus_connection_setup_with_g_main(conn, NULL);
n = notify_notification_new ("Matt is online", "", NULL, NULL);
notify_notification_set_timeout (n, NOTIFY_TIMEOUT_NEVER);
notify_notification_set_timeout (n, NOTIFY_EXPIRES_DEFAULT);
notify_notification_add_action (n, "default", "Do Default Action",
(NotifyActionCallback)callback);
notify_notification_set_category (n, "presence.online");

2
tests/test-image.c
View File

@ -61,7 +61,7 @@ main(int argc, char *argv[])
notify_notification_set_hint_int32(n, "x", 300);
notify_notification_set_hint_int32(n, "y", 24);
notify_notification_set_timeout(n, NOTIFY_TIMEOUT_NEVER);
notify_notification_set_timeout(n, NOTIFY_EXPIRES_DEFAULT);
helper = gtk_button_new();
icon = gtk_widget_render_icon(helper,
GTK_STOCK_DIALOG_QUESTION,

2
tests/test-multi-actions.c
View File

@ -92,7 +92,7 @@ main(int argc, char **argv)
"You can free up some disk space by "
"emptying the trash can.",
NULL, NULL);
notify_notification_set_timeout(n, NOTIFY_TIMEOUT_NEVER);
notify_notification_set_timeout(n, NOTIFY_EXPIRES_DEFAULT);
notify_notification_add_action(n, "help", "Help",
(NotifyActionCallback)help_callback);
notify_notification_add_action(n, "ignore", "Ignore",

2
tools/notify-send.c
View File

@ -38,7 +38,7 @@ main(int argc, const char **argv)
gchar *icon_str = NULL;
gchar *icons = NULL;
NotifyUrgency urgency = NOTIFY_URGENCY_NORMAL;
long expire_timeout = NOTIFY_TIMEOUT_DEFAULT;
long expire_timeout = NOTIFY_EXPIRES_DEFAULT;
char ch;
poptContext opt_ctx;
const char **args;