Desktop Entry Daemon

Desktop Entry Daemon is a userspace DBus API and daemon to manage desktop entries. This could be expanded later to include a system-level component, but the current scope is just for userspace applications.

The current resources a client may register with desktop-entry-daemon:

Lifetimes

There are 3 lifetimes for a resource in desktop-entry-daemon:

  • Process - Resources in this lifetime will be cleared when the calling process exits
  • Session - Resources in this lifetime will be cleared when the session is restarted OR when the daemon restarts
  • Persistent - Resources in this lifetime are persistent across reboots and won't be deleted unless explicitly called to do so.

The default directories for these lifetimes are:

  • Process - /run/user/$UID/desktop-entry-daemon/process/
  • Session - /run/user/$UID/desktop-entry-daemon/session/
  • Persistent - $HOME/.cache/desktop-entry-daemon/

Using the DBus API

The up-to-date XML interface for the API can be found here.

The DBus interface can be found at the name io.ryanabx.DesktopEntry at the path /io/ryanabx/DesktopEntry.

Example 1 - Entry/Icon for the Process Lifetime

Let's say you are a client and you'd like to register a temporary desktop entry and icon for yourself while you're running. In this case, you'd want to use the Process lifetime, so that when your application exits, the entry is removed.

Call the DBus API function NewProcessEntry with a string for your application ID appid and the plain text of the desktop entry entry. The daemon will track the calling process until the process exits, and then delete the entry. You may also call the function NewProcessIcon to register an icon with the name name and the raw data for the icon data.

Example 2 - Registering an SVG Icon

Lets say you'd like to register a scalable icon for an app or other purpose. Let's say you'd like the icon to be cleared after the session exits, so you'd use the Session lifetime. Call NewSessionIcon with a name of your choice and some SVG text data encoded into UTF-8.

NOTE: Session-level and Persistent-level resources have an extra argument owner which is a string of your choice that identifies that you own the resource. You may use this string later on if you'd like to force-remove the data you've stored.

Contributing

This API is open and welcome to community contributions! Please make an issue describing what you'd like to work on, to avoid duplicate work, then make a PR!

Using the D-Bus API

This D-Bus API is for clients who would like to register a Freedesktop Desktop Entry temporarily.

In addition to registering a desktop entry, clients may also register an application icon which will be placed in the hicolor theme as specified by the Freedesktop Icons Specification

Usage

Register a Desktop Entry

The RegisterEntry method takes in a string appid corresponding to the application ID, and a string entry which is the plaintext desktop entry as it would appear in a .desktop file.

<!--
Register a new application entry. The utf-8 encoded `entry` will be validated to be conformant with the
[Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/)
Returns an error if the entry failed to register.
requires a valid process identifier to watch, entry goes away after the identified process exits
-->
<method name="RegisterEntry">
    <arg name="appid" type="s" direction="in"/>
    <arg name="entry" type="s" direction="in"/>
</method>

Register an Icon

The RegisterIcon method takes in a name which will be used when saving the icon, and when identifying the icon according to the Icon Spec. The data field takes a byte array corresponding to the image data.

It is preferred that the image data be .png or .svg data, and the daemon will do the job of figuring out the format when it receives the data.

<!--
Register a new application icon. The icon data should be valid .png or .svg data, and the icon type should be
0 for .png, 1 for .svg. The icon name is the name desktop entries reference when using the icon. The method will
returns true if successful, false otherwise.
-->
<method name="RegisterIcon">
    <arg name="name" type="s" direction="in">
    <arg name="data" type="ay" direction="in"/>
</method>

Watch for desktop entry and icon changes

If you are a client that would like to do something when a desktop entry or icon is added or destroyed, these signals are emitted when those are changed.

<!--
signal for when an entry is added or destroyed. subscribe to this if you would like to manually
handle refreshing the xdg desktop database, i.e. by using `update-desktop-database`
this is normally handled automatically by desktop-entry-daemon
-->
<signal name="EntryChanged">
    <arg name="appid" type="s"/>
</signal>
<!--
signal for when an icon is added or destroyed. subscribe to this if you would like to manually
handle refreshing the xdg desktop database, i.e. by using `update-desktop-database`
this is normally handled automatically by desktop-entry-daemon
-->
<signal name="IconChanged">
    <arg name="icon_name" type="s"/>
</signal>

Register a client as a change handler

This use case is still being developed on.

By default, desktop-entry-daemon will run desktop handling commands commands like update-desktop-database every time an icon or entry is added.

If you are a desktop environment and would like to handle changes to desktop entries and icons on your own, register a process as a change handler.

<!--
register the sender as a change handler for icons and entries. this inhibits the behavior
of desktop-entry-daemon refreshing the database whenever a new icon or entry is added or
removed. along with this, if you'd like to watch changes, subscribe to `icon_changed` and
`entry_changed`
-->
<method name="RegisterChangeHandler"></method>