API 个人通讯录调用的说明

有关的API 调用

背景知识 (用户属性)

和个人通讯录有关的用户属性

属性名 类型 说明

iaddress 字符串 类似 vcard 格式的字符串, 包含了用户个人通讯录的所有联系人以及分组信息

有关 iaddress 属性的字符串格式, 在下一章中再详细说明

属性及值均是使用URL 参数的方式以字符串来传递, 使用 & 连接多个属性, 使用 = 连接属性和值

比如要传递属性 a, 值为 xyz, 则传递的字符串为 a=xyz

假如值中包含特殊字符则需要使用URL 的标准来编码

比如要传递属性 a, 值为 x=x, 其中"="是特殊符号需要编码为"%3C", 最终传递的字符串为 a=x%3Cx

对于中文字符串, 进行URL 编码时要使用 GBK 字符集

1. 通过 GetUserInfo 调用获取用户的个人通讯录内容

Java API 接口调用

APIContext getAttrs(String userAtDomain, String attrs) throws IOException;

C API 接口调用

API_RTCODE API_GetUserInfo(const char * lpszUserAtDomain, const char * lpszParams, APIContext *pContext );

其中 attrs/lpszParams 的值为: "iaddress=", 表示要获取个人通讯录内容 执行成功的返回值的格式是 "iaddress=通讯录内容", 其中属性值经过了编码(如上一节的说明)

2. 通过 AlterUserInfo 调用更新用户的个人通讯录内容

Java API 接口调用

APIContext changeAttrs(String userAtDomain, String attrs) throws IOException;

C API 接口调用

API_RTCODE API_AlterUserInfo(const char * lpszUserAtDomain, const char * lpszParams, APIContext *pContext );

其中 attrs/lpszParams 的值为: "iaddress=通讯录内容", 其中属性值需要经过了编码(如上一节的说明)

个人通讯录内容格式

个人通讯录内容 (用户的 iaddress 属性值) 使用了混合的简化 vcard 方式存储, 其中包含了用户的所有联系人和分组信息, 如下

iaddress 格式样例

BEGIN:VCARD --- 开始

VERSION:2.1 --- 版本信息

X-TEBIE WORK GROUP:8:FRIENDS:FAMILY:COWORKERS:NETFRIENDS:VIP:101:102 BEGIN:VCARD ------- 第一个联系人定义开始

FN:ys2 ----------- 联系人姓名

N:ys2

EMAIL;PREF:ys2@ ----------- 邮件地址

TEL;CELL;VOICE:2141243 ----------- 具体有哪些属性和代表什么含义请参考配置和下面的属性说明

UID:8 ----------- 联系人的唯一标识

END:VCARD ------- 第一个联系人定义结束

BEGIN:VCARD ------- 第一个联系组定义开始

X-TYPE:GROUP ----------- 特殊属性，表示这个项是一个联系组

X-TYPE1:SYSTEM ----------- 特殊属性，表示这个联系组是一个系统联系组

N:朋友 ----------- 联系组名称

UID:FRIENDS ----------- 联系组的唯一表示

END:VCARD ------- 第一个联系组定义结束

BEGIN:VCARD ------- 第二个联系组定义开始

X-TYPE:GROUP ------- ... ...

X-TYPE1:SYSTEM

N:家庭

UID:FAMILY

END:VCARD

BEGIN:VCARD

X-TYPE:GROUP

X-TYPE1:SYSTEM

N:同事

UID:COWORKERS

END:VCARD

BEGIN:VCARD

X-TYPE:GROUP

X-TYPE1:SYSTEM

N:网友

UID:NETFRIENDS

END:VCARD

BEGIN:VCARD

X-TYPE:GROUP

X-TYPE1:SYSTEM

N:重要联系人

UID:VIP

END:VCARD

BEGIN:VCARD

X-TYPE:GROUP

N:自定义

UID:101

END:VCARD

BEGIN:VCARD ------- 最后一个联系组定义开始

X-TYPE:GROUP

N:101

UID:102

BEGIN:VCARD ------- 最后一个联系组定义结束

END:VCARD --- 结束

其中每个项(包括联系人及联系组)都是属性的组合，所有项都是以 BEGIN:VCARD 开始定义 END:VCARD 结束定义, 每个属性占一行, 以冒号分割属性名和属性值, 属性值中不包含回车换行字符, 系统预定义有以下这些联系人属性

属性名说明/格式

UID 联系人唯一标识, 一般是系统自动生成, 可能有些联系人可能会没有标识

FN 姓名EMAIL;PREF Email

Grouping 所属联系组, 多个分组之间以分号 ; 连接, 引用联系组定义中的 UID 属性

BDAY 生日, 格式为 yyyyMMdd TEL;CELL;VOICE 手机

ICQ ICQ

URL 主页

ADR;HOME 家庭住址

PC;HOME 家庭邮政编码

TEL;HOME;VOICE 家庭电话

ORGNAME 公司名称