开源应用程序架构（卷 1）
Telepathy

20.2.1. 句柄

句柄在 Telepathy 中用于表示标识符（例如，联系人姓名和房间名称）。它们是由连接管理器分配的无符号整数值，使得元组（连接、句柄类型、句柄）唯一地引用给定的联系人或房间。

由于不同的通信协议以不同的方式规范化标识符（例如，大小写敏感性、资源），因此句柄为客户端提供了一种方法来确定两个标识符是否相同。它们可以请求两个不同标识符的句柄，如果句柄号码匹配，那么这些标识符引用相同的联系人或房间。

每个协议的标识符规范化规则都不同，因此客户端比较标识符字符串来比较标识符是一个错误。例如，escher@tuxedo.cat/bed 和 escher@tuxedo.cat/litterbox 是 XMPP 协议中同一个联系人 (escher@tuxedo.cat) 的两个实例，因此具有相同的句柄。客户端可以按标识符或句柄请求通道，但他们应该只使用句柄进行比较。

20.2.2. 发现 Telepathy 服务

某些服务（例如，帐户管理器和通道调度程序）始终存在，具有在 Telepathy 规范中定义的知名名称。但是，连接管理器和客户端的名称并不为人所知，必须发现它们。

Telepathy 中没有负责注册正在运行的连接管理器和客户端的服务。相反，感兴趣的各方会监听 D-Bus 上的新的服务公告。每当 D-Bus 总线守护进程在总线上出现新的命名 D-Bus 服务时，它都会发出信号。客户端和连接管理器的名称以规范中定义的已知前缀开头，新的名称可以与这些前缀匹配。

这种设计的好处在于它完全是无状态的。当 Telepathy 组件启动时，它可以询问总线守护进程（它有一个基于其打开的连接的规范列表）哪些服务当前正在运行。例如，如果帐户管理器崩溃，它可以查看哪些连接正在运行，并将这些连接与其帐户对象重新关联。

通道调度程序也使用此方法来发现 Telepathy 客户端。这些客户端以ofdT.Client 开头，例如，ofdT.Client.Logger。

20.2.3. 减少 D-Bus 流量

Telepathy 规范的原始版本在总线上产生了大量 D-Bus 流量，形式为请求总线上许多消费者所需的信息的方法调用。Telepathy 的后续版本通过一些优化解决了这个问题。

单个方法调用被 D-Bus 属性替换。原始规范包括用于对象属性的单独方法调用：GetInterfaces、GetChannelType 等。请求对象的全部属性需要进行多次方法调用，每次调用都有自己的调用开销。通过使用 D-Bus 属性，可以使用标准的GetAll 方法一次性请求所有内容。

此外，通道上的许多属性在通道的整个生命周期内都是不可变的。这些包括通道类型、接口、连接对象以及请求者。例如，对于文件传输通道，它还包括文件大小和内容类型。

添加了一个新的信号来预示通道的创建（传入和响应传出请求），其中包含一个不可变属性的哈希表。这可以直接传递给通道代理构造函数（参见 第 20.4 节），这可以节省有兴趣的客户端单独请求此信息的麻烦。

用户头像作为字节数组跨总线传输。虽然 Telepathy 已经使用令牌来引用头像，允许客户端知道何时需要新的头像并保存下载不需要的头像，但每个客户端都必须通过RequestAvatar 方法单独请求头像，该方法以其回复的形式返回头像。因此，当连接管理器发出信号表明联系人已更新其头像时，将发出多个单独的头像请求，要求头像通过消息总线传输多次。

这通过添加一种不返回值量（它不返回值）的新方法来解决。相反，它将头像放在一个请求队列中。从网络获取头像将导致信号AvatarRetrieved 发出，所有感兴趣的客户端都可以监听该信号。这意味着头像数据只需要通过总线传输一次，并将对所有感兴趣的客户端可用。一旦客户端的请求在队列中，所有进一步的客户端请求将被忽略，直到AvatarRetrieved 发出。

每当需要加载大量联系人（即加载联系人列表）时，需要请求大量信息：它们的别名、头像、功能和群组成员资格，以及可能的位置、地址和电话号码。以前在 Telepathy 中，这需要对每个信息组进行一次方法调用（大多数 API 调用，例如GetAliases 已经接受联系人列表），导致六次或更多次方法调用。

为了解决这个问题，引入了Contacts 接口。它允许通过单个方法调用返回来自多个接口的信息。Telepathy 规范已扩展为包括联系人属性：由GetContactAttributes 方法返回的命名空间属性，该方法隐藏用于检索联系人信息的方法调用。客户端使用它感兴趣的联系人列表和接口调用GetContactAttributes，并获得从联系人到联系人属性到值的映射的映射。

一些代码将使这一点更加清楚。请求看起来像这样

connection[CONNECTION_INTERFACE_CONTACTS].GetContactAttributes(
  [ 1, 2, 3 ], # contact handles
  [ "ofdT.Connection.Interface.Aliasing",
    "ofdT.Connection.Interface.Avatars",
    "ofdT.Connection.Interface.ContactGroups",
    "ofdT.Connection.Interface.Location"
  ],
  False # don't hold a reference to these contacts
)

回复可能看起来像这样

{ 1: { 'ofdT.Connection.Interface.Aliasing/alias': 'Harvey Cat',
       'ofdT.Connection.Interface.Avatars/token': hex string,
       'ofdT.Connection.Interface.Location/location': location,
       'ofdT.Connection.Interface.ContactGroups/groups': [ 'Squid House' ],
       'ofdT.Connection/contact-id': 'harvey@nom.cat'
     },
  2: { 'ofdT.Connection.Interface.Aliasing/alias': 'Escher Cat',
       'ofdT.Connection.Interface.Avatars/token': hex string,
       'ofdT.Connection.Interface.Location/location': location,
       'ofdT.Connection.Interface.ContactGroups/groups': [],
       'ofdT.Connection/contact-id': 'escher@tuxedo.cat'
     },
  3: { 'ofdT.Connection.Interface.Aliasing/alias': 'Cami Cat',
        ⋮    ⋮    ⋮
     }
}

20.3.1. 连接

连接由连接管理器创建，以建立与单个协议/帐户的连接。例如，连接到 XMPP 帐户escher@tuxedo.cat 和cami@egg.cat 将导致两个连接，每个连接由一个 D-Bus 对象表示。连接通常由帐户管理器为当前启用的帐户设置。

连接为管理和监控连接状态以及请求通道提供了一些强制功能。然后，它还可以根据协议的功能提供一些可选功能。这些作为可选的 D-Bus 接口提供（如上一节所述），并由连接的Interfaces 属性列出。

通常，连接由帐户管理器管理，使用相应帐户的属性创建。帐户管理器还将用户的当前状态与每个帐户同步到其相应的连接，并且可以被要求提供给定帐户的连接路径。

20.3.2. 通道

通道是进行通信的机制。通道通常是即时聊天对话、语音或视频通话或文件传输，但通道也用于提供与服务器本身的某些有状态通信（例如，搜索聊天室或联系人）。每个通道都由一个 D-Bus 对象表示。

通道通常位于两个或多个用户之间，其中一个是您自己。它们通常具有目标标识符，对于一对一通信，该标识符是另一个联系人；对于多用户通信（例如，聊天室），则为房间标识符。多用户通道公开Group 接口，允许您跟踪当前在通道中的联系人。

通道属于连接，并从连接管理器请求，通常通过通道调度程序；或者它们是由连接响应网络事件（例如，传入聊天）创建的，并传递给通道调度程序以进行调度。

通道类型由通道的ChannelType 属性定义。此通道类型所需的核心功能、方法、属性和信号（例如，发送和接收文本消息）在相应的Channel.Type D-Bus 接口中定义，例如，Channel.Type.Text。某些通道类型可能会实现可选的附加功能（例如，加密），这些功能显示为通道的Interfaces 属性列出的附加接口。一个将用户连接到多用户聊天室的示例文本通道可能具有 表 20.1 中显示的接口。

20.3.3. 请求频道、频道属性和调度

使用您希望目标频道拥有的属性映射来请求频道。通常，频道请求将包括频道类型、目标句柄类型（联系人或房间）和目标。但是，频道请求还可以包括诸如文件传输的文件名和文件大小、是否最初包含呼叫的音频和视频、将哪些现有频道合并到会议呼叫中，或者要在哪个联系人服务器上进行联系人搜索之类的属性。

频道请求中的属性是 Telepathy 规范接口定义的属性，例如ChannelType 属性（表 20.2）。它们与它们所属的接口的命名空间限定。可以包含在频道请求中的属性在 Telepathy 规范中被标记为可请求。

表 20.3中的更复杂示例请求文件传输频道。请注意，请求的属性是如何通过它们所属的接口进行限定的。（为了简洁，并非所有必需属性都显示出来。）

频道可以创建或确保。确保频道意味着仅在它不存在的情况下创建它。请求创建频道将导致创建一个全新的独立频道，或者如果多个此类频道的副本不能共存，则会生成错误。通常您希望确保文本频道和呼叫（即，您只需要与某人打开一个对话，事实上，许多协议不支持与同一联系人进行多个单独的对话），并希望创建文件传输和有状态频道。

新创建的频道（请求的或其他）由连接发出的信号宣布。此信号包含一个频道不可变属性的映射。这些是保证在频道整个生命周期中不会改变的属性。被认为不可变的属性在 Telepathy 规范中被标记为不可变，但通常包括频道的类型、目标句柄类型、目标、发起者（创建频道的人）和接口。诸如频道状态之类的属性显然不包括在内。

当您创建或确保频道时返回频道的不可变属性，这使得为频道创建代理对象的速度快得多。这是我们现在不必请求的信息。 表 20.4中的映射显示了我们在请求文本频道时可能包含的不可变属性（即，使用表 20.3中的频道请求）。出于简洁起见，已排除某些属性（包括TargetHandle 和InitiatorHandle）。

请求程序通常向频道调度程序发出频道请求，提供请求所针对的帐户、频道请求，以及可选的所需处理程序的名称（如果程序希望自行处理频道，这很有用）。传递帐户名称而不是连接意味着频道调度程序可以要求帐户管理器在线连接帐户（如果需要）。

请求完成后，频道调度程序要么将频道传递给命名处理程序，要么定位合适的处理程序（有关处理程序和其他客户端的讨论，请参见下文）。使所需处理程序的名称可选，使得对于对初始请求之外的通信频道不感兴趣的程序来说，可以请求频道并让最佳程序处理它们（例如，从电子邮件客户端启动文本聊天）。

图 20.4：频道请求和调度

请求程序向频道调度程序发出频道请求，频道调度程序反过来将请求转发到相应的连接。连接发出 NewChannels 信号，该信号被频道调度程序接收，然后找到合适的客户端来处理该频道。传入的、未请求的频道以几乎相同的方式调度，从连接发出信号，该信号被频道调度程序接收，但显然没有来自程序的初始请求。

20.3.4. 客户端

客户端处理或观察传入和传出的通信频道。客户端是任何注册到频道调度程序的内容。有三种类型的客户端（尽管单个客户端可以是两种，或所有三种类型，如果开发人员愿意）。

• 观察者：观察频道而不与它们交互。观察者通常用于聊天和活动日志记录（例如，传入和传出的 VoIP 呼叫）。
• 批准者：负责让用户有机会接受或拒绝传入频道。
• 处理程序：实际上与频道交互。这可能是确认和发送文本消息、发送或接收文件等等。处理程序往往与用户界面相关联。

客户端提供 D-Bus 服务，最多具有三个接口：Client.Observer、Client.Approver 和Client.Handler。每个接口提供一个方法，频道调度程序可以调用该方法来告知客户端有关要观察、批准或处理的频道的信息。

频道调度程序依次将频道调度到每个客户端组。首先，将频道调度到所有相应的观察者。一旦它们都返回，频道将调度到所有相应的批准者。一旦第一个批准者批准或拒绝了频道，所有其他批准者都会收到通知，最终频道将调度到处理程序。频道调度是分阶段进行的，因为观察者可能需要一些时间才能做好准备，然后再由处理程序开始更改频道。

客户端公开一个频道筛选器属性，这是一个由频道调度程序读取的筛选器列表，以便它知道客户端对哪些类型的频道感兴趣。筛选器必须至少包括客户端感兴趣的频道类型和目标句柄类型（例如，联系人或房间），但它可以包含更多属性。匹配是使用简单的相等比较，针对频道的不可变属性进行的。 表 20.5中的筛选器匹配所有一对一的文本频道。

客户端可以通过 D-Bus 发现，因为它们发布以众所周知名称ofdT.Client 开头的服务（例如ofdT.Client.Empathy.Chat）。它们还可以选择安装一个文件，频道调度程序将读取该文件以指定频道筛选器。这允许频道调度程序在客户端未运行时启动它。以这种方式使客户端可发现，使用户界面选择可配置，并且可以在任何时候更改，而无需替换 Telepathy 的任何其他部分。

20.4.1. 异步编程

在语言绑定中，所有通过 D-Bus 进行请求的方法调用都是异步的：发出请求，并在回调中给出回复。这是必需的，因为 D-Bus 本身是异步的。

与大多数网络和用户界面编程一样，D-Bus 需要使用事件循环来调度传入信号和方法返回的回调。D-Bus 与 GTK+ 和 Qt 工具包使用的 GLib 主循环很好地集成在一起。

一些 D-Bus 语言绑定（例如 dbus-glib）提供了一个伪同步 API，其中主循环会阻塞，直到方法回复返回。曾经，这通过 telepathy-glib API 绑定暴露出来。不幸的是，使用伪同步 API 充满了问题，最终从 telepathy-glib 中移除。

第一个 Telepathy 绑定中的方法调用，在 C 中生成，只是使用 typedef 回调函数。你的回调函数只需要实现相同的类型签名。

typedef void (*tp_conn_get_self_handle_reply) (
    DBusGProxy *proxy,
    guint handle,
    GError *error,
    gpointer userdata
);

这个想法很简单，对 C 来说有效，因此在下一代绑定中继续使用。

近年来，人们已经开发出一种方法来使用脚本语言，例如 Javascript 和 Python，以及一个名为 Vala 的类似 C# 的语言，这些语言通过名为 GObject-Introspection 的工具使用基于 GLib/GObject 的 API。不幸的是，将这些类型的回调重新绑定到其他语言非常困难，因此较新的绑定被设计为利用语言和 GLib 提供的异步回调功能。

20.4.2. 对象就绪

在简单的 D-Bus API 中，例如低级 Telepathy 绑定，你可以通过为它创建代理对象来开始对 D-Bus 对象进行方法调用或接收信号。它就像提供一个对象路径和接口名称一样简单，然后开始使用。

但是，在 Telepathy 的高级 API 中，我们希望我们的对象代理知道哪些接口可用，我们希望检索对象类型的通用属性（例如，通道类型、目标、发起者），并且我们希望确定和跟踪对象的 state 或状态（例如，连接状态）。

因此，就绪的概念存在于所有代理对象中。通过对代理对象进行方法调用，你能够异步地检索该对象的 state，并在 state 被检索到且对象可以使用时收到通知。

由于并非所有客户端都实现或感兴趣于给定对象的所有功能，因此对象类型的就绪被分成许多可能的功能。每个对象都实现了一个核心功能，这将准备有关对象的关键信息（即它的 `Interfaces` 属性和基本 state），以及一些可选功能以获取其他 state，这可能包括额外的属性或 state 跟踪。你可以准备各种代理上的其他功能的具体示例包括联系信息、功能、地理位置信息、聊天 state（例如，“Escher 正在输入……”）和用户头像。

例如，连接对象代理具有

• 一个核心功能，检索接口和连接状态；
• 功能用于检索可请求的通道类和支持联系信息；以及
• 一个功能用于建立连接并在连接时返回就绪状态。

程序员请求对象就绪，提供他们感兴趣的功能列表以及在所有这些功能都就绪时要调用的回调。如果所有功能都已经就绪，则可以立即调用回调，否则，一旦检索到所有这些功能的信息，就会调用回调。