docs: add api/dbus and docs/TODO.md
Signed-off-by: black-desk <me@black-desk.cn>
This commit is contained in:
black-desk
parent
0316297d8a
commit
d05e3fee70
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>
|
||||||
103
docs/TODO.md
Normal file
103
docs/TODO.md
Normal file
@ -0,0 +1,103 @@
|
|||||||
|
# AM重构计划
|
||||||
|
|
||||||
|
目前对AM应该有怎么样的特性、以及其负责的边界，
|
||||||
|
已经在[AM-ICU房间][1]中经过了详细的讨论。
|
||||||
|
已经到了可以着手进行初步的设计和评审工作的阶段。
|
||||||
|
|
||||||
|
[1]: https://matrix.to/#/!WBkiaAZKeeKzerJEZQ:deepin.org?via=deepin.org&via=matrix.org&via=mozilla.org
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
|
||||||
|
由于目前老AM项目中尚有dock和launcher项目的逻辑，
|
||||||
|
所以在重构时，
|
||||||
|
需要同步地将dock和launcher中属于后台服务部分的逻辑写回对应项目中去。
|
||||||
|
该部分工作会与AM的重构工作同步进行，由负责dock和launcher的研发人员完成。
|
||||||
|
这两个任务与AM的重构工作不应该产生强的依赖关系。
|
||||||
|
|
||||||
|
基于以上背景，老的AM并不会直接被移除，我们将新建一个项目完成新AM的编写。
|
||||||
|
完成其主要功能以后再将老AM中的启动应用功能移除，
|
||||||
|
并将dock和launcher中启动应用的部分逻辑切换到新AM提供的DBus接口。
|
||||||
|
|
||||||
|
老AM中launcher和dock的后端逻辑不会进行任何更改，
|
||||||
|
直到等待launcher和dock已经不再依赖老AM后，
|
||||||
|
彻底将旧AM从系统中移除。
|
||||||
|
|
||||||
|
## AM的主要功能
|
||||||
|
|
||||||
|
1. DDE的desktop文件管理器。
|
||||||
|
|
||||||
|
所有需要获取Desktop文件的进程，都应该通过AM来进行这个操作。
|
||||||
|
AM会提供两套接口完成对desktop文件的访问以及管理：
|
||||||
|
|
||||||
|
1. DBus
|
||||||
|
2. fuse 用于完全实现XDG兼容。\[暂不实现\]
|
||||||
|
|
||||||
|
这两套接口都需要考虑接口的调用者是从容器中访问的情况。
|
||||||
|
|
||||||
|
2. DDE的应用执行者。
|
||||||
|
|
||||||
|
需要提供DBus接口并更新dde-open。
|
||||||
|
|
||||||
|
## 工作记录
|
||||||
|
|
||||||
|
由参与AM重构计划的研发人员完成的主要的工作有以下几方面，
|
||||||
|
可以拆分为几个阶段来完成：
|
||||||
|
|
||||||
|
- 准备
|
||||||
|
- [x] 完成AM的DBus API设计文档（@black-desk）；
|
||||||
|
|
||||||
|
本次AM共计需要完成5个DBus接口:
|
||||||
|
|
||||||
|
1. [`org.desktopspec.ApplicationManager1`](../api/dbus/org.desktopspec.ApplicationManager1.xml)
|
||||||
|
2. [`org.desktopspec.ApplicationManager1.Application`](../api/dbus/org.desktopspec.ApplicationManager1.Application.xml)
|
||||||
|
3. [`org.desktopspec.ApplicationManager1.Instance`](../api/dbus/org.desktopspec.ApplicationManager1.Instance.xml)
|
||||||
|
4. [`org.desktopspec.JobManager1`](../api/dbus/org.desktopspec.JobManager1.xml)
|
||||||
|
5. [`org.desktopspec.JobManager1.Job`](../api/dbus/org.desktopspec.JobManager1.Job.xml)
|
||||||
|
|
||||||
|
- [ ] 以上接口设计需要通过评审。
|
||||||
|
|
||||||
|
- [ ] 完成AM的主要项目结构搭建；
|
||||||
|
|
||||||
|
框架完成后需要通过评审。
|
||||||
|
|
||||||
|
- [ ] 主要功能开发
|
||||||
|
- [ ] 应用列表；
|
||||||
|
- [ ] 启动应用；
|
||||||
|
- [ ] 从PID获取AppID；
|
||||||
|
- [ ] 正在运行的应用列表；
|
||||||
|
- [ ] 崩溃后恢复现场；
|
||||||
|
|
||||||
|
- [ ] launcher/dock迁移
|
||||||
|
|
||||||
|
更改launcher和dock中启动应用部分的代码，使用新dock来实现。
|
||||||
|
并删除老AM中启动应用相关的代码。
|
||||||
|
|
||||||
|
- [ ] 测试工作
|
||||||
|
|
||||||
|
进行
|
||||||
|
|
||||||
|
- [ ] dock
|
||||||
|
- [ ] launcher
|
||||||
|
- [ ] dde-open/xdg-open
|
||||||
|
- [ ] 文件管理器
|
||||||
|
- [ ] 浏览器
|
||||||
|
|
||||||
|
等桌面组件的基础功能测试，bug修复。
|
||||||
|
|
||||||
|
- [ ] hook功能开发
|
||||||
|
|
||||||
|
该功能的开发主要是为了防止应用从配置好的cgroup中逃逸。
|
||||||
|
|
||||||
|
1. 完成App运行前hook插件体系的实现；
|
||||||
|
2. 重要插件实现：
|
||||||
|
- [ ] cgroup锁定插件的实现；(@black-desk)
|
||||||
|
|
||||||
|
<https://github.com/black-desk/djail>
|
||||||
|
|
||||||
|
- [ ] dbus代理插件；(@black-desk)
|
||||||
|
|
||||||
|
使用flatpak提供的xdg-dbus-proxy实现一个不可交互的dbus代理，
|
||||||
|
目前主要用于屏蔽systemd用户实例提供的cgroup移动功能。
|
||||||
|
|
||||||
|
使用一个具有特权的二进制创建新的mount namepsace，
|
||||||
|
通过挂载将proxy提供的socket bind到对应位置。
|
||||||
Loading…
Reference in New Issue
Block a user