docs: add api/dbus and docs/TODO.md
Signed-off-by: black-desk <me@black-desk.cn>
This commit is contained in:
black-desk
104
api/dbus/org.desktopspec.ApplicationManager1.Application.xml
Normal file
104
api/dbus/org.desktopspec.ApplicationManager1.Application.xml
Normal file
@ -0,0 +1,104 @@
|
||||
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
|
||||
<node>
|
||||
<interface name="org.desktopspec.ApplicationManager1.Application">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="This interface is designed to
|
||||
provide a dbus interface of desktop file.
|
||||
Missing fields will be added later."
|
||||
/>
|
||||
|
||||
<method name="Launch">
|
||||
<arg type="s" name="action" direction="in" />
|
||||
<arg type="as" name="fields" direction="in" />
|
||||
<arg type="o" name="job" direction="out" />
|
||||
|
||||
<arg type="a{sv}" name="options" direction="in"/>
|
||||
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="Given an action identifier,
|
||||
and some fields (file path or URI),
|
||||
this method will launch this application,
|
||||
and the object path of the job launching application.
|
||||
Result of that job is a object path
|
||||
of the new application instance.
|
||||
If that job failed, the result is a bool `false`.
|
||||
|
||||
Extra options can be passed in `options` argument:
|
||||
1. `uid` (type u):
|
||||
The user id as who is that application will be run.
|
||||
This option might request a polikit authentication."
|
||||
/>
|
||||
</method>
|
||||
|
||||
<property type="a{sa{ua{sh}}}" name="Icons" access="read">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="The type of this property is
|
||||
map[action(string)]map[size(uint)]map[format(string)]fd.
|
||||
|
||||
Format can be `png`, `svg`, `xpm`, `dci` or `icon`
|
||||
refering to the png/svg/xpm/dci format of icon files,
|
||||
as well as the `.icon` file contain the extra icon-data.
|
||||
|
||||
NOTE:
|
||||
1. `action` is an action identifier
|
||||
which is the id of
|
||||
additional applications actions key.
|
||||
When `action` is emtpy,
|
||||
this method return icon of the main desktop entry.
|
||||
Check https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html#extra-actions-identifier
|
||||
for futher infomation.
|
||||
2. `.icon` is a text file with some metadata.
|
||||
Check https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html#file_formats
|
||||
for futher infomation.
|
||||
3. Check https://github.com/linuxdeepin/deepin-specifications
|
||||
for futher infomation of dci icon format."
|
||||
/>
|
||||
</method>
|
||||
|
||||
<property name="Actions" type="as" access="read">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="Names of all action identifiers of this application.
|
||||
Check https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#extra-actions
|
||||
for futher information."
|
||||
/>
|
||||
</property>
|
||||
|
||||
<method name="GetActionName">
|
||||
<arg name="identifier" type="s" direction="in"/>
|
||||
<arg name="env" type="as" direction="in"/>
|
||||
<arg name="name" type="s" direction="out"/>
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="Given an action identifier
|
||||
and optional locale-releate environments,
|
||||
this method return the localized value of Name of
|
||||
that action.
|
||||
If env is not passed,
|
||||
this method will use the locale config of that user."
|
||||
/>
|
||||
</method>
|
||||
|
||||
|
||||
<property name="AutoStart" type="b" access="readwrite"/>
|
||||
|
||||
<property name="Instances" type="ao" access="read">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="All instances of this application."
|
||||
/>
|
||||
</property>
|
||||
|
||||
<property name="ID" type="s" access="read">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="The desktop file id of this application.
|
||||
Check https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#desktop-file-id
|
||||
for futher infomation."
|
||||
/>
|
||||
</property>
|
||||
</interface>
|
||||
</node>
|
||||
26
api/dbus/org.desktopspec.ApplicationManager1.Instance.xml
Normal file
26
api/dbus/org.desktopspec.ApplicationManager1.Instance.xml
Normal file
@ -0,0 +1,26 @@
|
||||
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
|
||||
<node>
|
||||
<interface name="org.desktopspec.ApplicationManager1.Instance">
|
||||
<property name="Application" type="o" access="read">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="Object path of the Application.
|
||||
That DBus object will impelement
|
||||
org.desktopspec.ApplicationManager1.Application."
|
||||
/>
|
||||
</property>
|
||||
|
||||
<property name="SystemdUnitPath" type="o" access="read">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="The systemd unit object path of this instance
|
||||
under systemd user daemon.
|
||||
Some other DE compoments can use this path to
|
||||
use the cgroup interface provided by systemd.
|
||||
NOTE:
|
||||
This property MIGHT be empty
|
||||
if this instance is not managed by systemd."
|
||||
/>
|
||||
</property>
|
||||
</interface>
|
||||
</node>
|
||||
49
api/dbus/org.desktopspec.ApplicationManager1.xml
Normal file
49
api/dbus/org.desktopspec.ApplicationManager1.xml
Normal file
@ -0,0 +1,49 @@
|
||||
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
|
||||
<node>
|
||||
<interface name="org.desktopspec.ApplicationManager1">
|
||||
<property type="ao" access="read" name="List" />
|
||||
|
||||
<method name="Application">
|
||||
<arg type="s" name="id" direction="in" />
|
||||
<arg type="o" name="application" direction="out" />
|
||||
</method>
|
||||
|
||||
<method name="Identify">
|
||||
<arg type="h" name="pidfd" direction="in" />
|
||||
|
||||
<arg type="s" name="id" direction="out" />
|
||||
<arg type="o" name="application" direction="out" />
|
||||
<arg type="o" name="application_instance" direction="out" />
|
||||
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="Given a pidfd,
|
||||
this method return a destkop file id,
|
||||
an application instance object path,
|
||||
as well as an application object path.
|
||||
|
||||
NOTE:
|
||||
1. You should use pidfd_open(2) to get a pidfd."
|
||||
/>
|
||||
</method>
|
||||
|
||||
<method name="Launch">
|
||||
<arg type="s" name="id" direction="in" />
|
||||
<arg type="s" name="action" direction="in" />
|
||||
<arg type="as" name="fields" direction="in" />
|
||||
<arg type="a{sv}" name="options" direction="in" />
|
||||
|
||||
<arg type="o" name="job" direction="out" />
|
||||
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="Given a desktop file id,
|
||||
this method will launch a desktop application.
|
||||
|
||||
Check description of the `Launch` method in
|
||||
`org.desktopspec.ApplicationManager1.Application`
|
||||
interface for futher infomation."
|
||||
/>
|
||||
</method>
|
||||
</interface>
|
||||
</node>
|
||||
46
api/dbus/org.desktopspec.JobManager1.Job.xml
Normal file
46
api/dbus/org.desktopspec.JobManager1.Job.xml
Normal file
@ -0,0 +1,46 @@
|
||||
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
|
||||
<node>
|
||||
<interface name="org.desktopspec.JobManager1.Job">
|
||||
<property name="Status" type="s" access="read">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="Value of `Status` is one of
|
||||
`pending`, `working`, `done`,
|
||||
`pasuing`, `paused`, `resuming`,
|
||||
`canceled` and `failed`."
|
||||
/>
|
||||
</property>
|
||||
|
||||
<method name="Cancel">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="Success call to this method will
|
||||
change the Status of this Job to `canceled`.
|
||||
Then after some time this method call return,
|
||||
this Job will be removed.
|
||||
Then the signal JobRemoved of org.desktopspec.JobManager1
|
||||
will be emitted."
|
||||
/>
|
||||
</method>
|
||||
<method name="Pause">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="Success call to this method will
|
||||
change the Status of this Job to `pausing`.
|
||||
Then after some time this method call return,
|
||||
Status will change to `paused`."
|
||||
/>
|
||||
</method>
|
||||
|
||||
<method name="Resume">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="Success call to this method will
|
||||
change the Status of this Job to `resuming`.
|
||||
Resuming Jobs will be queued along with pending Jobs.
|
||||
Then after some time this method call return,
|
||||
Status will change to `working`."
|
||||
/>
|
||||
</method>
|
||||
</interface>
|
||||
</node>
|
||||
46
api/dbus/org.desktopspec.JobManager1.xml
Normal file
46
api/dbus/org.desktopspec.JobManager1.xml
Normal file
@ -0,0 +1,46 @@
|
||||
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
|
||||
<node>
|
||||
<interface name="org.desktopspec.JobManager1">
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="All method might block will return a DBus object path,
|
||||
which implement org.desktopspec.JobManager1.Job.
|
||||
This interface is design to provide some DBus signals to help
|
||||
caller to watch the Jobs they invoked.
|
||||
Caller should not interst in all the Jobs, as there are some
|
||||
Jobs not created by them.
|
||||
So the method to list all exsiting Jobs is NOT provided.
|
||||
NOTE:
|
||||
Signal emitted by this interface MIGHT be peer-to-peer."
|
||||
/>
|
||||
|
||||
<signal name="JobNew">
|
||||
<arg type="o" name="job" />
|
||||
<arg type="o" name="source" />
|
||||
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="`source` is the DBus object produce this job."
|
||||
/>
|
||||
</signal>
|
||||
<signal name="JobRemoved">
|
||||
<arg type="o" name="job" />
|
||||
<arg type="s" name="status" />
|
||||
<arg type="s" name="message" />
|
||||
<arg type="v" name="result" />
|
||||
|
||||
<annotation
|
||||
name="org.freedesktop.DBus.Description"
|
||||
value="This signal report the job remove event.
|
||||
`status` is the `status` porperty of that Job
|
||||
when it got removed.
|
||||
`message` is the human readable message
|
||||
for caller to report to user or just simple logging.
|
||||
`result` is the result this job produce if it success.
|
||||
Method that return an object of Job
|
||||
should always have document
|
||||
about the type and meaning of the `result`."
|
||||
/>
|
||||
</signal>
|
||||
</interface>
|
||||
</node>
|
||||
Reference in New Issue
Block a user