Status Notifier specification

[Alberts Muktupāvels]

Hi!

I think that it is time to update this specification. Here is list with
changes that I propose.

1. Specification.
=================

1.1. Currently we have three components - Watcher, Host and Item. We should
rename specification from 'Status Notifier Item' to 'Status Notifier'.

1.2. Current implementations use org.kde.* for dbus names. While this
specification is not used by all desktop environments it is not used only
by kde either. We should start using org.freedesktop.* for dbus names.

1.3. We should start to use versioned dbus interface names.

2. Watcher.
===========

2.1. Make method, property and signal names shorter by removing
'StatusNotifier' part from names.

2.2. RegisterHost method, change arguments to:
- bus_name (s) - the bus name of Status Notifier Host or empty to use
sender;
- object_path (o) - the object path of Status Notifier Host.

2.3. RegisterItem method, change arguments to:
- bus_name (s) - the bus name of Status Notifier Item or empty to use
sender;
- object_path (o) - the object path of Status Notifier Item.

2.4. RegisteredItems property, change type from 'as' to 'a(so)' - bus name
and object path for each registered item.

2.5. ProtocolVersion property, remove it.

2.6. Rename 'StatusNotifierHostRegistered' signal to 'HostsChanged'. Should
be emitted when new host is registered or existing disappears.

2.7. ItemRegistered signal, change arguments to:
- bus_name (s) - the bus name of Status Notifier Item that was registered;
- object_path (o) - the object path of Status Notifier Item that was
registered;

2.8. ItemUnregistered signal, change arguments to:
- bus_name (s) - the bus name of Status Notifier Item that was unregistered;
- object_path (o) - the object path of Status Notifier Item that was
unregistered;

Watcher should use:
- org.freedesktop.StatusNotifier1.Watcher as bus name and interface name;
- /org/freedesktop/StatusNotifier1/Watcher as object path.

Improvements over existing interface:
- removed unused property;
- ability to create/register multiple items/hosts from one connection
(currently it is not possible because there can not be two objects with
same path);
- hosts and items are not required to create separate bus name.

Updated dbus interface is added as attachment.

3. Host.
========

Host should use:
- org.freedesktop.StatusNotifier1.Host as interface name.

Optionally (not required, but similar to current specification):
- org.freedesktop.StatusNotifier1.Host-{pid}-{id} as bus name where {pid}
is process id and {id} is unique identifier starting with 1 (was
'org.kde.StatusNotifierHost-{pid}');
- /org/freedesktop/StatusNotifier1/Host{id} as object path where {id} is
unique identifier starting with 1 (was '/StatusNotifierHost').

4. Item.
========

4.1. Drop all New* signals and use PropertiesChanged to get new/changed
data.

4.2. New property - IconThemePath (type=s). An additional path to add to
the theme search path to find the icons. It looks like this is used by
current implementations.

4.3. New property - ItemIsMenu (type=b). I have seen this in interface
files, does anyone knows if this is really used? If not then it should not
be included in updated spec.

4.4. New property - Menu (type=o). Object path to dbus menu
(com.canonical.dbusmenu interface). This is used at least by ubuntu.

Maybe type could be changed from o to s? So if there is no menu it could be
set to empty string instead of non-existent path?

4.5. Specification should mention which properties are required and which
ones are optional.

Item should use:
- org.freedesktop.StatusNotifier1.Item as interface name.

Optionally (not required, but similar to current specification):
- org.freedesktop.StatusNotifier1.Item-{pid}-{id} as bus name where {pid}
is process id and {id} is unique identifier starting with 1 (was
'org.kde.StatusNotifierItem-{pid}-{id}');
- /org/freedesktop/StatusNotifier1/Item{id} as object path where {id} is
unique identifier starting with 1 (was '/StatusNotifierItem').

Updated dbus interface is added as attachment.

-- 
Alberts Muktupāvels
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/plasma-devel/attachments/20151206/fb27dfbb/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: org.freedesktop.StatusNotifier1.Host.xml
Type: text/xml
Size: 272 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/plasma-devel/attachments/20151206/fb27dfbb/attachment-0003.xml>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: org.freedesktop.StatusNotifier1.Watcher.xml
Type: text/xml
Size: 1094 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/plasma-devel/attachments/20151206/fb27dfbb/attachment-0004.xml>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: org.freedesktop.StatusNotifier1.Item.xml
Type: text/xml
Size: 1837 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/plasma-devel/attachments/20151206/fb27dfbb/attachment-0005.xml>