Changeset 2452
- Timestamp:
- 01/20/06 02:00:32
- Files:
-
- trunk/libnotify/ChangeLog (modified) (1 diff)
- trunk/libnotify/docs/notification-spec.xml (modified) (20 diffs)
- trunk/libnotify/libnotify/notification.c (modified) (2 diffs)
- trunk/libnotify/libnotify/notification.h (modified) (1 diff)
- trunk/libnotify/tests/test-default-action.c (modified) (1 diff)
- trunk/libnotify/tests/test-image.c (modified) (1 diff)
- trunk/libnotify/tests/test-multi-actions.c (modified) (1 diff)
- trunk/libnotify/tools/notify-send.c (modified) (1 diff)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
trunk/libnotify/ChangeLog
r2451 r2452 1 Fri Jan 20 01:59:26 PST 2006 Christian Hammond <chipx86@chipx86.com> 2 3 * docs/notification-spec.xml: 4 * libnotify/notification.c: 5 * libnotify/notification.h: 6 * tests/test-default-action.c: 7 * tests/test-image.c: 8 * tests/test-multi-actions.c: 9 * tools/notify-send.c: 10 - Fix some weird argument ordering in the calls to 11 dbus_g_proxy_call_*(). 12 - Re-order the arguments as per the spec. 13 - Change NOTIFY_TIMEOUT_* to NOTIFY_EXPIRES_*. 14 - Update the spec to 0.9. 15 1 16 Fri Jan 20 01:37:42 PST 2006 Christian Hammond <chipx86@chipx86.com> 2 17 trunk/libnotify/docs/notification-spec.xml
r2432 r2452 1 1 <?xml version="1.0"?> 2 3 <!DOCTYPE article PUBLIC "-//OASIS/DTD DocBook XML V4.1.2//EN" 4 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> 5 2 <!DOCTYPE article PUBLIC "-//OASIS/DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> 6 3 <article id="index"> 7 4 <articleinfo> 8 5 <title>Desktop Notifications Specification</title> 9 <releaseinfo>Version 0. 5</releaseinfo>10 <date> 2 October 2004</date>6 <releaseinfo>Version 0.9</releaseinfo> 7 <date>15 January 2006</date> 11 8 <authorgroup> 12 9 <author> … … 30 27 </authorgroup> 31 28 <revhistory> 29 <revision> 30 <revnumber>0.9</revnumber> 31 <date>15 January 2006</date> 32 <authorinitials>cdh</authorinitials> 33 <revremark> 34 Clarify the naming for the application IDs. 35 Put back a number of things that probably shouldn't have been removed 36 from the spec. 37 </revremark> 38 </revision> 39 <revision> 40 <revnumber>0.8</revnumber> 41 <date>23 September 2005</date> 42 <authorinitials>J5</authorinitials> 43 <revremark> 44 Major overhaul of spec to work with the newer D-Bus recursive type system. 45 Simplify protocol. 46 Changed the verbage notification type to category 47 </revremark> 48 </revision> 49 <revision> 50 <revnumber>0.7</revnumber> 51 <date>28 July 2005</date> 52 <authorinitials>cdh</authorinitials> 53 <revremark> 54 Added "x" and "y" hints. Talk about the variant type for hint values. 55 </revremark> 56 </revision> 32 57 <revision> 33 58 <revnumber>0.6</revnumber> … … 153 178 </row> 154 179 <row> 155 <entry>Application Icon</entry>156 <entry>157 The application icon. This is represented either as a path or a name158 in an icon theme.159 </entry>160 </row>161 <row>162 180 <entry>Replaces ID</entry> 163 181 <entry> … … 167 185 </row> 168 186 <row> 169 <entry>Notification Type ID</entry> 170 <entry> 171 An optional ID representing the notification type. See 172 <xref linkend="notification-types"/>. 173 </entry> 174 </row> 175 <row> 176 <entry>Urgency Level</entry> 177 <entry> 178 The urgency of the notification. See <xref linkend="urgency-levels"/>. 187 <entry>Notification Icon</entry> 188 <entry> 189 The notification icon. This is represented either as a URI 190 (file:// is the only URI schema supported right now) or a name in 191 a freedesktop.org-compliant icon theme (not a GTK+ stock ID). 179 192 </entry> 180 193 </row> … … 206 219 </row> 207 220 <row> 208 <entry>Images</entry>209 <entry>See <xref linkend="icons"/>.</entry>210 </row>211 <row>212 221 <entry>Actions</entry> 213 222 <entry> … … 216 225 notification server, conforming clients should check if it is available 217 226 before using it (see the GetCapabilities message in 218 <xref linkend="protocol"/> . An implementation is free to ignore any227 <xref linkend="protocol"/>). An implementation is free to ignore any 219 228 requested by the client. As an example one possible rendering of 220 229 actions would be as buttons in the notification popup. 230 231 Actions are sent over as a list of pairs. Each even element in the 232 list (starting at index 0) represents the identifier for the action. 233 Each odd element in the list is the localized string that will be 234 displayed to the user. 221 235 </entry> 222 236 </row> 223 237 <row> 224 238 <entry>Hints</entry> 225 <entry>See <xref linkend="hints"/>.</entry> 226 </row> 227 <row> 228 <entry>Expires</entry> 239 <entry><para>See <xref linkend="hints"/>.</para></entry> 240 241 <para> 242 Beyond the core protocol is the hints table. A couple of core 243 elements have been moved to hints mostly because in a huge number 244 of cases their default values would be sufficent. The elements moved 245 to hints are: 246 </para> 247 <segmentedlist> 248 <seglistitem> 249 <seg>Category ID</seg> 250 <seg>An optional ID representing the type of notification (the name 251 has been changed from Notification Type ID in pervious versions). 252 See <xref linkend="categories"/>.</seg> 253 </seglistitem> 254 <seglistitem> 255 <seg>Urgency Level</seg> 256 <seg>The urgency of the notification. See 257 <xref linkend="urgency-levels"/>. (Defaults to 1 - Normal)</seg> 258 </seglistitem> 259 <seglistitem> 260 <seg>Icon Data</seg> 261 <seg>Instead of overloading the icon field we now have an icon_data 262 field that is used when icon is blank.</seg> 263 </seglistitem> 264 </segmentedlist> 265 </row> 266 <row> 267 <entry>Expiration Timeout</entry> 229 268 <entry> 230 269 <para> 231 A boolean flag indicating whether or not this notification should 232 automatically expire. 233 </para> 234 </entry> 235 </row> 236 <row> 237 <entry>Expiration Timeout</entry> 238 <entry> 239 <para> 240 The timeout time in seconds since the display of the notification at 241 which the notification should automatically close. This is ignored 242 if the expires flag is set to false. 270 The timeout time in milliseconds since the display of the notification 271 at which the notification should automatically close. 243 272 </para> 244 273 <para> 245 If zero, the notification's expiration time is dependent on the274 If -1, the notification's expiration time is dependent on the 246 275 notification server's settings, and may vary for the type of 247 276 notification. 277 </para> 278 <para> 279 If 0, the notification never expires. 248 280 </para> 249 281 </entry> … … 399 431 <title>Icons</title> 400 432 <para> 401 A notification can optionally include an array of images for use as an 402 icon representing the notification. The array of images specifies frames 403 in an animation, which always loop. Implementations are free to ignore the 404 images data, and implementations that support images need not support 405 animation. 406 </para> 407 <para> 408 If the image array has more than one element, a "primary frame" can 409 be specified. If not specified, it defaults to the first frame. For 410 implementations that support images but not animation, only the primary 411 frame will be used. 412 </para> 413 <para> 414 Each element of the array must have the same type as the first 415 element. Mixtures of strings and blobs are not allowed. The element 416 types can be one of the following: 417 </para> 418 <informaltable> 419 <tgroup cols="3"> 420 <thead> 421 <row> 422 <entry>Element</entry> 423 <entry>Type</entry> 424 <entry>Description</entry> 425 </row> 426 </thead> 427 <tbody valign="top"> 428 <row> 429 <entry>Icon Theme Name</entry> 430 <entry>String</entry> 431 <entry> 432 Any string that does not begin with the <literal>/</literal> 433 character is assumed to be an icon theme name and is looked up 434 according to the spec. The best size to fit the servers chosen 435 presentation will be used. This is the recommended way of specifying 436 images. 437 </entry> 438 </row> 439 <row> 440 <entry>Absolute Path</entry> 441 <entry>String</entry> 442 <entry> 443 Any string that begins with a <literal>/</literal> will be used as 444 an absolute file path. Implementations should support at minimum 445 files of type image/png and image/svg. 446 </entry> 447 </row> 448 <row> 449 <entry>Image Data</entry> 450 <entry>Binary Data</entry> 451 <entry> 452 A data stream may be embedded in the message. This is assumed to be 453 of type image/png. 454 </entry> 455 </row> 456 </tbody> 457 </tgroup> 458 </informaltable> 433 A notification can optionally have an icon specified by the Notification 434 Icon field or by the icon_data hint. 435 </para> 436 <para> 437 The icon_data field should be a raw image data structure of signature 438 (iiibiiay) which describes the width, height, rowstride, has alpha, bits 439 per sample, channels and image data respectively. 440 </para> 459 441 </sect1> 460 442 461 <sect1 id=" notification-types" xreflabel="Notification Types">462 <title> Notification Types</title>443 <sect1 id="categories" xreflabel="Categories"> 444 <title>Categories</title> 463 445 <para> 464 446 Notifications can optionally have a type indicator. Although neither 465 447 client or nor server must support this, some may choose to. Those servers 466 implementing notification types may use them to intelligently display448 implementing categories may use them to intelligently display 467 449 the notification in a certain way, or group notifications of similar 468 450 types. 469 451 </para> 470 452 <para> 471 Notification types are in453 Categories are in 472 454 <literal><replaceable>class.specific</replaceable></literal> form. 473 455 <literal>class</literal> specifies the generic type of notification, and … … 481 463 </para> 482 464 <para> 483 Third parties, when defining their own notification types, should discuss465 Third parties, when defining their own categories, should discuss 484 466 the possibility of standardizing on the hint with other parties, preferably 485 467 in a place such as the … … 488 470 <ulink url="http://freedesktop.org/">freedesktop.org</ulink>. If it 489 471 warrants a standard, it will be added to the table above. If no 490 consensus is reached, the notification typeshould be in the form of472 consensus is reached, the category should be in the form of 491 473 "<literal>x-<replaceable>vendor</replaceable>.<replaceable>class</replaceable>.<replaceable>name</replaceable></literal>." 492 474 </para> … … 496 478 </para> 497 479 <table> 498 <title> Notification Types</title>480 <title>Categories</title> 499 481 <tgroup cols="2"> 500 482 <thead> … … 696 678 </para> 697 679 <para> 680 The value type for the hint dictionary in D-BUS is of the 681 <literal>DBUS_TYPE_VARIANT</literal> container type. This allows different 682 data types (string, integer, boolean, etc.) to be used for hints. When 683 adding a dictionary of hints, this type must be used, rather than putting 684 the actual hint value in as the dictionary value. 685 </para> 686 <para> 698 687 The following table lists the standard hints as defined by this 699 688 specification. Future hints may be proposed and added to this list … … 712 701 <tbody valign="top"> 713 702 <row> 703 <entry><literal>"urgency"</literal></entry> 704 <entry>byte</entry> 705 <entry> 706 The urgency level. 707 </entry> 708 </row> 709 <row> 710 <entry><literal>"category"</literal></entry> 711 <entry>string</entry> 712 <entry> 713 The type of notification this is. 714 </entry> 715 </row> 716 <row> 717 <entry><literal>"desktop-entry"></literal></entry>b 718 <entry>Application Desktop ID</entry> 719 <entry> 720 This specifies the name of the desktop filename representing the 721 calling program. This should be the same as the prefix used for the 722 application's .desktop file. An example would be "rhythmbox" from 723 "rhythmbox.desktop". This can be used by the daemon to retrieve the 724 correct icon for the application, for logging purposes, etc. 725 </entry> 726 </row> 727 <row> 728 <entry><literal>"image_data"</literal></entry> 729 <entry>(iiibiiay)</entry> 730 <entry> 731 This is a raw data image format which describes the width, height, 732 rowstride, has alpha, bits per sample, channels and image data 733 respectively. We use this value if the icon field is left blank. 734 </entry> 735 </row> 736 <row> 714 737 <entry><literal>"sound-file"</literal></entry> 715 738 <entry>string</entry> … … 725 748 ability. This is usually set when the client itself is going to 726 749 play its own sound. 750 </entry> 751 </row> 752 <row> 753 <entry><literal>"x"</literal></entry> 754 <entry>int</entry> 755 <entry> 756 Specifies the X location on the screen that the notification should 757 point to. The <literal>"y"</literal> hint must also be specified. 758 </entry> 759 </row> 760 <row> 761 <entry><literal>"y"</literal></entry> 762 <entry>int</entry> 763 <entry> 764 Specifies the Y location on the screen that the notification should 765 point to. The <literal>"x"</literal> hint must also be specified. 727 766 </entry> 728 767 </row> … … 845 884 </funcdef> 846 885 <paramdef>STRING <parameter>app_name</parameter></paramdef> 847 <paramdef>BYTE_ARRAY_OR_STRING <parameter>app_icon</parameter></paramdef>848 886 <paramdef>UINT32 <parameter>replaces_id</parameter></paramdef> 849 <paramdef>STRING <parameter>notification_type</parameter></paramdef> 850 <paramdef>BYTE <parameter>urgency_level</parameter></paramdef> 887 <paramdef>STRING <parameter>app_icon</parameter></paramdef> 851 888 <paramdef>STRING <parameter>summary</parameter></paramdef> 852 889 <paramdef>STRING <parameter>body</parameter></paramdef> 853 <paramdef>ARRAY <parameter>images</parameter></paramdef> 854 <paramdef>DICT <parameter>actions</parameter></paramdef> 890 <paramdef>ARRAY <parameter>actions</parameter></paramdef> 855 891 <paramdef>DICT <parameter>hints</parameter></paramdef> 856 <paramdef>BOOL <parameter>expires</parameter></paramdef> 857 <paramdef>UINT32 <parameter>expire_timeout</parameter></paramdef> 892 <paramdef>INT32 <parameter>expire_timeout</parameter></paramdef> 858 893 </funcprototype> 859 894 </funcsynopsis> … … 878 913 The optional name of the application sending the notification. 879 914 Can be blank. 880 </entry>881 </row>882 <row>883 <entry><parameter>app_icon</parameter></entry>884 <entry>BYTE_ARRAY or STRING</entry>885 <entry>886 The optional program icon of the calling application. This is in887 the same format as an image frame. See <xref linkend="icons"/>.888 Can be an empty string, indicating no icon.889 915 </entry> 890 916 </row> … … 902 928 </row> 903 929 <row> 904 <entry><parameter> notification_type</parameter></entry>930 <entry><parameter>app_icon</parameter></entry> 905 931 <entry>STRING</entry> 906 932 <entry> 907 The optional notification type ID, for potential server 908 categorization and logging purposes. See 909 <xref linkend="notification-types"/>. Can be empty. 910 </entry> 911 </row> 912 <row> 913 <entry><parameter>urgency_level</parameter></entry> 914 <entry>BYTE</entry> 915 <entry>The urgency level. See <xref linkend="urgency-levels"/>.</entry> 933 The optional program icon of the calling application. See <xref linkend="icons"/>. 934 Can be an empty string, indicating no icon. 935 </entry> 916 936 </row> 917 937 <row> … … 926 946 </row> 927 947 <row> 928 <entry><parameter> images</parameter></entry>948 <entry><parameter>actions</parameter></entry> 929 949 <entry>ARRAY</entry> 930 950 <entry> 931 The optional array of images. See <xref linkend="icons"/>. Can 932 be empty. 933 </entry> 934 </row> 935 <row> 936 <entry><parameter>actions</parameter></entry> 937 <entry>DICT</entry> 938 <entry> 939 A dictionary key of actions. Each key is the localized name of the 940 action, as it should appear to the user, and maps to a UINT32 value 941 containing a program-specific action code. This code will be reported 942 back to the program if the action is invoked by the user. Can be 943 empty. 951 Actions are sent over as a list of pairs. Each even element in the list 952 (starting at index 0) represents the identifier for the action. Each odd 953 element in the list is the localized string that will be displayed to the user. 944 954 </entry> 945 955 </row> … … 957 967 </row> 958 968 <row> 959 <entry><parameter>expires</parameter></entry>960 <entry>BOOL</entry>961 <entry>962 A boolean flag indicating whether or not this notification should963 automatically expire.964 </entry>965 </row>966 <row>967 969 <entry><parameter>expire_timeout</parameter></entry> 968 <entry> UINT32</entry>970 <entry>INT32</entry> 969 971 <entry> 970 972 <para> 971 The timeout time in seconds since the display of the notification at 972 which the notification should automatically close. This is ignored 973 if the expires flag is set to false. 973 The timeout time in milliseconds since the display of the notification at 974 which the notification should automatically close. 974 975 </para> 975 976 <para> 976 If zero, the notification's expiration time is dependent on the977 If -1, the notification's expiration time is dependent on the 977 978 notification server's settings, and may vary for the type of 978 979 notification. 980 981 If 0, never expire. 979 982 </para> 980 983 </entry> … … 1034 1037 <paramdef>out STRING <parameter>vendor</parameter></paramdef> 1035 1038 <paramdef>out STRING <parameter>version</parameter></paramdef> 1036 <paramdef>out STRING <parameter>spec_version</parameter></paramdef>1037 1039 </funcprototype> 1038 1040 </funcsynopsis> 1039 1041 <para> 1040 1042 This message returns the information on the server. Specifically, 1041 the server name, vendor, version number, and specification version number 1042 supported. 1043 the server name, vendor, and version number. 1043 1044 </para> 1044 1045 <table> … … 1070 1071 <entry>STRING</entry> 1071 1072 <entry>The server's version number.</entry> 1072 </row>1073 <row>1074 <entry><parameter>spec_version</parameter></entry>1075 <entry>STRING</entry>1076 <entry>The supported specification version number.</entry>1077 1073 </row> 1078 1074 </tbody> trunk/libnotify/libnotify/notification.c
r2451 r2452 125 125 obj->priv->body = NULL; 126 126 obj->priv->icon_name = NULL; 127 obj->priv->timeout = NOTIFY_ TIMEOUT_DEFAULT;127 obj->priv->timeout = NOTIFY_EXPIRES_DEFAULT; 128 128 obj->priv->actions = NULL; 129 129 obj->priv->hints = g_hash_table_new_full(g_str_hash, g_str_equal, … … 432 432 if (ignore_reply) 433 433 { 434 dbus_g_proxy_call_no_reply(priv->proxy, "Notify", 435 G_TYPE_STRING, notify_get_app_name(), 436 G_TYPE_STRING, 437 (priv->icon_name != 438 NULL) ? priv->icon_name : "", 439 G_TYPE_UINT, priv->id, G_TYPE_STRING, 440 priv->summary, G_TYPE_STRING, 441 priv->body, G_TYPE_STRV, 442 action_array, 443 dbus_g_type_get_map("GHashTable", 444 G_TYPE_STRING, 445 G_TYPE_VALUE), 446 priv->hints, G_TYPE_INT, priv->timeout, 447 G_TYPE_INVALID); 434 dbus_g_proxy_call_no_reply( 435 priv->proxy, "Notify", 436 G_TYPE_STRING, notify_get_app_name(), 437 G_TYPE_UINT, priv->id, 438 G_TYPE_STRING, priv->icon_name != NULL ? priv->icon_name : "", 439 G_TYPE_STRING, priv->summary, 440 G_TYPE_STRING, priv->body, 441 G_TYPE_STRV, action_array, 442 dbus_g_type_get_map("GHashTable", G_TYPE_STRING, 443 G_TYPE_VALUE), priv->hints, 444 G_TYPE_INT, priv->timeout, 445 G_TYPE_INVALID); 448 446 } 449 447 else 450 448 { 451 dbus_g_proxy_call(priv->proxy, "Notify", &tmp_error, 452 G_TYPE_STRING, notify_get_app_name(), 453 G_TYPE_STRING, 454 (priv->icon_name != NULL) ? priv->icon_name : "", 455 G_TYPE_UINT, priv->id, G_TYPE_STRING, 456 priv->summary, G_TYPE_STRING, priv->body, 457 G_TYPE_STRV, action_array, 458 dbus_g_type_get_map("GHashTable", G_TYPE_STRING, 459 G_TYPE_VALUE), priv->hints, 460 G_TYPE_INT, priv->timeout, G_TYPE_INVALID, 461 G_TYPE_UINT, &priv->id, G_TYPE_INVALID); 449 dbus_g_proxy_call( 450 priv->proxy, "Notify", &tmp_error, 451 G_TYPE_STRING, notify_get_app_name(), 452 G_TYPE_UINT, priv->id, 453 G_TYPE_STRING, priv->icon_name != NULL ? priv->icon_name : "", 454 G_TYPE_STRING, priv->summary, 455 G_TYPE_STRING, priv->body, 456 G_TYPE_STRV, action_array, 457 dbus_g_type_get_map("GHashTable", G_TYPE_STRING, 458 G_TYPE_VALUE), priv->hints, 459 G_TYPE_INT, priv->timeout, 460 G_TYPE_INVALID, 461 G_TYPE_UINT, &priv->id, 462 G_TYPE_INVALID); 462 463 } 463 464 trunk/libnotify/libnotify/notification.h
r2451 r2452 29 29 G_BEGIN_DECLS 30 30 31 #define NOTIFY_ TIMEOUT_DEFAULT -132 #define NOTIFY_ TIMEOUT_NEVER 031 #define NOTIFY_EXPIRES_DEFAULT -1 32 #define NOTIFY_EXPIRES_NEVER 0 33 33 34 34 #define NOTIFY_TYPE_NOTIFICATION (notify_notification_get_type ()) trunk/libnotify/tests/test-default-action.c
r2408 r2452 60 60 61 61 n = notify_notification_new ("Matt is online", "", NULL, NULL); 62 notify_notification_set_timeout (n, NOTIFY_ TIMEOUT_NEVER);62 notify_notification_set_timeout (n, NOTIFY_EXPIRES_DEFAULT); 63 63 notify_notification_add_action (n, "default", "Do Default Action", 64 64 (NotifyActionCallback)callback); trunk/libnotify/tests/test-image.c
r2441 r2452 62 62 notify_notification_set_hint_int32(n, "x", 300); 63 63 notify_notification_set_hint_int32(n, "y", 24); 64 notify_notification_set_timeout(n, NOTIFY_ TIMEOUT_NEVER);64 notify_notification_set_timeout(n, NOTIFY_EXPIRES_DEFAULT); 65 65 helper = gtk_button_new(); 66 66 icon = gtk_widget_render_icon(helper, trunk/libnotify/tests/test-multi-actions.c
r2391 r2452 93 93 "emptying the trash can.", 94 94 NULL, NULL); 95 notify_notification_set_timeout(n, NOTIFY_ TIMEOUT_NEVER);95 notify_notification_set_timeout(n, NOTIFY_EXPIRES_DEFAULT); 96 96 notify_notification_add_action(n, "help", "Help", 97 97 (NotifyActionCallback)help_callback); trunk/libnotify/tools/notify-send.c
r2434 r2452 39 39 gchar *icons = NULL; 40 40 NotifyUrgency urgency = NOTIFY_URGENCY_NORMAL; 41 long expire_timeout = NOTIFY_ TIMEOUT_DEFAULT;41 long expire_timeout = NOTIFY_EXPIRES_DEFAULT; 42 42 char ch; 43 43 poptContext opt_ctx;
