Tinode即时通讯系统中的theCard数据格式详解

Tinode即时通讯系统中的theCard数据格式详解

chat Instant messaging platform. Backend in Go. Clients: Swift iOS, Java Android, JS webapp, scriptable command line; chatbots 项目地址: https://gitcode.com/gh_mirrors/ch/chat

什么是theCard

在Tinode即时通讯系统中，theCard是一种用于存储和传输人员及话题描述信息的结构化数据格式。它类似于传统通讯录中的联系人卡片，但专门为即时通讯场景进行了优化设计。

格式演变历史

theCard最初被称为vCard，这与RFC 6350定义的vCard标准名称相同但格式不兼容，这在实际使用中造成了一些混淆。为了解决这个问题，Tinode团队将其重命名为theCard。需要注意的是，在代码和文档中可能仍然会看到vCard或vCard的引用，除非特别说明，这些都应该理解为theCard格式。

JSON表示形式

当使用JSON来表示theCard数据时，它与jCard(RFC 7095)标准不同，两者不兼容。主要区别在于：

1. theCard使用对象来表示逻辑相关的数据
2. jCard使用有序数组结构

这种设计使得theCard更易于理解和处理，特别是在即时通讯这种需要快速解析的场景中。

数据结构详解

theCard是一个包含多个可选字段的对象，以下是各字段的详细说明：

基本字段

1. fn (Formatted Name)

   • 类型：字符串
   • 说明：人员或话题的格式化名称
   • 示例："张三"

2. photo (头像照片)

   • 类型：对象
   • 要求：必须包含data或ref字段之一
   • 子字段：
     • type：图片类型(省略了"image/"前缀的MIME类型)
     • data：Base64编码的二进制图片数据
     • ref：图片的URL地址
     • width：图片宽度(像素)
     • height：图片高度(像素)
     • size：图片大小(字节)

3. note (备注)

   • 类型：字符串
   • 说明：对人员或话题的描述信息

扩展字段(当前客户端未实现)

1. n (结构化名称)

   • 子字段：
     • surname：姓氏
     • given：名字
     • additional：附加名(如中间名)
     • prefix：前缀(如头衔)
     • suffix：后缀(如"Jr")

2. org (组织信息)

   • 子字段：
     • fn：组织名称
     • title：职位头衔

3. tel (电话号码列表)

   • 类型：对象数组
   • 每个对象包含：
     • type：联系方式类型(如"HOME")
     • uri：电话号码URI

4. email (电子邮件列表)

   • 类型：对象数组
   • 每个对象包含：
     • type：邮件类型(如"WORK")
     • uri：邮件地址

5. comm (其他联系方式)

   • 类型：对象数组
   • 每个对象包含：
     • type：联系类型
     • name：联系方式名称
     • uri：特定于联系类型的URI

6. bday (生日)

   • 子字段：
     • y：年份
     • m：月份(1-12)
     • d：日期(1-31)

实际应用情况

目前Tinode客户端主要使用fn和photo这两个基本字段。其他字段虽然已定义但尚未被任何已知客户端实现。这种设计为未来功能扩展预留了空间，如果需要，可以从对应的vCard标准字段中采用更多属性。

技术实现建议

1. 在处理theCard数据时，应该始终将其视为可选字段的集合，不要假设任何字段必然存在。

2. 对于照片数据，优先检查ref字段(外部引用)，如果没有再处理data字段(内联数据)。

3. 考虑到未来兼容性，实现时应保留未知字段而不是丢弃它们。

4. 在用户界面展示时，可以根据可用字段灵活组合显示信息，例如优先显示fn，然后是note等。

theCard格式的设计体现了Tinode系统在数据结构和扩展性方面的深思熟虑，既满足了当前即时通讯的基本需求，又为未来的功能演进预留了充足的空间。

chat Instant messaging platform. Backend in Go. Clients: Swift iOS, Java Android, JS webapp, scriptable command line; chatbots 项目地址: https://gitcode.com/gh_mirrors/ch/chat