飞信Symbian客户端接口规范版本:1.0
掌上明珠公司
2006年7月21日
更新日期 更新者 更新内容
2006-7-18 刘垌序
修改文档(添加消息)
1、 添加Fetion交友服务消息
2、 修改GetConfig消息
3、 修改GetUserConfig消息
目录
2006年7月18日 1
1. 范围 18
2. 参考文献 18
3. 术语和缩略语 19
4. 系统结构 20
5. 基础协议 20
5.1. SMS 20
5.2. HTTP 21
5.3. SIP 21
5.4. SDP 21
5.5. XML 21
5.6. 加密算法 21
5.7. 压缩算法 21
6. SIP-C基础 22
6.1. 概述 22
6.2. SIP方法的缩写 22
6.3. SIP消息头的缩写 23
7. 服务状态改变 23
7.1. 业务定购 23
7.1.1. 移动设备 24
7.1.1.1. 过程描述 24
7.1.1.2. 短信发送格式 - [SMS-Register] 24
7.1.1.3. 短信接收格式 - [SMS-RSP-Register] 25
7.1.2. 非移动设备 25
7.2. 业务退订 25
7.2.1. 短信方式 - [SMS-Unregister] 25
7.2.2. 命令方式 26
8. 登陆状态改变 26
8.1. 模式 26
8.2. 请求注册 27
8.2.1. 注册请求消息 - [REG-1] 27
8.2.1.1. 消息格式 27
8.2.1.2. 示例 27
8.2.2. 注册应答消息 - [REG-RSP-1] 28
8.2.2.1. 消息格式 28
8.2.2.2. 错误处理 28
8.2.2.3. 示例 28
8.3. 请求认证 29
8.3.1. 认证请求消息 - [REG-2] 29
8.3.1.1. 消息格式 29
8.3.1.2. 凭据生成算法 29
8.3.1.3. 示例 30
8.3.2. 认证应答消息 - [REG-RSP-2] 30
8.3.2.1. 消息格式 30
8.3.2.2. 错误处理 30
8.3.2.3. 示例 31
8.4. 协商流压缩 31
8.4.1. 协商请求 - [NEG-COMPRESS] 31
8.4.1.1. 消息格式 31
8.4.1.2. 压缩算法 31
8.4.1.3. 示例 32
8.4.2. 协商应答消息 - [NEG-COMPRESS-RSP-2] 32
8.4.2.1. 消息格式 32
8.4.2.2. 错误处理 32
8.4.2.3. 示例 33
8.5. 保持注册 33
8.5.1. 保持注册请求消息 - [REG-3] 33
8.5.1.1. 消息格式 33
8.5.1.2. 示例 33
8.5.2. 保持注册应答消息 - [REG-RSP-3] 34
8.5.2.1. 消息格式 34
8.5.2.2. 示例 34
8.6. 注销 35
8.6.1. 注销请求消息 - [UNREG-1] 35
8.6.1.1. 消息格式 35
8.6.1.2. 示例 35
8.6.2. 注销应答消息 - [UNREG-RSP-1] 36
8.6.2.1. 消息格式 36
8.6.2.2. 错误处理 36
8.6.2.3. 示例 36
8.7. 强制注销通知 36
8.7.1. 通知消息 - [NTF-Registration] 37
8.7.1.1. 消息格式 37
8.7.1.2. 消息体格式 37
8.7.1.3. 消息示例 38
8.7.2. 应答消息 - [NTF-RSP- Registration] 39
8.7.2.1. 消息格式 39
8.7.2.2. 消息示例 39
8.7.2.3. 错误处理 39
9. 订阅-通知 40
9.1. 模式 40
9.2. 联系人列表 40
9.2.1. 订阅联系人列表 40
9.2.1.1. 订阅请求 - [SUB-Contacts] 41
9.2.1.2. 订阅应答 - [SUB-RSP-Contacts] 42
9.2.2. 联系人列表通知 43
9.2.2.1. 通知消息 - [NTF-Contacts] 44
9.2.2.2. 应答消息 - [NTF-RSP-Contacts] 47
9.2.3. 退订联系人列表 49
9.2.3.1. 退订请求 - [UNSUB-Contacts] 49
9.2.3.2. 退订应答 - [UNSUB-RSP-Contacts] 50
9.3. 状态授权信息 50
9.3.1. 订阅状态授权信息 50
9.3.1.1. 订阅请求 - [SUB-ACLs] 51
9.3.1.2. 订阅应答 - [SUB-RSP-ACLs] 52
9.3.2. 授权信息通知 54
9.3.2.1. 通知消息 - [NTF-ACLs] 54
9.3.2.2. 应答消息 - [NTF-RSP-ACLs] 57
9.3.3. 退订授权信息 58
9.3.3.1. 退订请求 - [UNSUB-ACLs] 58
9.3.3.2. 退订应答 - [UNSUB-RSP-ACLs] 59
9.4. 状态订阅申请 60
9.4.1. 订阅状态订阅申请 60
9.4.1.1. 订阅消息 - [SUB-WPending] 60
9.4.1.2. 应答消息 - [SUB-RSP-WPending] 61
9.4.2. 订阅申请通知 63
9.4.2.1. 通知消息 - [NTF-WPending] 63
9.4.2.2. 应答消息 - [NTF-RSP-WPending] 65
9.4.3. 退订状态订阅申请 66
9.4.3.1. 退订请求 - [UNSUB-WPending] 66
9.4.3.2. 退订应答 - [UNSUB-RSP-WPending] 67
9.5. 联系人状态 68
9.5.1. 批量订阅联系人状态 68
9.5.1.1. 订阅请求 - [SUB-Presence-1] 68
9.5.1.2. 订阅应答 - [SUB-RSP-Presence-1] 72
9.5.2. 单个订阅联系人状态 74
9.5.2.1. 订阅请求 - [SUB-Presence-2] 75
9.5.2.2. 订阅应答 - [SUB-RSP-Presence-2] 76
9.5.3. 联系人状态变化通知 77
9.5.3.1. 通知消息 - [NTF-Presence] 77
9.5.3.2. 应答消息 - [NTF-RSP-Presence] 80
9.5.3.3. 错误处理 80
9.5.4. 批量退订联系人状态 81
9.5.4.1. 退订请求 - [UNSUB-Presence-1] 81
9.5.4.2. 退订应答 - [UNSUB-RSP-Presence-1] 82
9.5.5. 单个退订联系人状态 83
9.5.5.1. 退订请求 - [UNSUB-Presence-2] 83
9.5.5.2. 退订应答 - [UNSUB-RSP-Presence-2] 84
10. 系统服务 85
10.1. 模式 85
10.2. 获取用户信息 86
10.2.1. 请求消息 - [SVC-GetUserConfig] 86
10.2.1.1. 消息格式 86
10.2.1.2. 消息体格式 87
10.2.1.3. 消息示例 88
10.2.2. 应答消息 - [SVC-RSP-GetUserConfig] 88
10.2.2.1. 消息格式 88
10.2.2.2. 消息体格式(DeailFlag=5) 89
10.2.2.3. 消息体格式(DeailFlag=3) 92
10.2.2.4. 消息体格式(DeailFlag=1) 93
10.2.2.5. 消息示例 94
10.2.2.6. 错误处理 95
10.3. 添加联系人 95
10.3.1. 请求消息 - [SVC-AddContact] 95
10.3.1.1. 消息格式 95
10.3.1.2. 消息示例 96
10.3.2. 应答消息 - [SVC-RSP-AddContact] 96
10.3.2.1. 消息格式 96
10.3.2.2. 消息示例 96
10.3.2.3. 错误处理 97
10.3.3. 通知消息 - [NTF-AddContact] 97
10.3.3.1. 消息体格式 97
10.3.3.2. 消息体示例 98
10.4. 修改联系人分组 98
10.4.1. 请求消息 - [SVC-SetGroups] 98
10.4.1.1. 消息格式 98
10.4.1.2. 消息示例 99
10.4.2. 应答消息 - [SVC-RSP- SetGroups] 99
10.4.2.1. 消息格式 99
10.4.2.2. 消息示例 100
10.4.2.3. 错误处理 100
10.4.3. 通知消息 - [NTF- SetGroups] 100
10.4.3.1. 消息体格式 100
10.4.3.2. 消息体示例 101
10.5. 状态订阅授权 102
10.5.1. 请求消息 - [SVC-SetACE] 102
10.5.1.1. 消息格式 102
10.5.1.2. 消息示例 103
10.5.2. 应答消息 - [SVC-RSP- SetACE] 103
10.5.2.1. 消息格式 103
10.5.2.2. 消息示例 103
10.5.2.3. 错误处理 104
10.5.3. 通知消息 - [NTF-SetACE] 104
10.6. 删除联系人 104
10.6.1. 请求消息 - [SVC-DeleteContact] 104
10.6.1.1. 消息格式 104
10.6.1.2. 消息示例 105
10.6.2. 应答消息 - [SVC-RSP-DeleteContact] 105
10.6.2.1. 消息格式 105
10.6.2.2. 消息示例 106
10.6.2.3. 错误处理 106
10.6.3. 通知消息 - [NTF-DeleteContact] 106
10.6.3.1. 消息体格式 106
10.6.3.2. 消息体示例 107
10.7. 添加联系人组 107
10.7.1. 请求消息 - [SVC-AddGroup] 107
10.7.1.1. 消息格式 107
10.7.1.2. 消息示例 108
10.7.2. 应答消息 - [SVC-RSP- AddGroup] 108
10.7.2.1. 消息格式 108
10.7.2.2. 消息示例 108
10.7.2.3. 错误处理 109
10.7.3. 通知消息 - [NTF- AddGroup] 109
10.7.3.1. 消息体格式 109
10.7.3.2. 消息体示例 110
10.8. 修改联系人组 110
10.8.1. 请求消息 - [SVC-ModifyGroup] 110
10.8.1.1. 消息格式 110
10.8.1.2. 消息示例 111
10.8.2. 应答消息 - [SVC-RSP-ModifyGroup] 111
10.8.2.1. 消息格式 111
10.8.2.2. 消息示例 111
10.8.2.3. 错误处理 112
10.8.3. 通知消息 - [NTF-ModifyGroup] 112
10.8.3.1. 消息体格式 112
10.8.3.2. 消息体示例 113
10.9. 删除联系人组 113
10.9.1. 请求消息 - [SVC-DeleteGroup] 113
10.9.1.1. 消息格式 113
10.9.1.2. 消息示例 114
10.9.2. 应答消息 - [SVC-RSP- DeleteGroup] 114
10.9.2.1. 消息格式 114
10.9.2.2. 消息示例 114
10.9.2.3. 错误处理 115
10.9.3. 通知消息 - [NTF-DeleteGroup] 115
10.9.3.1. 消息体格式 115
10.9.3.2. 消息示例 115
10.10. 设置显示状态 116
10.10.1. 请求消息 - [SVC-SetPresence] 116
10.10.1.1. 消息格式 116
10.10.1.2. 消息体格式 116
10.10.1.3. 消息示例 117
10.10.2. 应答消息 - [SVC-RSP- SetPresence] 117
10.10.2.1. 消息格式 117
10.10.2.2. 消息示例 118
10.10.2.3. 错误处理 118
10.10.3. 通知消息 - [NTF-Presence] 118
10.11. 修改个人资料 118
10.11.1. 请求消息 - [SVC-UpdateUserConfig] 118
10.11.1.1. 消息格式 118
10.11.1.2. 消息体格式 119
10.11.1.3. 消息示例 120
10.11.2. 应答消息 - [SVC-RSP- SetPresence] 120
10.11.2.1. 消息格式 120
10.11.2.2. 消息示例 121
10.11.2.3. 错误处理 121
10.11.3. 发送改变通知 121
10.12. 获取手机状态 121
10.12.1. 请求消息 - [SVC-GetMobileInfo] 121
10.12.1.1. 消息格式 121
10.12.1.2. 消息体格式 122
10.12.1.3. 消息示例 123
10.12.2. 应答消息 - [SVC-RSP-GetMobileInfo] 123
10.12.2.1. 消息格式 123
10.12.2.2. 消息体格式 124
10.12.2.3. 消息示例 124
10.12.2.4. 错误处理 125
10.13. 随机速配 125
10.13.1. 请求消息 - [SVC-RandomQueryUser] 125
10.13.1.1. 消息格式 125
10.13.1.2. 消息体格式 125
10.13.1.3. 消息示例 126
10.13.2. 应答消息 - [SVC-RSP- RandomQueryUser] 127
10.13.2.1. 消息格式 127
10.13.2.2. 消息体格式 127
10.13.2.3. 消息示例 128
10.13.2.4. 错误处理 129
10.14. 条件速配 129
10.14.1. 请求消息 - [SVC-QueryUser] 129
10.14.1.1. 消息格式 129
10.14.1.2. 消息体格式 130
10.14.1.3. 消息示例 131
10.14.2. 应答消息 - [SVC-RSP-QueryUser] 132
10.14.2.1. 消息格式 132
10.14.2.2. 消息体格式 132
10.14.2.3. 消息示例 133
10.14.2.4. 错误处理 134
10.15. 系统消息 134
10.15.1. 接收消息 - [MSG-SystemMessage] 134
10.15.1.1. 消息格式 134
10.15.1.2. 消息体格式 134
10.15.1.3. 消息示例 135
10.15.2. 应答消息 - [MSG-RSP-SystemMessage] 135
10.15.2.1. 消息格式 135
10.15.2.2. 消息示例 135
10.15.2.3. 错误处理 136
10.16. 退定服务 136
10.16.1. 请求消息 - [SVC-CloseService] 136
10.16.1.1. 消息格式 136
10.16.1.2. 消息体格式 136
10.16.1.3. 消息示例 137
10.16.2. 应答消息 - [SVC-RSP-CloseService] 137
10.16.2.1. 消息格式 137
10.16.2.2. 消息体格式 138
10.16.2.3. 消息示例 139
10.16.2.4. 错误处理 139
10.17. FETION交友服务 140
10.17.1开通Fetion交友服务 – [SVC-RegisterFriendMatching] 140
10.17.2应答消息 – [SVC-RSP-RegisterFriendMatching] 141
10.17.3 关闭Fetion交友服务 – [SVC-UnregisterFriendMatching] 142
10.17.4 应答消息 - [SVC-RSP-UnregisterFriendMatching] 143
10.18. 获取权限信息 145
10.18.1 请求消息 - [SVC-GetPrivacy] 145
10.18.1.1 消息格式 145
10.18.1.2 消息示例 145
10.18.2 应答消息 - [SVC-RSP-GetPrivacy] 145
10.18.2.1 消息格式 145
10.18.2.2 消息体格式 146
10.18.2.3 消息示例 146
10.19. 设置权限消息 147
10.19.1请求消息 - [SVC-SetPrivacy] 147
10.19.1.1消息格式 147
10.19.1.2 消息体格式 147
10.19.1.3 消息示例 148
10.19.2 应答消息 - [SVC-RSP- SetPrivacy] 148
10.19.2.1 消息格式 148
10.19.2.2 消息示例 149
11. 即时消息 150
11.1. 模式 150
11.1.1. 双方邀请 150
11.1.2. 取消邀请 151
11.1.3. 发送与接收 151
11.1.4. 退出会话 152
11.2. 邀请过程 153
11.2.1. UAC 153
11.2.1.1. 请求消息 – [INVITE-IM-UAC] 153
11.2.1.2. 临时应答 – [INVITE-RSP-IM-UAC-Trying] 155
11.2.1.3. 回铃 – [INVITE-RSP-IM-UAC-Ringing] 156
11.2.1.4. 最终应答 – [INVITE-RSP-IM-UAC] 157
11.2.2. UAS 159
11.2.2.1. 请求消息 – [INVITE-IM-UAS] 159
11.2.2.2. 临时应答 – [INVITE-RSP-IM-UAS-Trying] 160
11.2.2.3. 回铃 – [INVITE-RSP-IM-UAS-Ringing] 161
11.2.2.4. 最终应答 – [INVITE-RSP-IM-UAS] 163
11.3. 取消过程 165
11.3.1. UAC 165
11.3.1.1. 请求消息 – [CANCEL-IM-UAC] 165
11.3.1.2. 应答消息 – [CANCEL-RSP-IM-UAC] 166
11.3.2. UAS 167
11.3.2.1. 请求消息 – [CANCEL-IM-UAS] 167
11.3.2.2. 应答消息 – [CANCEL-RSP-IM-UAS] 168
11.4. 确认过程 169
11.4.1. UAC – [ACK-IM-UAC] 169
11.4.1.1. 消息格式 169
11.4.1.2. 消息示例 169
11.4.2. UAS – [ACK-IM-UAS] 170
11.4.2.1. 消息格式 170
11.4.2.2. 消息示例 170
11.4.2.3. 错误处理 170
11.5. 消息传送 171
11.5.1. UAC 171
11.5.1.1. 请求消息 – [MSG-IM-UAC] 171
11.5.1.2. 应答消息 – [MSG-RSP-IM-UAC] 172
11.5.2. UAS 173
11.5.2.1. 请求消息 – [MSG-IM-UAS] 173
11.5.2.2. 应答消息 – [MSG-RSP-IM-UAS] 174
11.6. 结束会话 175
11.6.1. UAC 175
11.6.1.1. 请求消息 – [BYE-IM-UAC] 175
11.6.1.2. 应答消息 – [BYE-RSP-IM-UAC] 176
11.6.2. UAS 177
11.6.2.1. 请求消息 – [BYE-IM-UAS] 177
11.6.2.2. 应答消息 – [BYE-RSP-IM-UAS] 178
11.7. 文件共享 179
11.7.1. 上传文件 179
11.7.2. 发送消息 179
11.7.3. 下载文件 179
12. 语音聊天(IVR) 180
12.1. 模式 180
12.1.1. 流程 180
12.1.2. 取消过程 181
12.2. 邀请过程 182
12.2.1. UAC 182
12.2.1.1. 请求消息 – [INVITE-IVR-UAC] 182
12.2.1.2. 临时应答 – [INVITE-RSP-IVR-UAC-Trying] 184
12.2.1.3. 回铃 – [INVITE-RSP-IVR-UAC-Ringing] 185
12.2.1.4. 最终应答 – [INVITE-RSP-IVR-UAC] 186
12.2.2. UAS 188
12.2.2.1. 请求消息 – [INVITE-IVR-UAS] 188
12.2.2.2. 临时应答 – [INVITE-RSP-IVR-UAS-Trying] 189
12.2.2.3. 回铃 – [INVITE-RSP-IVR-UAS-Ringing] 190
12.2.2.4. 最终应答 – [INVITE-RSP-IVR-UAS] 191
12.3. 取消过程 193
12.3.1. UAC 193
12.3.1.1. 请求消息 – [CANCEL-IVR-UAC] 193
12.3.1.2. 应答消息 – [CANCEL-RSP-IVR-UAC] 194
12.3.2. UAS 195
12.3.2.1. 请求消息 – [CANCEL-IVR-UAS] 195
12.3.2.2. 应答消息 – [CANCEL-RSP-IVR-UAS] 196
12.4. 确认过程 197
12.4.1. UAC – [ACK-IVR-UAC] 197
12.4.1.1. 消息格式 197
12.4.1.2. 消息示例 197
12.4.2. UAS – [ACK-IVR-UAS] 198
12.4.2.1. 消息格式 198
12.4.2.2. 消息示例 198
12.4.2.3. 错误处理 198
12.5. 发起聊天 199
12.5.1. 请求消息 - [SVC-StartVoiceChat] 199
12.5.1.1. 消息格式 199
12.5.1.2. 消息体格式 200
12.5.1.3. 消息示例 201
12.5.2. 应答消息 - [SVC-RSP-StartVoiceChat] 202
12.5.2.1. 消息格式 202
12.5.2.2. 消息体格式 202
12.5.2.3. 消息示例 203
12.5.2.4. 错误处理 203
12.6. 结束会话 203
12.6.1. UAC 203
12.6.1.1. 请求消息 – [BYE-IVR-UAC] 204
12.6.1.2. 应答消息 – [BYE-RSP-IVR-UAC] 205
12.6.2. UAS 206
12.6.2.1. 请求消息 – [BYE-IVR-UAS] 206
12.6.2.2. 应答消息 – [BYE-RSP-IVR-UAS] 207
13. 离线消息 208
13.1. 模式 208
13.2. 发送离线消息 209
13.2.1. 请求消息 - [MSG-SendOfflineMessage] 209
13.2.1.1. 消息格式 209
13.2.1.2. 消息体格式 209
13.2.1.3. 消息示例 210
13.2.2. 应答消息 - [MSG-RSP-SendOfflineMessage] 210
13.2.2.1. 消息格式 210
13.2.2.2. 消息示例 211
13.2.2.3. 错误处理 211
13.3. 获取存储转发消息 211
13.3.1. 请求消息 - [SVC-GetOfflineMessage] 211
13.3.1.1. 消息格式 211
13.3.1.2. 消息示例 212
13.3.2. 应答消息 - [SVC-RSP-GetOfflineMessage] 212
13.3.2.1. 消息格式 212
13.3.2.2. 消息示例 212
13.3.2.3. 错误处理 212
13.4. 接收离线消息 213
13.4.1. 接收消息 - [MSG-OfflineMessage] 213
13.4.1.1. 消息格式 213
13.4.1.2. 消息体格式 213
13.4.1.3. 消息示例 214
13.4.2. 应答消息 - [MSG-RSP-OfflineMessage] 214
13.4.2.1. 消息格式 214
13.4.2.2. 消息示例 214
13.4.2.3. 错误处理 215
14. 短信通道 215
14.1. 获取当前手机号 215
14.1.1. 过程描述 215
14.1.2. 发送格式 – [SMS-QueryPhone] 215
14.1.3. 接收格式 – [SMS-RSP-QueryPhone] 215
14.2. 重设密码 216
14.2.1. 过程描述 216
14.2.2. 发送格式 – [SMS-SetPassword] 216
14.2.3. 接收格式 – [SMS-RSP-SetPassword] 216
14.2.4. 错误码 217
14.3. 离线发送消息- [SMS-MESSAGE] 217
14.4. 获取手机号2 217
14.4.1 过程描述 217
14.4.2 发送格式 – [SMS- QueryPhone2] 217
14.4.3 应答格式 – [SMS-RSP-QueryPhone2] 217
14.5注册短信 218
14.5.1描述 218
14.5.2 发送格式 – [SMS-Register2] 218
14.5.3 应答格式 – [SMS-RSP-Register2] 219
15. 数据通道 219
15.1. 获取导航信息 219
15.1.1. 过程描述 219
15.1.2. 发送格式 - [HTTP-GetConfig] 219
15.1.3. 接收格式 – [HTTP-RSP-GetConfig] 220
15.1.4. 错误码 222
15.2. 获取用户URI 222
15.2.1. 过程描述 222
15.2.2. 发送格式 – [HTTP-GetSipUri] 222
15.2.3. 接收格式 – [HTTP-RSP-GetSipUri] 223
15.2.4. 错误码 223
15.3. 头像上传 223
15.3.1. 过程描述 223
15.3.2. 发送格式 – [HTTP-UploadUserPhoto] 224
15.3.3. 接收格式 – [HTTP-RSP-UploadUserPhoto] 224
15.3.4. 发送头像改变通知 224
15.3.5. 错误码 225
15.4. 头像下载 225
15.4.1. 过程描述 225
15.4.2. 发送格式 – [HTTP-DownloadUserPhoto] 225
15.4.3. 接收格式 – [HTTP-RSP-DownloadUserPhoto] 225
15.4.4. 错误码 226
15.5. 共享文件上传 226
15.5.1. 过程描述 226
15.5.2. 发送格式 – [HTTP-UploadFile] 226
15.5.3. 接收格式 – [HTTP-RSP-UploadFile] 227
15.5.4. 错误码 227
15.6. 共享文件下载 227
16. 即时消息格式 228
16.1. 表情图片 228
16.2. 控制标签 229
16.2.1. 功能描述 229
16.2.2. 标签格式 229
16.2.3. 发送者编码 230
16.2.4. 接收者解码 230
16.3. 文件共享 230
16.3.1. 标签名 230
16.3.2. 功能描述 231
16.4. 文本格式 231
17. 全局错误 231
18. 用户统一状态编码 231
附录1 系统状态码 233
附录2 消息格式索引 233
1. 范围
本规范规定了即时消息与状态服务的客户端的接入协议,是提供消息与状态服务的客户端和服务器端设备都要遵从的技术文件。
2. 参考文献
[1] [RFC1321] The MD5 Message-Digest Algorithm
http://www.faqs.org/rfcs/rfc1321.html
[2] [RFC2327] SDP: Session Description Protocol
http://www.faqs.org/rfcs/rfc2327.html
[3] [RFC2396] Uniform Resource Identifiers (URI): Generic Syntax
http://www.faqs.org/rfcs/rfc2396.html
[4] [RFC2616] Hypertext Transfer Protocol -- HTTP/1.1
http://www.faqs.org/rfcs/rfc2616.html
[5] [RFC2617] HTTP Authentication: Basic and Digest Access Authentication
http://www.faqs.org/rfcs/rfc2617.html
[6] [RFC2633] S/MIME Version 3 Message Specification
http://www.faqs.org/rfcs/rfc2633.html
[7] [RFC806] URLs for Telephone Calls
http://www.faqs.org/rfcs/rfc2806.html
[8] [RFC3261] SIP: Session Initiation Protocol
http://www.faqs.org/rfcs/rfc3261.html
[9] [RFC3262] Reliability of Provisional Responses in Session Initiation Protocol (SIP)
http://www.faqs.org/rfcs/rfc3262.html
[10] [RFC3263] Session Initiation Protocol (SIP): Locating SIP Servers
http://www.faqs.org/rfcs/rfc3263.html
[11] [RFC3264] An Offer/Answer Model with Session Description Protocol (SDP)
http://www.faqs.org/rfcs/rfc3264.html
[12] [RFC3265] Session Initiation Protocol (SIP)-Specific Event Notification
http://www.faqs.org/rfcs/rfc3265.html
[13] [RFC3311] The Session Initiation Protocol (SIP) UPDATE Method
http://www.faqs.org/rfcs/rfc3312.html
[14] [RFC3115] The Session Initiation Protocol (SIP) Refer Method
http://www.faqs.org/rfcs/rfc3515.html
[15] [XML] Extensible Markup Language (XML) 1.0
http://www.w3.org/TR/REC-xml/
[16]
[17]
[18]
3. 术语和缩略语
简称 全称 解释
SMS Short Massage Services 短消息服务
HTTP Hypertext Transfer Protocol 超文本传输协议
SIP Session Initiation Protocol 会话初始化协议
SDP Session Description Protocol 会话描述协议
XML Extensible Markup Language 可扩展标记语言
SID System ID Fetion号
URI Universal Resource Identifier 统一资源标志
SIPC Compact SIP 本规范通过对SIP的简化和扩展而定义的协议。
消息 SIP消息 如果特殊说明,本文当中出现的消息表示SIP消息。
事务 发送SIP请求消息,并接受相应应答消息的过程。
会话 围绕一个主题的一系列消息,可能包含多个会话。可由INVITE事务建立,也可以不经由INVITE建立,以相同的Call-ID标志。
4. 系统结构
5. 基础协议
系统基于一些得到广泛支持的协议进行构建,并对一些协议进行了简化和扩展,以便适应移动通讯技术的网络特点,并支持特定的服务。
5.1. SMS
对于移动设备,可以直接使用短信开通和退订服务,修改密码等操作,客户端也需要用这个通道来获取当前设备的一些信息。
5.2. HTTP
系统使用HTTP来与服务器进行部分数据交换。
5.3. SIP
系统使用一个简化和增强的SIP协议:SIP-C(Compact SIP),以适应移动终端设备的接入特点,但SIP及相关协议确立的会话的逻辑过程保持不变。
凡是[RFC3261]要求必须有,但本规范没有要求的消息头,以本规范为准。
本规范有定义的消息头的生成规则以本规范为准。
本规范未定义的消息头的生成规则以[RFC3261]为准。
5.4. SDP
终端使用SDP协议来描述会话类型,建立各种类型的会话,包括文本消息、IVR、群、组。
5.5. XML
系统使用XML作为主要的数据交换格式。
5.6. 加密算法
系统目前规定了一种的摘要算法,用于用户的认证。此认证过程需要客户端至少实现MD5算法。
5.7. 压缩算法
客户端可与服务器之间可以进行协商,使用双方都支持的算法来对信令通道进行压缩。
移动客户端应至少实现LZ77算法。
压缩数据包的格式为:
数据包压缩长度 数据包实际长度 数据流
unsigned short unsigned short char[]
High Byte Low Byte High Byte Low Byte char char … …
6. SIP-C基础
6.1. 概述
消息无需Via、Route、Record-Route头。
只有有必要时,消息才包含To头。
只有消息体存在时,才需要Content-Type和Content-Length头。
客户端发送的请求消息的Call-ID的取值为一个从1开始,顺序增加的正整数。
客户端接受的请求的Call-ID的取值为一个从-1开始,顺序减少的负整数。
如果消息头有多个值,必须分别写多个消息头,SIP-C不使用逗号分割的多个值的表示方式。
SIP-C定义了对方法和消息头的缩写方式,但在以下文档中的说明中,仍旧使用全称,以方便理解。
SIP-C的错误定义与SIP兼容,对于每个操作的特定应答错误码,会在操作的错误处理部分加以说明,其他错误,可参考总体的应答错误处理部分的说明。
6.2. SIP方法的缩写
SIP-C定义了对方法的缩写表示方式,SIP-C消息必须使用定义的缩写。
SIP 方法 SIP-C方法
ACK A
BYE B
BENOTIFY BN
CANCEL C
INVITE I
MESSAGE M
NOTIFY N
NEGOTIATE NEG
REGISTER R
REFER REF
SERVICE S
SUBSCRIBE SUB
6.3. SIP消息头的缩写
SIP-C定义了对消息头的缩写方式,SIP-C消息中的消息头必须使用缩写方式。
SIP消息头 SIP简写方式 SIP-C简写方式
Authorization A
Content-Type C
Content-Encoding E
CSeq Q
From F
Call-ID I
Content-Length L
Contact M
Event N
Expires X
Subject S
Supported K
To T
Via V
WWW-Authenticate W
Roster-Manager RM
EndPoints EP
Refer-To RT
Referred-By RB
Require RQ
Unsupport UK
7. 服务状态改变
7.1. 业务定购
在用户第一次使用此项服务时,需要先进行开通,用户需填写的内容包括:
昵称
性别
出生日期
用户密码
其中昵称和用户密码为必填,其他两项为可选。
7.1.1. 移动设备
7.1.1.1. 过程描述
? 向系统指定的短信网关发送一条注册短信,短信网关回复注册结果。
? 客户端需截获网关返回的短信,解析其中用户SID和URI,用于登录系统。
7.1.1.2. 短信发送格式 - [SMS-Register]
? 必须以英文关键字“Register”开始,不区分大小写,其后紧接一个英文空格。
? 用户的每个用于注册的数据项之间以一个英文“#”为分隔符,数据项之间不能有无意义的空格。如果该项用户未填,用于分割该项的“#”必须保留。
值域 类型 格式/范围 非空
用户密码 VARCHAR(16) ASCII码0x21-0x7E,不包含# 是
性别 CHAR(1) 一个英文字符,
U:未知
M:男
F:女
昵称 NVARCHAR(15) 可见字符,不能包含# 是
保留 此位置保留为空
出生日期 DATETIME 格式为YYYY-MM-DD
例如:
1980-8-12
示例:
密码为123,性别女性,昵称为可人
7.1.1.3. 短信接收格式 - [SMS-RSP-Register]
? 以英文关键字“Register”开始,不区分大小写,其后紧接一个英文空格。
? 每个用于注册数据项之间以一个英文空格为分隔符。
值域 类型 格式/范围 非空
错误码 INT2 数字200表示注册成功
否则为失败。 是
SID INT4 整数的十进制表示 是
手机号 VARCHAR(11) 当前用户的手机号码 是
URI VARCHAR(32) SID@domain的格式 是
如果注册失败,返回格式会有所变化,此时参照一下格式解析:
错误说明
420 用户性别设置错误 442 密码不能为空,或格式错误
443 昵称为空,长度超长或格式错误 481 用户已经开通
7.1.2. 非移动设备
7.2. 业务退订
7.2.1. 短信方式 - [SMS-Unregister]
可直接发送以下短信到指定的短信网关,不区分大小写。
系统会返回表示操作结果的文本消息。
7.2.2. 命令方式
也可登陆成功后利用系统命令退订业务,详细规范请参考第10章相应部分。
8. 登陆状态改变
用户希望使用此系统时,应当首先使用客户端登入此系统。
8.1. 模式
注册过程中所有的REGISTER消息属于同一个会话,使用相同的Call-ID,CSeq递增。
NEGOTIATE作为一个独立的会话,使用独立的Call-ID。
8.2. 请求注册
8.2.1. 注册请求消息 - [REG-1]
8.2.1.1. 消息格式
其中epid-value的格式符合以下规则:
?epid-value为10个字母或数字的混合字符串。
?该字符串包含4个字节长的规定字符串,再加上6个客户端随机生成的字符。
?epid-value中的字母为大小写敏感。
?4个规定字符的规则如下
? WE1C Web客户端
? WA1C Wap客户端
? S31C S40客户端
? S61C S60客户端
? M31C SmartPhone 2003客户端
?后面的6个随机字符建议为HHMMSS格式的当前时间。
8.2.1.2. 示例
8.2.2. 注册应答消息 - [REG-RSP-1]
8.2.2.1. 消息格式
8.2.2.2. 错误处理
如果返回的消息中没有WWW-Authenticate头,说明服务器过忙,客户端应该断开连接,服务器也可能主动断开。
客户端应该间隔一定时间后重试,间隔时间建议为16秒,如果重试超过3次仍未成功,应该将此信息提示给用户,由用来户选择重试,此后用户每次选择重试,客户端设备只重试1次。
8.2.2.3. 示例
8.3. 请求认证
8.3.1. 认证请求消息 - [REG-2]
8.3.1.1. 消息格式
8.3.1.2. 凭据生成算法
key = MD5 (SID + “:” + Domain + “:” + Password)
H1 = MD5ToHex (key + “:” + n-value + “:” + cn-value)
H2 = MD5ToHex (“REGISTER” + “:” + SID)
Response = MD5ToHex (H1 + “:” + n-value + “:” + H2)
MD5 :
表示计算MD5摘要,返回值为16个字节长的二进制数据块。
MD5ToHex :
表示先计算MD5摘要,然后将结果转化为16进制表示的字符串,返回值为32个字节长的字符串。
8.3.1.3. 示例
8.3.2. 认证应答消息 - [REG-RSP-2]
8.3.2.1. 消息格式
Expires头表示了本次注册的有效期,单位为秒,客户端应该在有效期超时前发送[REG-3]消息给服务器,建议客户端提前90-150秒发送[REG-3]保持注册消息。
8.3.2.2. 错误处理
可能返回的错误
400 – 消息格式错误
401 – 认证失败
404 – 用户不存在
认证失败后,重新进行认证时,需要重新发送[REG-1]消息,来获取新的nonce值。
8.3.2.3. 示例
8.4. 协商流压缩
如果希望协商压缩应该在登陆成功后,发送任何其他命令前进行。
注册成功后,如果已发送任何消息,则不得再发送协商命令。
协商成功后,从下一条消息立即开始使用压缩,包括后续的REGISTER消息。
8.4.1. 协商请求 - [NEG-COMPRESS]
8.4.1.1. 消息格式
server-ip:port为TCP连接服务器一端的地址和端口
client-ip:port为TCP连接客户一端的地址和端口
客户端可列上所有支持的算法,位置靠前的优先,每个算法使用一个独立的Event头。
8.4.1.2. 压缩算法
目前定义以下两种算法:
LZ77-8K – LZ77算法,使用8096字节长的字典
LZ77-64K – LZ77算法,使用65536字节长的字典
8.4.1.3. 示例
8.4.2. 协商应答消息 - [NEG-COMPRESS-RSP-2]
8.4.2.1. 消息格式
a-value为服务器选定的算法。
8.4.2.2. 错误处理
如果返回的应答消息中没有Event头出现,说明服务器不支持客户端的压缩算法,或者拒绝使用压缩。此后客户端仍可以选择以非压缩的方式继续与服务器进行通信。
8.4.2.3. 示例
8.5. 保持注册
客户端必须在注册有效期超时之前,发送[REG-3]消息以保持注册状态。
8.5.1. 保持注册请求消息 - [REG-3]
8.5.1.1. 消息格式
[REG-3]消息必须使用与[REG-1]相同的Domain、SID、epid-value、call-id-value。
8.5.1.2. 示例
8.5.2. 保持注册应答消息 - [REG-RSP-3]
8.5.2.1. 消息格式
Expires头表示了本次注册的有效期,客户端应该在有效期超时前发送下一个[REG-3]消息给服务器,建议客户端提前90-150秒发送下一个[REG-3]保持注册消息。
8.5.2.2. 示例
8.6. 注销
8.6.1. 注销请求消息 - [UNREG-1]
8.6.1.1. 消息格式
发送带有值为0的Expires头的REGISTER消息,来从系统中注销登陆。
8.6.1.2. 示例
8.6.2. 注销应答消息 - [UNREG-RSP-1]
8.6.2.1. 消息格式
8.6.2.2. 错误处理
客户端应等待服务器应答消息返回后再退出,至少要等待30秒,如果超时后仍无应答返回,正常退出,无需提示用户。
如果返回的砖状态码不2XX,可忽略错误,正常退出。
8.6.2.3. 示例
8.7. 强制注销通知
在用户已经登陆的情况下,如果此用户从另一个设备再次登陆,或者登陆过程中主动或被动关闭了服务,原来的客户端会收到一个通知,来表明此登陆已被强制注销,此时客户端应该退订已经订阅成功的各种事件,然后提示用户,并退出。
8.7.1. 通知消息 - [NTF-Registration]
8.7.1.1. 消息格式
通知消息有两种方式,NOTIFY方式和BENOTIFY方式,BENOTIFY消息是单向消息,无需返回应答。
NOTIFY方式
BENOTIFY方式
8.7.1.2. 消息体格式
消息体的类型为 :text/registration-event
消息的格式为:
其中event-type可能取以下值:
取值 含义
unregistered 服务器接受了来自次用户的其他登陆
unsubscribed 用户的此项服务已被退订
8.7.1.3. 消息示例
NOTIFY方式
BENOTIFY方式
8.7.2. 应答消息 - [NTF-RSP- Registration]
只对于NOTIFY消息需要返回应答。
8.7.2.1. 消息格式
8.7.2.2. 消息示例
8.7.2.3. 错误处理
对于NOTIFY消息,客户端在正确接收后应该立即返回应答消息,客户端处理中发生的错误不必返回给服务器。
9. 订阅-通知
9.1. 模式
订阅-通知模式用来进行客户端与服务器端数据的同步。
订阅针对一个具体的事件进行。对于不同的事件,需要分别进行订阅。
一个事件一般代表了某种数据的变化。
订阅的应答消息会返回一次完整的数据,此后的变化以通知(NOTIFY / BENOTIFY)的形式发送。
不同的事件应该使用不同的会话,即使用不同的Call-ID。
退出前必须对订阅成功的事件逐项退订。
退订应该在退出前进行,客户端应该等待全部退订应答消息返回后,再发送注销消息[UNREG-1]。
如果应答消息没有全部返回,至少应等待30秒,如果超时后仍无应答,可直接进入注销流程。
9.2. 联系人列表
9.2.1. 订阅联系人列表
联系人列表表示自己的所有联系人的列表。此后当进行增、删联系人操作时,请求消息的应答并不表示实际添加结果,而是应该等待联系人列表的变化通知。
9.2.1.1. 订阅请求 - [SUB-Contacts]
9.2.1.1.1. 消息格式
9.2.1.1.2. 消息示例
9.2.1.2. 订阅应答 - [SUB-RSP-Contacts]
9.2.1.2.1. 消息格式
9.2.1.2.2. 消息体格式
contactList节点可以包含多个group节点
contactList节点可以包含多个contact节点。
contact节点的属性groups的值是以空格分割的多个group节点的id属性的值。
9.2.1.2.3. 消息示例
9.2.1.2.4. 错误处理
9.2.2. 联系人列表通知
当联系人列表成功进行修改后,系统以通知的形式,将修改的类型和内容通知客户端。有以下几种修改形式:
添加组
修改组
删除组
添加联系人
修改联系人分组
删除联系人
9.2.2.1. 通知消息 - [NTF-Contacts]
9.2.2.1.1. 消息格式
通知消息有两种方式,NOTIFY方式和BENOTIFY方式,BENOTIFY消息是单向消息,无需返回应答。
NOTIFY方式
BENOTIFY方式
9.2.2.1.2. 消息体格式
当用户修改了自身的联系人数据后,服务器会异步的将数据变化以通知的形式发送给客户端,消息体类型与[SUB-RSP-Contacts]相同。根节点的名称为contactDelta,其不同的子节点代表了不同的变化类型。下面列出了简表,各节点的详细结构和示例将在对应的修改操作章节中进行介绍。
节点名称 对应操作
addedGroup 添加了一个新组
modifiedGroup 修改了一个组的名字
deleteGroup 删除了一个组
addContact 添加了一个新联系人。
modifiedContact 修改了联系人的分组
deletedContact 删除了一个联系人。
9.2.2.1.3. 消息示例
消息头(NOTIFY方式) :
消息头(BENOTIFY方式) :
添加新组通知消息体:
修改组名通知消息体:
删除组通知消息体:
添加新联系人通知消息体:
修改联系人分组通知消息体:
删除联系人通知消息体:
9.2.2.2. 应答消息 - [NTF-RSP-Contacts]
只对于NOTIFY消息需要返回应答。
9.2.2.2.1. 消息格式
9.2.2.2.2. 消息示例
9.2.2.2.3. 错误处理
对于NOTIFY消息,客户端在正确接收后应该立即返回应答消息,客户端处理中发生的错误不必返回给服务器。
9.2.3. 退订联系人列表
9.2.3.1. 退订请求 - [UNSUB-Contacts]
9.2.3.1.1. 消息格式
9.2.3.1.2. 消息示例
9.2.3.2. 退订应答 - [UNSUB-RSP-Contacts]
9.2.3.2.1. 消息格式
9.2.3.2.2. 消息示例
9.2.3.2.3. 错误处理
9.3. 状态授权信息
9.3.1. 订阅状态授权信息
用户通过订阅自己的在线状态和即时消息授权信息,来使客户端的数据与服务器端的数据保持一致。用户的订阅操作将得到自己当前的全部授权信息,此时可能并非所有的授权对象都在联系人列表中。此后每次进行授权操作后,服务器会将权限信息的变化通知客户端。
9.3.1.1. 订阅请求 - [SUB-ACLs]
9.3.1.1.1. 消息格式
9.3.1.1.2. 消息示例
9.3.1.2. 订阅应答 - [SUB-RSP-ACLs]
9.3.1.2.1. 消息格式
9.3.1.2.2. 消息体格式
ACL = Access Control List
ACE = Access Control Entry
ACLlist节点包含一个userACL节点。
userACL节点可以包含多个ace节点。
User-URI是一个以sip开头的字符串,表示授权对象,格式为:
rights-value为对目标的授权信息,是一个两个字节长的字符串。格式如下:
[subecription-permission] – 决定了授权对象是否有权订阅授权者的在线状态。取值范围和意义如下:
取值 意义 说明
A Allow 允许订阅 允许此人订阅我的状态和变化
B Block 阻挡 不允许此人订阅我的状态
P Prompt 提示 下次登陆时提示,再进行决定
[invite-permission] – 决定了授权对象是否有权邀请授权者以建立会话。取值范围和意义如下:
取值 意义 说明
A Allow 允许 允许此人向授权者发出邀请,以建立会话
D Deny 拒绝 授权者将不接受来自此人的任何邀请
以下的值都是有效的rights-value
9.3.1.2.3. 消息示例
9.3.1.2.4. 错误处理
9.3.2. 授权信息通知
当成功修改或添加一条授权纪录后,系统会以通知的形式再将新的权限记录通知到客户端。
9.3.2.1. 通知消息 - [NTF-ACLs]
9.3.2.1.1. 消息格式
通知消息有两种方式,NOTIFY方式和BENOTIFY方式,BENOTIFY消息是单向消息,无需返回应答。
NOTIFY方式
BENOTIFY方式
9.3.2.1.2. 消息体格式
当用户添加或修改一条权限记录后,服务器会异步的将数据变化以通知的形式发送给客户端,消息体类型与[SUB-RSP-ACLs]相同。根节点的名称为ACLdelta,包含一个子节点userACL。userACL包含一个子节点modifiedACE,指明了授权的目标和新设置的权限。
属性mask和rights的含义请参考前一节。
9.3.2.1.3. 消息示例
NOTIFY方式
BENOTIFY方式
9.3.2.2. 应答消息 - [NTF-RSP-ACLs]
只对于NOTIFY消息需要返回应答。
9.3.2.2.1. 消息格式
9.3.2.2.2. 消息示例
9.3.2.2.3. 错误处理
对于NOTIFY消息,客户端在正确接收后应该立即返回应答消息,客户端处理中发生的错误不必返回给服务器。
9.3.3. 退订授权信息
9.3.3.1. 退订请求 - [UNSUB-ACLs]
9.3.3.1.1. 消息格式
9.3.3.1.2. 消息示例
9.3.3.2. 退订应答 - [UNSUB-RSP-ACLs]
9.3.3.2.1. 消息格式
9.3.3.2.2. 消息示例
9.3.3.2.3. 错误处理
9.4. 状态订阅申请
当一个用户尝试订阅另一个用户的状态时,如果被订阅的一方没有对订阅者的授权,此时需要通知被订阅方对此进行处理,此类通知称为状态订阅申请通知。用户登陆后,应该主动订阅这个事件,以便于随时处理状态订阅申请。
9.4.1. 订阅状态订阅申请
9.4.1.1. 订阅消息 - [SUB-WPending]
9.4.1.1.1. 消息格式
9.4.1.1.2. 消息示例
9.4.1.2. 应答消息 - [SUB-RSP-WPending]
9.4.1.2.1. 消息格式
9.4.1.2.2. 消息体格式
pendingWatchers节点包含0个或多个watcher节点。
watcher节点的uri属性指明了状态订阅的申请者。
user-URI和watcher-URI是一个以sip开头的字符串,格式为:
9.4.1.2.3. 消息示例
9.4.1.2.4. 错误处理
9.4.2. 订阅申请通知
当有一个从未被授权的订阅者试图订阅被订阅者的状态时,如果此时被订阅者在线,系统会向被订阅者发送订阅申请通知。通知消息的消息体的结构与前面一节的订阅结果中的结构一样。
9.4.2.1. 通知消息 - [NTF-WPending]
9.4.2.1.1. 消息格式
通知消息有两种方式,NOTIFY方式和BENOTIFY方式,BENOTIFY消息是单向消息,无需返回应答。
NOTIFY方式
BENOTIFY方式
9.4.2.1.2. 消息体格式
消息体的格式和含义与前面[SUB-RSP-WPending]的消息体完全相同。
9.4.2.1.3. 消息示例
NOTIFY方式
BENOTIFY方式
9.4.2.2. 应答消息 - [NTF-RSP-WPending]
只对于NOTIFY消息需要返回应答。
9.4.2.2.1. 消息格式
9.4.2.2.2. 消息示例
9.4.2.2.3. 错误处理
对于NOTIFY消息,客户端在正确接收后应该立即返回应答消息,客户端处理中发生的错误不必返回给服务器。
9.4.3. 退订状态订阅申请
9.4.3.1. 退订请求 - [UNSUB-WPending]
9.4.3.1.1. 消息格式
9.4.3.1.2. 消息示例
9.4.3.2. 退订应答 - [UNSUB-RSP-WPending]
9.4.3.2.1. 消息格式
9.4.3.2.2. 消息示例
9.4.3.2.3. 错误处理
9.5. 联系人状态
用户登陆成功后可以订阅好友的在线状态。订阅成功并不意味着一定能看到对方的状态,因为被订阅的一方可以选择对特定的订阅方隐藏自己状态。此时订阅方只能看到被订阅方离线,无论此时被订阅方是否真正离线。
订阅状态分为两种方式:批量方式和单个方式。
因为系统可能会化分为多个管理域,至少对于订阅与订阅者在同一个管理域的联系人应该支持批量订阅方式。对于位于不同的管理域中的联系人,要逐个订阅状态。
客户端可以先假设所有用户都位于同一个管理域中,来执行批量订阅,然后再根据每个联系人的订阅结果来决定是否要再进行单个订阅。
单个订阅的方式还可用于订阅新添加的联系人的状态。
9.5.1. 批量订阅联系人状态
9.5.1.1. 订阅请求 - [SUB-Presence-1]
9.5.1.1.1. 消息格式
9.5.1.1.2. 消息体格式 – 批量订阅
adhoclist节点下包含一个子节点create。
create可以包含一个或多个resource子节点。
user-URI为订阅者自己的URI,target-URI为希望订阅状态的目标的URI。
user-URI和target-URI的格式如下:
9.5.1.1.3. 消息体格式 – 增加订阅
adhoclist节点下包含一个子节点add。
add可以包含一个或多个resource子节点。
user-URI为订阅者自己的URI,target-URI为希望添加到状态订阅列表中的目标的URI。
user-URI和target-URI的格式如下:
9.5.1.1.4. 消息体格式 – 删除订阅
adhoclist节点下包含一个子节点delete。
delete可以包含一个或多个resource子节点。
user-URI为订阅者自己的URI,target-URI为希望从状态订阅列表中删除的目标的URI。
user-URI和target-URI的格式如下:
9.5.1.1.5. 消息示例
9.5.1.2. 订阅应答 - [SUB-RSP-Presence-1]
9.5.1.2.1. 消息格式
9.5.1.2.2. 消息体格式
presenceList节点可以包含多个resource节点。
resource节点可以包含activity、nickname、impresa、photo、deivce节点各一个。如果对象不在线,则不包含任何子节点。相当于:
user-URI为标志此资源的URI,为以下格式:
resource-state为此资源的订阅状态,可能为以下值:
值 含义 实现建议
active 资源有效 在订阅操作中表示订阅成功
resubscribe 需要重新订阅 需要对此资源的在线状态进行单独的订阅
(未指定) 等于active
activity-value为此资源显示状态,取值和含义参考下表。
值 描述 含义
600 Busy 忙碌
500 In Call 接听电话
400 Active 在线
300 Be Right Back 马上回来
150 At Lunch 外出就餐
100 Away 离开
0 offline 离线
当用户使用了自定义的状态时,active-description为此自定义状态的描述,否则为空。
nickname节点仅用于昵称修改的通知,在此应答消息不会出现。
impresa节点仅用于心情短语修改的通知,在此应答消息中不会出现。
photo节点仅用于头像修改的通知,在此应答消息中不会出现。
epid(EndPoint ID)为此联系人此次登陆的终端编号。
9.5.1.2.3. 消息示例
其中1000在线,2000离线,3000需要独立订阅状态。
9.5.1.2.4. 错误处理
9.5.2. 单个订阅联系人状态
此订阅请求的发送目标为状态订阅目标。
9.5.2.1. 订阅请求 - [SUB-Presence-2]
9.5.2.1.1. 消息格式
其中target-URI的格式为:
9.5.2.1.2. 消息示例
9.5.2.2. 订阅应答 - [SUB-RSP-Presence-2]
9.5.2.2.1. 消息格式
9.5.2.2.2. 消息体格式
消2体格式与[UNSUB-RSP-Presence]相同。
9.5.2.2.3. 消息示例
9.5.2.2.4. 错误处理
9.5.3. 联系人状态变化通知
如果订阅成功并有足够的权限,此后当被订阅的一方的状态信息发生变化时,就会通知订阅方。
9.5.3.1. 通知消息 - [NTF-Presence]
9.5.3.1.1. 消息格式
通知消息有两种方式,NOTIFY方式和BENOTIFY方式,BENOTIFY消息是单向消息,无需返回应答。
NOTIFY方式
BENOTIFY方式
9.5.3.1.2. 消息体格式
消息体的格式和含义与前面[SUB-RSP-Presence-2]的消息体完全相同。不同的是:
如果此时包含节点nickname,代表着昵称进行了修改,而且nickname-value为新的昵称。
如果此时包含节点impresa,代表着心情短语进行了修改,而且impresa-value为新的心情短语。
如果此时包含节点photo,代表着头像进行了修改,而且crc-value为新头像的校验和,url-value为获取新头像的位置。
9.5.3.1.3. 消息示例
NOTIFY方式
BENOTIFY方式
9.5.3.2. 应答消息 - [NTF-RSP-Presence]
只对于NOTIFY消息需要返回应答。
9.5.3.2.1. 消息格式
9.5.3.2.2. 消息示例
9.5.3.2.3. 错误处理
对于NOTIFY消息,客户端在正确接收后应该立即返回应答消息,客户端处理中发生的错误不必返回给服务器。
9.5.3.3. 错误处理
9.5.4. 批量退订联系人状态
9.5.4.1. 退订请求 - [UNSUB-Presence-1]
9.5.4.1.1. 消息格式
9.5.4.1.2. 消息示例
9.5.4.2. 退订应答 - [UNSUB-RSP-Presence-1]
9.5.4.2.1. 消息格式
9.5.4.2.2. 消息示例
9.5.4.2.3. 错误处理
9.5.5. 单个退订联系人状态
9.5.5.1. 退订请求 - [UNSUB-Presence-2]
9.5.5.1.1. 消息格式
9.5.5.1.2. 消息示例
9.5.5.2. 退订应答 - [UNSUB-RSP-Presence-2]
9.5.5.2.1. 消息格式
9.5.5.2.2. 消息示例
9.5.5.2.3. 错误处理
10. 系统服务
10.1. 模式
如果操作的目标是本人的联系人列表或授权信息,那么操作的应答消息仅表示服务器接受了这个命令,并会尝试执行。客户端只有收到对应的NOTIFY后才表示操作成功。
对除了联系人列表和权限之外的其他操作,200 OK的返回表示操作成功。没有后续的NOTIFY消息。
当SERVICE消息的Content-Type头的值为application/xml时,可以省略这个消息头。
10.2. 获取用户信息
10.2.1. 请求消息 - [SVC-GetUserConfig]
10.2.1.1. 消息格式
target-URI为可选择消息头,当查询个人的配置时,不需要这个消息头。
当查询某个联系人的信息时,需要用这个头来指定联系人的URI,格式如下:
10.2.1.2. 消息体格式
格式说明:
节点名称 功能 格式 非空
User 待获取的用户。此节点只能有一个。 是
DetailFlag 请求的附加参数。不同的数字,将导致返回不同细节的数据。被获取的用户必须时已注册的用户。值定义:
0:不返回任何资料。
1:用于获取好友最少资料。
3:用于获取一个好友的详细信息。
5:用于获取自己的个人资料及好友列表 Int 是
Sid 用户的系统标识。 Int 见注
CellPhone 手机号码。 Varchar(11) 见注
注:Sid, CellPhone二者有且仅有一个为非空。
10.2.1.3. 消息示例
10.2.2. 应答消息 - [SVC-RSP-GetUserConfig]
10.2.2.1. 消息格式
10.2.2.2. 消息体格式(DeailFlag=5)
格式说明:
节点名称 功能 格式 非空
Group 定义一个组的组信息。可能有多个此节点,用以定义多个组。
包括属性:
id:组的数字ID
name:组的英文或中文名称
flag:组的数字标志。1:系统组;3:不可见的系统组;5:大头像组;32:用户自定义的组
User 定义用户数据
User/@flag 用户属性(可能不存在或为空)。
1、该值与512位与操作等于512时,表明该用户具有开通“语音聊天服务”的能力(即程序应检查flag&512=512)
Uri 登录LC服务器的帐户 Varchar(100) 是
Sid 用户的系统标识 Int 是
Domain 用户所属的域 Varchar(30) 是
CellPhone 用户手机号码
(但好友的手机号码可以为空) Varchar(11) 是
AmigoToken 用户登录后,LC服务器(Amigo应用)为其生成的验证票据 Varchar(32) 是
NickName 昵称 NVarchar(15)
Nickname/@p Int
Gender 性别(U:未知,M:男,F:女) Char(1)
Impresa 用于扩展昵称的心情短语 NVarchar(100)
Status 用户状态。6位数字组成的字符串: Char(6)
Email 用户的电子邮件地址 Varchar(50)
BirthDate 用户的出生日期
Province 用户所在省的2位数字区号 Char(2)
City 用户所在城市4位数字区号 Char(4)
Abbr 用户的英文或拼音缩写(用于快速定位用户) Varchar(10)
Device 用户当前登录所使用的设备名称,此节点可能有多个,以表明用户可能在以多个设备进行登录。定义见错误!未找到引用源。节
Varchar(10)
PhotoCRC 用户大头像的文件CRC校验和数据,并将二进制字节转换成16进制字符串的结果。如:0E1AC9F8 Varchar(32)
FriendMatching 值为“1”表示开通了Fetion交友, 为“0”表示未开通。
BuddyList 定义好友的集合,即好友列表。
contact属性:当前用户好友列表的版本号(Int类型)
permission属性:当前用户被添加列表的版本号(Int类型)
Buddy 定义一个好友,此节点可能有多个,以标识多个好友。其子节点含义与User节点的子节点含义相同。
Buddy下的节点,除Sid及Uri外,其它节点都可能为空。
Buddy/@group 好友所属的组编号。如该好友同时属于多个组,则组编号以英文空格分开。如:“1 2 5”。
Buddy/@right 好友对用户的访问权限,两位字母,与LC服务器的好友访问用户的权限的定义相同。如“AA”或“BD”,A代表Access,D代表Deny
Buddy/@flag 好友属性(可能不存在或为空)。
1、该值与2位与操作等于2时,表明该好友为“聊友”(即程序应检查flag&2=2)
2、该值与16位与操作等于16时,表明该好友为“已经注销”(即程序应检查flag&16=16)
3、该值与256位与操作等于256时, 表明该NickName为当前用户所重设的。否则表明该好友的Nickname未被本人重设,NickName节点的值为该好友的真实昵称。
4、该值与512位与操作等于512时,表明该好友为“开通语音聊天服务”(即程序应检查flag&512=512)
10.2.2.3. 消息体格式(DeailFlag=3)
格式说明:
节点名称 功能 格式 非空
BloodType 用户血型,数字含义
1: A型血,2: B型血,3:AB型,4:O型 Int
NickName 该昵称为好友的真实昵称,而并非用户对该好友重设的昵称 NVARCHAR(15)
Address 用户住址 NVARCHAR(100)
Memo 好友的个人简介 NVARCHAR(100)
其余节点定义见10.2.2.2节
注意:如果查询的不是自己的资料,则没有“FriendMatching”节点。
10.2.2.4. 消息体格式(DeailFlag=1)
节点定义见10.2.2.2节。
10.2.2.5. 消息示例
10.2.2.6. 错误处理
GetUserConfig的特定错误
451 DetailFlag不支持 452 未指定有效的用户信息
10.3. 添加联系人
10.3.1. 请求消息 - [SVC-AddContact]
10.3.1.1. 消息格式
delta-number-value为当前联系人信息的版本号。操作必须给出正确的版本号,否则操作将直接失败。
contact-URI为要添加的联系人的URI,格式如下:
10.3.1.2. 消息示例
10.3.2. 应答消息 - [SVC-RSP-AddContact]
10.3.2.1. 消息格式
10.3.2.2. 消息示例
10.3.2.3. 错误处理
因为每个联系人列表和组的操作都需要当前的联系人信息版本号(delta-number-value),所以不能同时进行多个相关这些数据的操作。如果前一个操作返回200 OK,下一个操作需要等待相应的NOTIFY消息回来,以获得下一个有效的版本号
如果使用了错误的联系人信息版本号,服务器会返回 409 Conflict应答,说明此时客户端的联系人信息与服务器端不一致,此时建议客户端,重新订阅联系人信息,先取消上一次订阅,再使用一个新的会话(新的Call-ID)重新订阅。
10.3.3. 通知消息 - [NTF-AddContact]
通知消息和相应的应答消息的详细结构,请参考[NTF-Contacts],本节只介绍对应添加联系人操作的通知消息的体结构。
10.3.3.1. 消息体格式
current-contact-delta-number为操作完成后的联系人版本号。
previous-contact-delta-number为操作前的版本号。
new-contact-URI为新添加的联系人的URI,格式为:
10.3.3.2. 消息体示例
10.4. 修改联系人分组
10.4.1. 请求消息 - [SVC-SetGroups]
10.4.1.1. 消息格式
delta-number-value为当前联系人信息的版本号。操作必须给出正确的版本号,否则操作将直接失败。
contact-URI为要添加的联系人的URI,格式如下:
owner-groups为用户所在的0个或多个组的编号,以空格分割。
10.4.1.2. 消息示例
10.4.2. 应答消息 - [SVC-RSP- SetGroups]
10.4.2.1. 消息格式
10.4.2.2. 消息示例
10.4.2.3. 错误处理
因为每个联系人列表和组的操作都需要当前的联系人信息版本号(delta-number-value),所以不能同时进行多个相关这些数据的操作。如果前一个操作返回200 OK,下一个操作需要等待相应的NOTIFY消息回来,以获得下一个有效的版本号
如果使用了错误的联系人信息版本号,服务器会返回 409 Conflict应答,说明此时客户端的联系人信息与服务器端不一致,此时建议客户端,重新订阅联系人信息,先取消上一次订阅,再使用一个新的会话(新的Call-ID)重新订阅。
10.4.3. 通知消息 - [NTF- SetGroups]
通知消息和相应的应答消息的详细结构,请参考[NTF-Contacts],本节只介绍对应添加联系人操作的通知消息的体结构。
10.4.3.1. 消息体格式
current-contact-delta-number为操作完成后的联系人版本号。
previous-contact-delta-number为操作前的版本号。
modified-contact-URI为被修改的联系人的URI,格式为:
owner-groups为用户所在的0个或多个组的编号,以空格分割。
10.4.3.2. 消息体示例
10.5. 状态订阅授权
10.5.1. 请求消息 - [SVC-SetACE]
10.5.1.1. 消息格式
delta-number-value为当前权限信息的版本号。操作必须给出正确的版本号,否则操作将直接失败。
contact-URI为要授权的联系人的URI,格式如下:
rights-value的取值请参考[SUB-RSP-ACLs]部分。
10.5.1.2. 消息示例
10.5.2. 应答消息 - [SVC-RSP- SetACE]
10.5.2.1. 消息格式
10.5.2.2. 消息示例
10.5.2.3. 错误处理
因为每个授权操作都需要当前的权限信息版本号(delta-number-value),所以不能同时进行多个相关权限的操作。如果前一个操作返回200 OK,下一个操作需要等待相应的NOTIFY消息回来,以获得下一个有效的权限版本号。
如果使用了错误的版本号,服务器会返回 409 Conflict应答,说明此时客户端的授权信息与服务器端不一致,此时建议客户端,重新订阅授权信息,先取消上一次订阅,再使用一个新的会话(新的Call-ID)重新订阅。
10.5.3. 通知消息 - [NTF-SetACE]
通知消息和相应的应答消息的详细结构,请参考[NTF-ACLs]。
10.6. 删除联系人
10.6.1. 请求消息 - [SVC-DeleteContact]
10.6.1.1. 消息格式
delta-number-value为当前联系人信息的版本号。操作必须给出正确的版本号,否则操作将直接失败。
contact-URI为要删除的联系人的URI,格式如下:
10.6.1.2. 消息示例
10.6.2. 应答消息 - [SVC-RSP-DeleteContact]
10.6.2.1. 消息格式
10.6.2.2. 消息示例
10.6.2.3. 错误处理
因为每个联系人列表和组的操作都需要当前的联系人信息版本号(delta-number-value),所以不能同时进行多个相关这些数据的操作。如果前一个操作返回200 OK,下一个操作需要等待相应的NOTIFY消息回来,以获得下一个有效的版本号
如果使用了错误的联系人信息版本号,服务器会返回 409 Conflict应答,说明此时客户端的联系人信息与服务器端不一致,此时建议客户端,重新订阅联系人信息,先取消上一次订阅,再使用一个新的会话(新的Call-ID)重新订阅。
10.6.3. 通知消息 - [NTF-DeleteContact]
通知消息和相应的应答消息的详细结构,请参考[NTF-Contacts],本节只介绍对应添加联系人操作的通知消息的体结构。
10.6.3.1. 消息体格式
current-contact-delta-number为操作完成后的联系人版本号。
previous-contact-delta-number为操作前的版本号。
deleted-contact-URI为新添加的联系人的URI,格式为:
10.6.3.2. 消息体示例
10.7. 添加联系人组
10.7.1. 请求消息 - [SVC-AddGroup]
10.7.1.1. 消息格式
delta-number-value为当前联系人信息的版本号。操作必须给出正确的版本号,否则操作将直接失败。
group-name为要添加的组的名字。
10.7.1.2. 消息示例
10.7.2. 应答消息 - [SVC-RSP- AddGroup]
10.7.2.1. 消息格式
10.7.2.2. 消息示例
10.7.2.3. 错误处理
因为每个联系人列表和组的操作都需要当前的联系人信息版本号(delta-number-value),所以不能同时进行多个相关这些数据的操作。如果前一个操作返回200 OK,下一个操作需要等待相应的NOTIFY消息回来,以获得下一个有效的版本号
如果使用了错误的联系人信息版本号,服务器会返回 409 Conflict应答,说明此时客户端的联系人信息与服务器端不一致,此时建议客户端,重新订阅联系人信息,先取消上一次订阅,再使用一个新的会话(新的Call-ID)重新订阅。
如果组名本身存在问题(比如:长度超常,或和已存在的组同名等),那么服务器返回错误485 Ambiguous。
10.7.3. 通知消息 - [NTF- AddGroup]
通知消息和相应的应答消息的详细结构,请参考[NTF-Contacts],本节只介绍对应添加联系人操作的通知消息的体结构。
10.7.3.1. 消息体格式
current-contact-delta-number为操作完成后的联系人版本号。
previous-contact-delta-number为操作前的版本号。
new-group-id为新添加的组的整数编号。
new-group-name为新添加的组的名字。
10.7.3.2. 消息体示例
10.8. 修改联系人组
10.8.1. 请求消息 - [SVC-ModifyGroup]
10.8.1.1. 消息格式
delta-number-value为当前联系人信息的版本号。操作必须给出正确的版本号,否则操作将直接失败。
group-id为要修改的组的编号。
new-group-name为组的新名字。
10.8.1.2. 消息示例
10.8.2. 应答消息 - [SVC-RSP-ModifyGroup]
10.8.2.1. 消息格式
10.8.2.2. 消息示例
10.8.2.3. 错误处理
因为每个联系人列表和组的操作都需要当前的联系人信息版本号(delta-number-value),所以不能同时进行多个相关这些数据的操作。如果前一个操作返回200 OK,下一个操作需要等待相应的NOTIFY消息回来,以获得下一个有效的版本号
如果使用了错误的联系人信息版本号,服务器会返回 409 Conflict应答,说明此时客户端的联系人信息与服务器端不一致,此时建议客户端,重新订阅联系人信息,先取消上一次订阅,再使用一个新的会话(新的Call-ID)重新订阅。
如果组名本身存在问题(比如:长度超常,或和已存在的组同名等),那么服务器返回错误485 Ambiguous。
10.8.3. 通知消息 - [NTF-ModifyGroup]
通知消息和相应的应答消息的详细结构,请参考[NTF-Contacts],本节只介绍对应添加联系人操作的通知消息的体结构。
10.8.3.1. 消息体格式
current-contact-delta-number为操作完成后的联系人版本号。
previous-contact-delta-number为操作前的版本号。
modified-group-id为被修改的组的编号。
modified-group-name为修改后的组名。
10.8.3.2. 消息体示例
10.9. 删除联系人组
10.9.1. 请求消息 - [SVC-DeleteGroup]
10.9.1.1. 消息格式
delta-number-value为当前联系人信息的版本号。操作必须给出正确的版本号,否则操作将直接失败。
group-id为要删除的组的编号。
10.9.1.2. 消息示例
10.9.2. 应答消息 - [SVC-RSP- DeleteGroup]
10.9.2.1. 消息格式
10.9.2.2. 消息示例
10.9.2.3. 错误处理
因为每个联系人列表和组的操作都需要当前的联系人信息版本号(delta-number-value),所以不能同时进行多个相关这些数据的操作。如果前一个操作返回200 OK,下一个操作需要等待相应的NOTIFY消息回来,以获得下一个有效的版本号
如果使用了错误的联系人信息版本号,服务器会返回 409 Conflict应答,说明此时客户端的联系人信息与服务器端不一致,此时建议客户端,重新订阅联系人信息,先取消上一次订阅,再使用一个新的会话(新的Call-ID)重新订阅。
10.9.3. 通知消息 - [NTF-DeleteGroup]
通知消息和相应的应答消息的详细结构,请参考[NTF-Contacts],本节只介绍对应添加联系人操作的通知消息的体结构。
10.9.3.1. 消息体格式
current-contact-delta-number为操作完成后的联系人版本号。
previous-contact-delta-number为操作前的版本号。
deleted-group-id为已被删除的组的编号。
10.9.3.2. 消息示例
10.10. 设置显示状态
10.10.1. 请求消息 - [SVC-SetPresence]
10.10.1.1. 消息格式
10.10.1.2. 消息体格式
active-value、activity-description的取值参考消息[SUB-RSP-Presence-1]的消息体部分的说明。
activity节点为必须有的节点。
nickname节点为可选节点,表示当前用户修改了自己的昵称,并希望将这个变化通知自己状态的订阅者。
impresa节点为可选节点,表示当前用户修改了自己的心情短语,并希望将这个变化通知自己状态的订阅者。
photo节点为可选节点,表示当前用户修改了自己的头像,并希望将这个变化通知自己状态的订阅者。
10.10.1.3. 消息示例
10.10.2. 应答消息 - [SVC-RSP- SetPresence]
10.10.2.1. 消息格式
10.10.2.2. 消息示例
10.10.2.3. 错误处理
10.10.3. 通知消息 - [NTF-Presence]
修改成功后,有权订阅此用户状态的其他用户将收到状态变化通知。此消息的详细结构已在联系人状态部分进行了描述。
10.11. 修改个人资料
10.11.1. 请求消息 - [SVC-UpdateUserConfig]
10.11.1.1. 消息格式
10.11.1.2. 消息体格式
说明:
节点名称 功能 格式 非空
User 定义用户数据
NickName 自己昵称或者对好友的命名
set属性:用于清空NickName。当NickName节点的值为空时,如果set属性为“1”,则清空NickName,否则将忽略NickName节点。 NVarchar(15)
Impresa 用于扩展昵称的心情短语
set属性见NickName中的set属性描述 NVarchar(100)
Password 用户登录LC服务器的旧密码 Varchar(16)
NewPassword 修改后的新密码 Varchar(16) 同上
Buddy 定义一个好友,此节点可能有多个,以标识多个好友。
Sid 用户的系统标识 Int 是
注:仅仅当NewPassword节点不为空时,同时需要Password不为空。否则Password节点可以为空。
10.11.1.3. 消息示例
10.11.2. 应答消息 - [SVC-RSP- SetPresence]
10.11.2.1. 消息格式
10.11.2.2. 消息示例
10.11.2.3. 错误处理
10.11.3. 发送改变通知
在成功修改了自己的昵称或心情短语之后,如果希望自己状态的订阅者能够立即看到变化,应该通过更新自己的状态来发送通知,细节请参考[SVC-SetPresence]。
10.12. 获取手机状态
10.12.1. 请求消息 - [SVC-GetMobileInfo]
10.12.1.1. 消息格式
其中target-URI为查询目标的URI,格式如下:
10.12.1.2. 消息体格式
detail-flag-value为整数的查询结果详细级别,其中3表示获取开关机状态信息与手机位置信息。
其中target-SID-value为查询目标的SID。
10.12.1.3. 消息示例
10.12.2. 应答消息 - [SVC-RSP-GetMobileInfo]
10.12.2.1. 消息格式
10.12.2.2. 消息体格式
其中target-SID-value为查询目标的SID。
status-value为六个字符长的用户的状态标值位,解析规则可参考[16 用户统一状态编码] 一节。
location-description为不超过128个字符的用户位置的描述信息。
10.12.2.3. 消息示例
10.12.2.4. 错误处理
10.13. 随机速配
10.13.1. 请求消息 - [SVC-RandomQueryUser]
10.13.1.1. 消息格式
10.13.1.2. 消息体格式
query-flag-value指定返回数据的细节级别,为一个整数,目前固定设为5。
page-size-value指定每页返回的结果数量,如果超过了系统允许的最大数量,以系统的最大数量为准。。
10.13.1.3. 消息示例
10.13.2. 应答消息 - [SVC-RSP- RandomQueryUser]
10.13.2.1. 消息格式
10.13.2.2. 消息体格式
其中节点的值为被速配到的人的年龄。其他节点的意义与[SVC-GetUserConfig]的返回结果中的同名节点相同。
10.13.2.3. 消息示例
10.13.2.4. 错误处理
10.14. 条件速配
10.14.1. 请求消息 - [SVC-QueryUser]
10.14.1.1. 消息格式
10.14.1.2. 消息体格式
说明:
节点名称 功能 格式 非空
QueryUserFlag 定义查询所需返回的细节。应设置为“5”。
Int 是
注:以下条件皆可为空,为空时则忽略该条件
Sid 用户的系统标识 Int
CellPhone 用户手机号码 Varchar(11)
NickName 昵称 NVarchar(15)
Gender 性别(U:未知,M:男,F:女)。 Char(1)
Status 用户状态。6位数字组成的字符串。
目前仅仅支持“110000”或“为空”。“110000”时查询在线用户。 Char(6)
Province 用户所在省的2位数字区号 Char(2)
City 用户所在城市4位数字区号 Char(4)
MinAge 最小年龄 Int
MaxAge 最大年龄 Int
Email 用户的电子邮件地址 Varchar(50)
LastSid 数据进行分页时,用于标识分页的起始Sid,即当前分页数据中的所有用户的Sid都大于(非大于等于)该Sid。如果该参数为空,一般表示当前页为第一页。 Int
PageSize 每页的结果数。(下标为1)(此值的上限将受到服务器限制,即可能指定此值为30,但是服务器可能每页仅返回25条记录) Int
10.14.1.3. 消息示例
10.14.2. 应答消息 - [SVC-RSP-QueryUser]
10.14.2.1. 消息格式
10.14.2.2. 消息体格式
其中节点的值为被速配到的人的年龄。其他节点的意义与[SVC-GetUserConfig]的返回结果中的同名节点相同。
10.14.2.3. 消息示例
10.14.2.4. 错误处理
10.15. 系统消息
10.15.1. 接收消息 - [MSG-SystemMessage]
10.15.1.1. 消息格式
当消息类型为text/plain时,此时消息头Content-Type可以省略。
10.15.1.2. 消息体格式
消息体格式的解析,可参考[即时消息格式]部分。
10.15.1.3. 消息示例
10.15.2. 应答消息 - [MSG-RSP-SystemMessage]
10.15.2.1. 消息格式
10.15.2.2. 消息示例
10.15.2.3. 错误处理
通知消息是系统为了提示用户而发送的消息,客户端只需要以恰当的方式显示给用户,无需做出任何特殊反应。
10.16. 退定服务
10.16.1. 请求消息 - [SVC-CloseService]
10.16.1.1. 消息格式
10.16.1.2. 消息体格式
节点名称 功能 格式 非空
EndDate 即将停止服务的日期。如此值为:”2005-9-30 15:30:9”,表示当到达该时间后,用户的全部通讯服务将停止。如果此值为空,表示立刻停止服务。 DateTime
10.16.1.3. 消息示例
10.16.2. 应答消息 - [SVC-RSP-CloseService]
10.16.2.1. 消息格式
10.16.2.2. 消息体格式
节点名称 功能 格式 非空
EndDate 如果ErrorCode为0,则此值表示服务将停止的日期。如“2005-9-30 23:59:59”。如果ErrorCode不为0,此值为空。 DateTime
10.16.2.3. 消息示例
10.16.2.4. 错误处理
10.17. Fetion交友服务
10.17.1开通Fetion交友服务 – [SVC-RegisterFriendMatching]
10.17.1.1 消息格式
10.17.1.2 消息体格式
10.17.1.3 消息示例
10.17.2应答消息 – [SVC-RSP-RegisterFriendMatching]
10.17.2.1 消息格式
10.17.2.2 消息体格式
节点名称 功能 格式 非空
Error 200表示开通成功.
452用户尚未开通FETION
453用户已经开通Fetion交友
500 服务器错误:
Memo 提示信息.成功或出错时的提示信息
10.17.2.3 消息示例
10.17.3 关闭Fetion交友服务 – [SVC-UnregisterFriendMatching]
10.17.3.1 消息格式
10.17.2.2 消息体格式
10.17.2.3 消息示例
10.17.4 应答消息 - [SVC-RSP-UnregisterFriendMatching]
10.17.4.1 消息格式
10.17.4.2 消息体格式
节点名称 功能 格式 非空
Error 200 表示关闭成功.
452 用户尚未开通Fetion交友
500 服务器错误
10.17.4.3 消息示例
S femoo.amigo.bjmcc.net SIP-C/1.0
F: 560006831
N: GetPrivacy
I: 3
Q: 3 S
SIP-C/1.0 200 OK
I: 3
Q: 3 S
L: 204
033SIP-C/1.0 200 OK
I: 3
Q: 4 S
10.18. 获取权限信息
10.18.1 请求消息 - [SVC-GetPrivacy]
10.18.1.1 消息格式
10.18.1.2 消息示例
10.18.2 应答消息 - [SVC-RSP-GetPrivacy]
10.18.2.1 消息格式
10.18.2.2 消息体格式
10.18.2.3 消息示例
10.19. 设置权限消息
10.19.1请求消息 - [SVC-SetPrivacy]
10.19.1.1消息格式
10.19.1.2 消息体格式
10.19.1.3 消息示例
10.19.2 应答消息 - [SVC-RSP- SetPrivacy]
10.19.2.1 消息格式
10.19.2.2 消息示例
11. 即时消息
11.1. 模式
11.1.1. 双方邀请
双方邀请过程(INVITE Transaction)发生在几个场景下:
1.会话管理者建立会话。
2.会话管理者邀请新的参与者。
2.会话的后参与者邀请除会话管理者之外的先前参与者。
Call-ID的值标志了不同的会话,一个会话中所有消息应该共享同一个Call-ID。
对于同一个会话中的不同的目标,CSeq的值应当分别从1开始进行计数。除了[ACK]和[CANCEL]消息外,每一条消息的CSeq的值应该比前一条消息增加1。
对于[ACK]和[INVITE]消息,CSeq的数值部分应当与要取消或确认的[INVITE]消息相同。
11.1.2. 取消邀请
邀请的发出方可以选择发送CANCEL消息来取消本次邀请,如果在CANCEL消息的应答之前收到了INVITE的2XX类应答,则无论此后CANCEL消息的应答是什么,都应该发送ACK和BYE请求以结束会话。
11.1.3. 发送与接收
会话建立后,当用户发送消息时,应该向除自己以外的参与者逐个发送此消息。
11.1.4. 退出会话
当客户端决定结束一个会话时,应该向除自己以外的参与者逐个发送结束会话请求[BYE]。
11.2. 邀请过程
11.2.1. UAC
11.2.1.1. 请求消息 – [INVITE-IM-UAC]
11.2.1.1.1. 消息格式
Roster-Manager为会话管理者的URI,target-uri为邀请目标的URI,格式如下:
EndPoints为逗号分割的会话参与者的列表
Referred-By的消息头为可选消息头,只有在邀请的目标是由其他会话参与者介绍而来时需要,referred-by-URI为此介绍人的URI。
Supported消息头为可选消息头。
Require消息头为可选消息头。
对于[INVITE]消息,如果消息体的类型为SDP,表示消息体类型的头(C: application/sdp)可以省略。
11.2.1.1.2. 消息体格式
其中network-address为邀请者的网络地址。
port为邀请者与服务器连接的本地端口号。
user-uri为邀请者的URI,格式如下:
11.2.1.1.3. 消息示例
11.2.1.2. 临时应答 – [INVITE-RSP-IM-UAC-Trying]
11.2.1.2.1. 消息格式
target-uri为邀请目标的URI,格式如下:
11.2.1.2.2. 消息示例
11.2.1.3. 回铃 – [INVITE-RSP-IM-UAC-Ringing]
请求方再收到回铃应答后,应该延长邀请消息的超时时间(10-30秒)。
11.2.1.3.1. 消息格式
target-uri为邀请目标的URI,格式如下:
11.2.1.3.2. 消息示例
11.2.1.4. 最终应答 – [INVITE-RSP-IM-UAC]
11.2.1.4.1. 消息格式
target-uri为邀请目标的URI,格式如下:
Supported消息头为可选消息头。
对于[INVITE]消息的应答,如果没有指定消息体类型(Content-Type),客户端应当认为消息体的类型为SDP,相当于消息头:
11.2.1.4.2. 消息体格式
消息体格式与请求消息相同,不同之处在于network-address、port、user-uri分别为被邀请方的相应信息。
11.2.1.4.3. 消息示例
11.2.1.4.4. 错误处理
11.2.2. UAS
11.2.2.1. 请求消息 – [INVITE-IM-UAS]
11.2.2.1.1. 消息格式
Roster-Manager为会话管理者的URI,source-uri为邀请发出者的URI,格式如下:
EndPoints为逗号分割的会话参与者的列表
当存在Referred-By的消息头时,referred-by-URI为参加此次会话介绍人的URI。
Supported消息头为可选消息头。
Require消息头为可选消息头。
对于[INVITE]消息,如果没有指定消息体类型(Content-Type),客户端应当认为消息体的类型为SDP,相当于消息头:
11.2.2.1.2. 消息体格式
消息体格式与UAC发出的请求消息相同
11.2.2.1.3. 消息示例
11.2.2.2. 临时应答 – [INVITE-RSP-IM-UAS-Trying]
被请求方受到邀请后,应该立即返回一个临时应答。
11.2.2.2.1. 消息格式
source-uri为邀请目标的URI,格式如下:
11.2.2.2.2. 消息示例
11.2.2.3. 回铃 – [INVITE-RSP-IM-UAS-Ringing]
如果邀请确认需要较长时间,为了避免请求超时,被邀请方可以间隔一定时间(10-30秒)返回一个回铃应答消息。
11.2.2.3.1. 消息格式
source-uri为邀请目标的URI,格式如下:
11.2.2.3.2. 消息示例
11.2.2.4. 最终应答 – [INVITE-RSP-IM-UAS]
11.2.2.4.1. 消息格式
source-uri为邀请目标的URI,格式如下:
Supported消息头为可选消息头。
对于[INVITE]消息,如果消息体的类型为SDP,表示消息体类型的头(C: application/sdp)可以省略。
11.2.2.4.2. 消息体格式
消息体格式与请求消息相同,不同之处在于network-address、port、user-uri分别为当前被邀请方的相应信息。
11.2.2.4.3. 消息示例
11.2.2.4.4. 错误处理
11.3. 取消过程
11.3.1. UAC
11.3.1.1. 请求消息 – [CANCEL-IM-UAC]
11.3.1.1.1. 消息格式
取消消息对应一条特定邀请消息,所以取消消息的消息头From、To、Call-ID的值应该与对应的邀请消息相同。CSeq头的cseq-value部分也应该与对应的邀请消息相同。
11.3.1.1.2. 消息示例
11.3.1.2. 应答消息 – [CANCEL-RSP-IM-UAC]
11.3.1.2.1. 消息格式
11.3.1.2.2. 消息示例
11.3.1.2.3. 错误处理
481 – 要取消的邀请在服务器端并不存在。
无论CANCEL消息的返回结果是什么,只要收到应答消息前收到了对应的INVITE消息的2XX应答消息,都应该像服务器发送ACK和BYE消息以结束会话。
11.3.2. UAS
11.3.2.1. 请求消息 – [CANCEL-IM-UAS]
11.3.2.1.1. 消息格式
取消消息对应一条特定邀请消息,取消消息的消息头From、Call-ID的值应该与对应的邀请消息相同。CSeq头的cseq-value部分也应该与对应的邀请消息相同。
11.3.2.1.2. 消息示例
11.3.2.2. 应答消息 – [CANCEL-RSP-IM-UAS]
11.3.2.2.1. 消息格式
11.3.2.2.2. 消息示例
11.3.2.2.3. 错误处理
如果无法匹配到对应的IVNITE消息,则返回 :
481 Call/Transaction Does Not Exist。
如果在回复对应的INVITE消息前收到取消消息,则终止会话,无需返回INVITE消息的应答消息,返回CANCEL消息的200应答消息。
如果在回复对应的INVITE消息后收到取消消息,则直接返回CANCEL消息的200应答消息,但不影响会话的状态。
11.4. 确认过程
11.4.1. UAC – [ACK-IM-UAC]
11.4.1.1. 消息格式
确认消息对应一条特定邀请消息,所以取消消息的消息头From、To、Call-ID的值应该与对应的邀请消息相同。CSeq头的cseq-value部分也应该与对应的邀请消息相同。
确认消息无对应的应答消息。
11.4.1.2. 消息示例
11.4.2. UAS – [ACK-IM-UAS]
11.4.2.1. 消息格式
确认消息对应一条特定邀请消息,取消消息的消息头From、Call-ID的值应该与对应的邀请消息相同。CSeq头的cseq-value部分也应该与对应的邀请消息相同。
11.4.2.2. 消息示例
11.4.2.3. 错误处理
如果被邀请方在返回对INVITE消息后的60秒内没有受到对应的ACK消息,则认为此会话超时,则应该向对方发送BYE消息并结束对话。
如果在收到ACK消息前,在同一个会话中收到除了CANCEL和BYE之外的其他消息,则表明发生了错误,此时UAS应该返回500 Server Internal Error,然后向会话的另一方发送BYE消息,以结束会话。
11.5. 消息传送
11.5.1. UAC
11.5.1.1. 请求消息 – [MSG-IM-UAC]
11.5.1.1.1. 消息格式
target-uri为消息目标的URI,格式如下:
消息的Call-ID应该与建立会话INVITE消息的Call-ID相同。
CSeq的cseq-value部分为此次会话中发送的消息的序列号。
对于[MESSAGE]消息,如果消息体的类型为text/plain,表示消息体类型的消息头可以省略。
11.5.1.1.2. 消息体格式
即时消息的消息体的详细格式请参考即时消息格式一章。
11.5.1.1.3. 消息示例
11.5.1.2. 应答消息 – [MSG-RSP-IM-UAC]
11.5.1.2.1. 消息格式
11.5.1.2.2. 消息示例
11.5.1.2.3. 错误处理
11.5.2. UAS
11.5.2.1. 请求消息 – [MSG-IM-UAS]
11.5.2.1.1. 消息格式
source-uri为消息发送者的URI,格式如下:
消息的Call-ID与建立会话INVITE消息的Call-ID相同。
CSeq的cseq-value部分为此次会话中发送的消息的序列号。
对于[MESSAGE]消息,如果没有指定消息体类型,则消息体的类型为text/plain。
11.5.2.1.2. 消息体格式
即时消息的消息体的详细格式请参考即时消息格式一章。
11.5.2.1.3. 消息示例
11.5.2.2. 应答消息 – [MSG-RSP-IM-UAS]
11.5.2.2.1. 消息格式
11.5.2.2.2. 消息示例
11.5.2.2.3. 错误处理
如果无法匹配会话,则作为离线消息处理。
11.6. 结束会话
11.6.1. UAC
当一个会话的参与者希望退出一个会话时,应该向所有的会话参与者发送结束会话消息。
11.6.1.1. 请求消息 – [BYE-IM-UAC]
11.6.1.1.1. 消息格式
target-uri为会话目标的URI,格式如下:
Call-ID的值应该和会话建立时使用的Call-ID的值相同。
11.6.1.1.2. 消息示例
11.6.1.2. 应答消息 – [BYE-RSP-IM-UAC]
11.6.1.2.1. 消息格式
11.6.1.2.2. 消息示例
11.6.1.2.3. 错误处理
11.6.2. UAS
11.6.2.1. 请求消息 – [BYE-IM-UAS]
11.6.2.1.1. 消息格式
source-uri为消息发送者的URI,格式如下:
Call-ID的值和会话建立时使用的Call-ID的值相同。
11.6.2.1.2. 消息示例
11.6.2.2. 应答消息 – [BYE-RSP-IM-UAS]
11.6.2.2.1. 消息格式
11.6.2.2.2. 消息示例
11.6.2.2.3. 错误处理
11.7. 文件共享
11.7.1. 上传文件
文件共享的发起方应当首先将文件上传到共享内容服务器,并从上传结果中获取上传内容的URL。具体的上传协议可参考共享文件上传。
11.7.2. 发送消息
将共享文件的名字与URL按一定格式编码到一个消息中。并作为消息发送给接收方。消息的编码方式可参考文件共享。
11.7.3. 下载文件
接收方受到消息后,试图打开共享内容时,从服务器下载文件。下载协议可参考共享文件下载。
12. 语音聊天(IVR)
12.1. 模式
12.1.1. 流程
12.1.2. 取消过程
取消过程与即使消息会话中的取消逻辑稍有不同,即使会话正确建立后,语音聊天发起方也可以通过发送CANCEL消息,来通知其他参与者此会话被取消;其他参与者即使在确认参与后后,也应该提示此次语音聊天已被取消。
无论是否存在取消过程,ACK和BYE的逻辑不变。
12.2. 邀请过程
12.2.1. UAC
12.2.1.1. 请求消息 – [INVITE-IVR-UAC]
12.2.1.1.1. 消息格式
target-uri为邀请目标的URI,格式如下:
对于[INVITE]消息,如果消息体的类型为SDP,表示消息体类型的头(C: application/sdp)可以省略。
12.2.1.1.2. 消息体格式
其中network-address为邀请者的网络地址。
user-uri为邀请者的URI。
user-uri-1、user-uri-2等为参与此次会话的2个或更多用户的URI列表。
URI格式如下:
12.2.1.1.3. 消息示例
12.2.1.2. 临时应答 – [INVITE-RSP-IVR-UAC-Trying]
12.2.1.2.1. 消息格式
target-uri为邀请目标的URI,格式如下:
12.2.1.2.2. 消息示例
12.2.1.3. 回铃 – [INVITE-RSP-IVR-UAC-Ringing]
请求方再收到回铃应答后,应该延长邀请消息的超时时间(10-30秒)。
12.2.1.3.1. 消息格式
target-uri为邀请目标的URI,格式如下:
12.2.1.3.2. 消息示例
12.2.1.4. 最终应答 – [INVITE-RSP-IVR-UAC]
12.2.1.4.1. 消息格式
target-uri为邀请目标的URI,格式如下:
对于[INVITE]消息的应答,如果没有指定消息体类型(Content-Type),客户端应当认为消息体的类型为SDP,相当于消息头:
12.2.1.4.2. 消息体格式
消息体格式与请求消息相同,不同之处在于network-address、user-uri分别为被邀请方的相应信息。
12.2.1.4.3. 消息示例
12.2.1.4.4. 错误处理
12.2.2. UAS
12.2.2.1. 请求消息 – [INVITE-IVR-UAS]
12.2.2.1.1. 消息格式
source-uri为邀请发出者的URI,格式如下:
对于[INVITE]消息,如果没有指定消息体类型(Content-Type),客户端应当认为消息体的类型为SDP,相当于消息头:
12.2.2.1.2. 消息体格式
消息体格式与UAC发出的请求消息相同
12.2.2.1.3. 消息示例
12.2.2.2. 临时应答 – [INVITE-RSP-IVR-UAS-Trying]
被请求方受到邀请后,应该立即返回一个临时应答。
12.2.2.2.1. 消息格式
source-uri为邀请目标的URI,格式如下:
12.2.2.2.2. 消息示例
12.2.2.3. 回铃 – [INVITE-RSP-IVR-UAS-Ringing]
如果邀请确认需要较长时间,为了避免请求超时,被邀请方可以间隔一定时间(10-30秒)返回一个回铃应答消息。
12.2.2.3.1. 消息格式
source-uri为邀请目标的URI,格式如下:
12.2.2.3.2. 消息示例
12.2.2.4. 最终应答 – [INVITE-RSP-IVR-UAS]
12.2.2.4.1. 消息格式
source-uri为邀请目标的URI,格式如下:
对于[INVITE]消息,如果消息体的类型为SDP,表示消息体类型的头(C: application/sdp)可以省略。
12.2.2.4.2. 消息体格式
消息体格式与请求消息相同,不同之处在于network-address、user-uri分别为当前被邀请方的相应信息。
12.2.2.4.3. 消息示例
12.2.2.4.4. 错误处理
12.3. 取消过程
12.3.1. UAC
12.3.1.1. 请求消息 – [CANCEL-IVR-UAC]
12.3.1.1.1. 消息格式
取消消息对应一条特定邀请消息,所以取消消息的消息头From、To、Call-ID的值应该与对应的邀请消息相同。CSeq头的cseq-value部分也应该与对应的邀请消息相同。
对于IVR会话过程,即使被邀请方已经返回INVITE消息的2xx应答,在发起聊天的命令发送前,发起者仍可以使用CANCEL消息来通知参与者会话被取消。
12.3.1.1.2. 消息示例
12.3.1.2. 应答消息 – [CANCEL-RSP-IVR-UAC]
12.3.1.2.1. 消息格式
12.3.1.2.2. 消息示例
12.3.1.2.3. 错误处理
481 – 要取消的邀请在服务器端并不存在。
无论CANCEL消息的返回结果是什么,只要收到应答消息前收到了对应的INVITE消息的2XX应答消息,都应该像服务器发送ACK和BYE消息以结束会话。
12.3.2. UAS
12.3.2.1. 请求消息 – [CANCEL-IVR-UAS]
12.3.2.1.1. 消息格式
取消消息对应一条特定邀请消息,取消消息的消息头From、Call-ID的值应该与对应的邀请消息相同。CSeq头的cseq-value部分也应该与对应的邀请消息相同。
对于IVR会话,UAS即使已经收到了客户端的ACK消息,仍可能在稍后收到CANCEL消息,此时UAS仍应该将此会话已取消的信息提示给用户,但并不影响此会话的状态。
12.3.2.1.2. 消息示例
12.3.2.2. 应答消息 – [CANCEL-RSP-IVR-UAS]
12.3.2.2.1. 消息格式
12.3.2.2.2. 消息示例
12.3.2.2.3. 错误处理
如果无法匹配到对应的IVNITE消息,则返回 :
481 Call/Transaction Does Not Exist。
如果在回复对应的INVITE消息前收到取消消息,则终止会话,无需返回INVITE消息的应答消息,返回CANCEL消息的200应答消息。
如果在回复对应的INVITE消息后收到取消消息,则直接返回CANCEL消息的200应答消息,但不影响会话的状态。
12.4. 确认过程
12.4.1. UAC – [ACK-IVR-UAC]
12.4.1.1. 消息格式
确认消息对应一条特定邀请消息,所以取消消息的消息头From、To、Call-ID的值应该与对应的邀请消息相同。CSeq头的cseq-value部分也应该与对应的邀请消息相同。
确认消息无对应的应答消息。
12.4.1.2. 消息示例
12.4.2. UAS – [ACK-IVR-UAS]
12.4.2.1. 消息格式
确认消息对应一条特定邀请消息,取消消息的消息头From、Call-ID的值应该与对应的邀请消息相同。CSeq头的cseq-value部分也应该与对应的邀请消息相同。
12.4.2.2. 消息示例
12.4.2.3. 错误处理
如果被邀请方在返回对INVITE消息后的90秒内没有受到对应的ACK消息,则认为此会话超时,则应该向对方发送BYE消息并结束对话。
如果在收到ACK消息前,在同一个会话中收到除了CANCEL和BYE之外的其他消息,则表明发生了错误,此时UAS应该返回500 Server Internal Error,然后向会话的另一方发送BYE消息,以结束会话。
12.5. 发起聊天
12.5.1. 请求消息 - [SVC-StartVoiceChat]
12.5.1.1. 消息格式
其中target-URI为查询目标的URI,格式如下:
12.5.1.2. 消息体格式
节点名称 功能 格式 非空
BeginDate 即将开始语音聊天的日期。例如:”2005-9-30 15:30:9”。如果此值为空,表示立刻开始语音聊天。 DateTime
User 开始语音聊天的全部用户(包括主叫用户),每个节点代表一个用户,可以有多个节点。 是
Sid 用户的系统标识 Int 是
12.5.1.3. 消息示例
12.5.2. 应答消息 - [SVC-RSP-StartVoiceChat]
12.5.2.1. 消息格式
12.5.2.2. 消息体格式
节点名称 功能 格式 非空
BeginDate 如果ErrorCode为0,则此值表示语音聊天将开始的日期。如“2005-9-30 23:59:59”。如果发生错误,此值为空。 DateTime
FailedUsers 每个节点代表一个不能开始语音聊天的用户,可以有多个节点。如果全部用户皆可开始语音聊天,则此节点为空。
Sid 用户的系统标识 Int 是
12.5.2.3. 消息示例
12.5.2.4. 错误处理
如果部分用户无法加入语音聊天,应该提示给发起者和各个参与者。
12.6. 结束会话
12.6.1. UAC
但本次语音聊天呼叫建立成功或失败后,应该立即发送BYE消息结束此次会话。
12.6.1.1. 请求消息 – [BYE-IVR-UAC]
12.6.1.1.1. 消息格式
target-uri为会话目标的URI,格式如下:
Call-ID的值应该和会话建立时使用的Call-ID的值相同。
12.6.1.1.2. 消息示例
12.6.1.2. 应答消息 – [BYE-RSP-IVR-UAC]
12.6.1.2.1. 消息格式
12.6.1.2.2. 消息示例
12.6.1.2.3. 错误处理
12.6.2. UAS
12.6.2.1. 请求消息 – [BYE-IVR-UAS]
12.6.2.1.1. 消息格式
source-uri为消息发送者的URI,格式如下:
Call-ID的值和会话建立时使用的Call-ID的值相同。
12.6.2.1.2. 消息示例
12.6.2.2. 应答消息 – [BYE-RSP-IVR-UAS]
12.6.2.2.1. 消息格式
12.6.2.2.2. 消息示例
12.6.2.2.3. 错误处理
13. 离线消息
13.1. 模式
当联系人不在线,或者联系人状态未知时,可以直接向目标发送离线消息。此时如果联系人在线,可直接收到消息;如果联系人短信在线,此消息将被转换为短信发送给联系人;如果联系人短信也不在线或选择了离线消息的存储转发,系统将暂时存储此消息,当其上线时再进行转发。
对于离线消息的接受方,因为消息并不在一个会话中,所以当接受方回复消息时,有两种情况:
如果接受方看来发送方离线或状态未知,回复的消息也应作为离线消息发送。
如果接受方此时看来在线,应该先建立即时消息会话[参考11 会话部分]。
13.2. 发送离线消息
13.2.1. 请求消息 - [MSG-SendOfflineMessage]
13.2.1.1. 消息格式
其中target-URI为消息目标方目标的URI,格式如下:
当消息类型为text/plain时,此时消息头Content-Type可以省略。
13.2.1.2. 消息体格式
消息体格式的解析,可参考[即时消息格式]部分。
13.2.1.3. 消息示例
13.2.2. 应答消息 - [MSG-RSP-SendOfflineMessage]
13.2.2.1. 消息格式
13.2.2.2. 消息示例
13.2.2.3. 错误处理
离线消息并不一定被存储转发,系统应自动根据目标方的状态来决定消息的处理方式,转为短信、存储转发或者转给实际在线的客户端。
13.3. 获取存储转发消息
客户端登陆成功后,应该主动向服务器索要被存储转发的消息。
13.3.1. 请求消息 - [SVC-GetOfflineMessage]
13.3.1.1. 消息格式
13.3.1.2. 消息示例
13.3.2. 应答消息 - [SVC-RSP-GetOfflineMessage]
13.3.2.1. 消息格式
13.3.2.2. 消息示例
13.3.2.3. 错误处理
返回200状态码表示操作成功,当并不表示一定有离线消息。如果有未读取的离线消息,稍后会以[MSG-OfflineMessage]消息返回。
13.4. 接收离线消息
13.4.1. 接收消息 - [MSG-OfflineMessage]
13.4.1.1. 消息格式
其中source-URI为消息发送方的URI,格式如下:
当消息类型为text/plain时,此时消息头Content-Type可以省略。
13.4.1.2. 消息体格式
消息体格式的解析,可参考[即时消息格式]部分。
13.4.1.3. 消息示例
13.4.2. 应答消息 - [MSG-RSP-OfflineMessage]
13.4.2.1. 消息格式
13.4.2.2. 消息示例
13.4.2.3. 错误处理
14. 短信通道
14.1. 获取当前手机号
14.1.1. 过程描述
? 向系统指定的短信网关发送一条查询短信,短信网关回复查询结果。
? 客户端需截获并解析网关返回的短信
14.1.2. 发送格式 – [SMS-QueryPhone]
? 必须为关键字QueryPhone(大小写不敏感)。
14.1.3. 接收格式 – [SMS-RSP-QueryPhone]
? 以英文关键字“CurrentPhone”开始,不区分大小写,其后紧接一个英文空格。
? 每个用于注册数据项之间以一个英文空格为分隔符。
节点名称 功能 格式 非空
URI 连接LC服务器的帐号
格式为:345@bj.amigo.com Varchar(30) 是
Sid 用户的系统标识 Int 是
手机号 当前用户的手机号码 Varchar(11) 是
开通标志 0 - 标示该手机号码未开通
1 - 表示已经开通
2 - 表示已开通但停用
5 - 表示开通但未设置初始密码
Int 是
? 以关键字CurrentPhone(大小写不敏感)。
? 其后接一个空格。
? 其后接用户的数字系统登录帐号,即(SID)。如果用户未注册过(不包括开通过但后来停止服务了),则此值为0
? 其后接一个空格。
? 其后接被当前用户的手机号码。
? 其后接一个空格。
? 其后接用户的URI(格式为:)。
? 其后接一个空格。
? 其后接一位数字的开通标志:0标识该手机号码未开通,1表示已经开通,2表示已开通但停用。
14.2. 重设密码
14.2.1. 过程描述
? 向系统指定的短信网关发送一条指定格式的短信,短信网关回复设置结果。
? 客户端需截获并解析网关返回的短信
14.2.2. 发送格式 – [SMS-SetPassword]
? 必须以英文关键字“SetPassword”开始,不区分大小写
? 其后紧接一个英文空格。
? 其后紧接用户密码。
节点名称 功能 格式 非空
用户密码 用户的密码(ASCII码0x21-0x7E,但不包含#) Varchar(16) 是
14.2.3. 接收格式 – [SMS-RSP-SetPassword]
? 以英文关键字“SetPassword”开始,不区分大小写
? 其后紧接一个英文空格。
? 其后接错误编码。
节点名称 功能 格式 非空
ErrorCode 错误编码。数字200表示注册成功,否则为失败. 定义见下一节。 Int 是
错误描述 如果出错,为出错描述。否则为空 NVarchar(30)
14.2.4. 错误码
值 含义
442 密码为空、格式错误或包含非法字符
503 用户未开通
14.3. 离线发送消息- [SMS-Message]
?以指定网关的特服号+目标的SID为目标号码,将消息作为短信的内容发给此号码。
?目标回复的消息将同样来自这个目标号码,客户端应截获并显示应答消息。
14.4. 获取手机号2
14.4.1 过程描述
? 流程与 1 类似,但是是通过发送新定义的短信来作为开通 FETION 方法。
? 客户端需截获并解析网关返回的短信
14.4.2 发送格式 – [SMS- QueryPhone2]
14.4.3 应答格式 – [SMS-RSP-QueryPhone2]
? 客户端靠5301这个子号码来识别是QueryPhone2命令的返回结果
? 其中└┘代表英文空格
? 如果用户从未开通FETION(开通标志 = 0),则取格式1
? 如果用户当前开通FETION(开通标志 > 0),则取格式2,返回用户的基本资料
如果用户曾经开通FETION(开通标志 < 0),则取格式2,返回用户上次登记的基本资料
各字段说明如下:
节点名称 功能 格式 非空
手机号 当前用户的手机号码 varchar(11) 是
开通标志 0 - 表示该手机号码从未开通FETION
1 - 表示已经开通FETION,并已设置密码
5 - 表示已经开通FETION,但未设置密码
-1 - 表示曾经开通FETION(当前处于未开通状态) int 是
URI 用于登录服务器的帐号(仅当开通标志不为0时有效)
格式为345或345@bj.amigo.com。 如果不带@符号,则为URI相当于用户的SID; 如果带@符号,则@符号前面的就是用户的SID。 客户端需要适应这两种情况 varchar(30)
昵称 仅当开通标志不为0时有效
如果用户的昵称为空串,则昵称字段将没有任何字符。 因昵称字段前后各有一个空格,因此会在URI字段和性别字段之间出现连续的两个空格,客户端应适应这种情况 nvarchar(15)
性别 该用户的性别(仅当开通标志不为0时有效)
M=男,F=女,U=未知 char(1)
出生日期 该用户的出生日期(仅当开通标志不为0时有效)。
格式为1976-2-12格式(即月、日可能为1~2位)。 用1900-1-1表示用户未设置出生日期。 datetime
14.5注册短信
14.5.1描述
? 新增短信命令将仅开通FETION,而不开通Fetion交友(调用Provision.Register的1号功能)。
14.5.2 发送格式 – [SMS-Register2]
说明:
? Register2命令、性别大小写不敏感,用户密码、昵称大小写敏感
? 其中└┘代表英文空格
? 用户的每个用于注册的数据项之间以一个英文“#”为分隔符,数据项之间不能有无意义的空格。如果该项用户未填,用于分割该项的“#”必须保留
? 旧版短信命令Register支持不填性别或性别为”未知”,新增Register2命令要求必须明确指定性别(即必须为M或F)
14.5.3 应答格式 – [SMS-RSP-Register2]
? 客户端靠5302这个子号码来识别是Register2命令的返回结果
? 其中└┘代表英文空格
? 如果操作成功(操作结果 >= 200 && 操作结果 <= 299),则采用格式1
如果操作失败(操作结果>=300),则采用格式2
15. 数据通道
15.1. 获取导航信息
15.1.1. 过程描述
?客户端向指定的服务器位置发送请求
?服务器端返回应答
15.1.2. 发送格式 - [HTTP-GetConfig]
? HTTP头为:
? POST /Getconfig.aspx HTTP/1.1
? HTTP体中参数包含:
? Sid:用户的9位数字ID
? CellPhone:用户的手机号码,11位数字。(与SID二者至少有一个不能为空)
? Protocol:字符串,使用不带空格的英文分号表明客户端在连接支持的连接协议。如:“SIP”表明支持的连接协议。“SIP;HTTP”标识支持SIP和HTTP两种协议。(不为空)
? ClientVersion:字符串。表明登录服务器的客户端程序版本。由英文斜线分割客户端软件名字和版本号。如:Amigo_Smartphone_official/1.2.32。(不为空)
? Imei:字符串。手机的硬件序列号。(不为空)
15.1.3. 接收格式 – [HTTP-RSP-GetConfig]
? Response节点
? Error 错误号,如果命令正确,返回0,其它值表示错误。
? Memo 错误号的文字描述
? NewestClient节点下包含了服务器上拥有的最新版本的客户端软件。其下的子节点为客户端软件的名字。
? Version:字符串。以英文句号分割成三部分数字的字符串。分别代表主版本号,次版本号,修订号。
? Compatible:该软件所向下兼容的最低版本的客户端版本号。格式同Version。如果用户在用的客户端小于这个最低版本号,则用户必须升级,否则不能进行登录。如果大于Compatible而小于Version,则提示升级。
? Size:最新版本软件的大小。单位:byte。
? Date:最新版本软件的发布日期。格式:2005-4-1
? HttpApplication节点:包含多个Uri节点,每个节点定义一个类型应用服务的URL。如:http://amigo.com/upload/userphoto.aspx
? Uri:服务器地址,其中包含了协议,地址,端口号,虚拟路径信息。如:http://gateway.amigomessenger.com:6200或tls://bj.lcs.amigomessenger.com:5061
? Uri/@type=DownloadUserPhoto: 下载用户大头像的HTTP应用程序路径
? Uri/@type=UploadUserPhoto: 上传用户大头像的HTTP应用程序路径
? Uri/@type=UploadSharedContent: 上传内容共享的HTTP应用程序路径
? Uri/@type=DownSharedContent: 下载内容共享的HTTP服务器路径(格式如:http://m161.com.cn/download)
? Uri/@type= GetSipUri: 获取SipUri及注册状态的HTTP应用程序路径
? SipProxy:SIP服务器的相关信息
? Uri:服务器地址。格式为:”sip:sipproxy4.amigo.com:5060”
? Priority:服务器的连接优先级。(当有多个服务器有能力提供该服务时,可以以此顺序逐个尝试找寻一个可用的服务器)
? SipcProxy:SIP-C代理服务器的相关信息
? Uri:服务器地址。格式为:”sip:sipproxy4.amigo.com:5060”
? Priority:服务器的连接优先级。(当有多个服务器有能力提供该服务时,可以以此顺序逐个尝试找寻一个可用的服务器)
? ClientConfig:客户端的配置信息
? Tip/@type=ChatIM:当向好友发送消息时,系统切换至“即时消息”状态时,给予用户的提示信息。
? Tip/@type=ChatSMS:当向好友发送消息时,系统切换至“短消息”状态时,给予用户的提示信息。
? Tip/@type=FETIONCharge: FETION 的资费说明
? Tip/@type=FETIONIsFree: 标识 FETION 是否免费,true 表示免费,false 表示收费
? Tip/@type=ChatCharge: Fetion交友的资费说明
Tip/@type=ChatIsFree: 标识Fetion交友是否收费,true 表示免费,false 表示收费
15.1.4. 错误码
值 含义
10 SID与CellPhone不能同时为空
11 SID格式错误
21 CellPhone格式错误
40 Imei不能为空
50 Protocol不能为空
51 Protocol不合法或不被支持。
91 请求的url不合法.
500 服务器发生未知错误
15.2. 获取用户URI
15.2.1. 过程描述
?客户端向指定的服务器URL发送请求。其中URL为导航信息中type属性为GetSipUri的Uri节点的值。
?服务器端返回应答。
15.2.2. 发送格式 – [HTTP-GetSipUri]
? HTTP方法:GET
? 必须包含的HTTP参数
? Sid:待获取的用户的9位数字的系统标识。
15.2.3. 接收格式 – [HTTP-RSP-GetSipUri]
节点名称 功能 格式 非空
Error 错误号,如果命令正确,返回0,其它值表示发生错误。 INT 是
Memo 错误号的文字描述 NVarchar(100)
User 被获取的用户信息
Sid 用户系统标识 Int 用户无效则为空,否则非空
Uri 用户登录LC服务器的帐户 Varchar(100) 同上
15.2.4. 错误码
值 含义
10 SID与CellPhone不能同时为空
11 SID格式错误
21 CellPhone格式错误
500 服务器发生未知错误
15.3. 头像上传
15.3.1. 过程描述
?客户端向指定的服务器URL发送请求。其中URL为导航信息中type属性为UploadUserPhoto的Uri节点的值。
?服务器端返回应答。
15.3.2. 发送格式 – [HTTP-UploadUserPhoto]
? HTTP方法:POST
? 必须包含的HTTP参数
? AmigoToken:用户的身份验证票据,定义见获取用户信息的应答[SVC-RSP-GetUserConfig]
? FileName:上传的文件名称
? FileData:上传文件的二进制数据
15.3.3. 接收格式 – [HTTP-RSP-UploadUserPhoto]
HTTP体
节点名称 功能 格式 非空
Error 上传操作的错误码。如果为0则表示上传成功,其它值为发生错误。 Int 是
Url 下载用户大头像的Web地址。如果为空,则表明用户上传了空的大头像,即该用户删除了自己的大头像。此url并非一个完全限定名的Http地址,而是一个相对下载路径。需取得全部路径,需要再加上导航信息中的头像的下载位置地址。 Varchar(200)
PhotoCRC 用户大头像的文件的校验和 Varchar(32)
Memo 关于大头像更改的附加文字描述。(如果Url为空,无此节点或此节点的值为空),则此部分为中文的“错误描述”。 NVarchar(100)
15.3.4. 发送头像改变通知
头像上传成功后,可以通过设置自己的状态,来通知自己状态的订阅者,头像发生改变,具体的消息格式参考[SVC-SetPresence],其中photo节点的crc属性设为应答消息中的PhotoCRC的值,url属性设为Url节点的值。
15.3.5. 错误码
值 含义
10 没有上传文件
20 上传的文件格式不被支持
100 没有包含AmigoToken
200 AmigoToken发生错误
210 AmigoToken已经过期
500 服务器发生未知错误
15.4. 头像下载
15.4.1. 过程描述
?客户端向指定的服务器URL发送请求。其中URL为导航信息中type属性为DownLoadUserPhoto的Uri节点的值,再加上头像的相对地址。
?服务器端返回头像数据。
15.4.2. 发送格式 – [HTTP-DownloadUserPhoto]
? HTTP方法:GET
? 必须包含的HTTP参数
? AmigoToken:用户的身份验证票据,定义见获取用户信息的应答[SVC-RSP-GetUserConfig]。
? Sid:待获取的用户的9位数字的系统标识。
? Size:数字。当“1”时:表示获取64x64的大头像。“2”时:表示获取“24x24”的大头像缩略图。
15.4.3. 接收格式 – [HTTP-RSP-DownloadUserPhoto]
? HTTP头:
? 包含一个自定义的头标签:“PhotoCRC”,表明大头像(64x64)文件的校验和。校验和与返回的头像大小无关。
? 标准的HTTP二进制文件下载格式,头像为jpg格式。
? 当下载发生错误:
? HTTP头Content-Type: text/xml
? HTTP体
Error:整数格式的错误编码。
Memo:错误的中文描述。
15.4.4. 错误码
值 含义
401 参数异常
402 Amigotoken错误
403 无权限获取
404 大头像文件不存在
500 服务器发生未知错误
15.5. 共享文件上传
15.5.1. 过程描述
?客户端向指定的服务器URL发送请求。其中URL为导航信息中type属性为UploadSharedContent的Uri节点的值。
?服务器端返回应答。
15.5.2. 发送格式 – [HTTP-UploadFile]
? HTTP方法:POST
? 必须包含的HTTP参数
? AmigoToken:用户的身份验证票据,定义见获取用户信息的应答[SVC-RSP-GetUserConfig]。
? FileName:上传的文件名称。
? FileData:上传文件的二进制数据。
15.5.3. 接收格式 – [HTTP-RSP-UploadFile]
HTTP体
节点名称 功能 格式 非空
Error 上传操作的错误码。0表示上传成功,其它值为发生错误。 Int 是
Url 浏览该文件的URL地址。 Varchar(200)
Memo 关于共享文件的附加文字描述。如果Url为空,无此节点或此节点的值为空,则此部分为错误描述。 NVarchar(100)
15.5.4. 错误码
值 含义
10 没有上传文件
11 上传的文件名不能为空
20 上传的文件格式不被支持
100 没有包含AmigoToken
200 AmigoToken发生错误
210 AmigoToken已经过期
500 服务器发生未知错误
15.6. 共享文件下载
?客户端向指定的服务器URL发送HTTP请求。其中URL为导航信息中type属性为DownSharedContent的Uri节点的值,再加上文件的相对地址。
?无特殊系统参数。
?服务器端返回文件数据。
16. 即时消息格式
客户端应至少支持text/plain类型的即时消息,当客户端接收到的未知类型消息内容时,应当作为text/plain来进行处理。
当消息类型为text/plain时,此时消息头Content-Type可以省略。
客户端应至少处理消息中的以下元素:表情图片和控制标签,以及文件共享。
16.1. 表情图片
共计32个,每个表情图片尺寸为20*20像素
序号 表情中文 聊天文字 图画表情 序号 表情中文 聊天文字 图画表情
1 微笑 :) 2 大笑 :D
3 装酷 8D 4 脸红害羞 :I
5 伤心 :( 6 流泪 :P
7 做鬼脸 ;) 8 困惑 ;S
9 生气 :8 10 红心 (L)
11 心碎 (B) 12 震惊 (S)
13 生病 +8( 14 哀求 (H)
15 夸奖 (P) 16 胜利 (V)
17 瞌睡 :S 18 闭嘴 (D)
19 鄙视 :B 20 美女 :G
21 帅哥 :-B 22 猪头 :-G
23 *** :-Z 24 电话 (M)
25 握手 :H 26 玫瑰 (F)
27 凋谢的玫瑰 :F( 28 爱慕 :L
29 悄悄话 :Q 30 匕首 (K)
31 吻 :K 32 吃饭 :5F
16.2. 控制标签
16.2.1. 功能描述
? 用户在收发消息时,消息体中包含隐藏的控制性标签,不同的标签表示不同的功能。
? 所有的标签以英文尖括号构成(ASCII 0x3C与0x3E)。标签应为成对出现。客户端软件应隐藏对下列内容的显示
? 可识别的标签
? 不可识别的标签,即所有包含在尖括号中的全部内容。(例如:当遇见不可识别的标签“Wav”,my.wav,处理后应该为”my.wav”)
? 标签名称为大小写敏感
? 在发送消息前,应对用户输入内容进行文本编码
? 在接收到消息后,应对消息体中的内容进行文本解码
16.2.2. 标签格式
? 所有的标签以英文尖括号构成(ASCII 0x3C与0x3E),一组标签包含一个开始标签和一个结束标签,必须成对出现格式:
? <标签名>标签名>
? 标签内部可以包含属性,属性内容必须以英文双引号包裹。格式:
? <标签名 属性名=”属性的值”>标签名>
? 标签名称为大小写敏感,标签中的属性名也为大小写敏感。属性间应包含一个以上英文空格。标签属性值中不能包含英文&,<,>,”字符应转义。标签名称与英文见括号及英文字符“/”不能包含空格。
? 下列为合法标签
? 我的照片
? 我的照片
? 我的照片
? 下列为不合法标签
? 我的照片
? 我的照片
? < Url>我的照片 Url>
? 我的照片
? ”>我的照片
16.2.3. 发送者编码
? 发送即时消息时,发送者应该对用户输入的文字中的特殊字符进行编码。以免被接收者认为时不可识别的标签而导致内容无法正确显示。
? 将英文”&”编码为英文”&”
? 将英文”<”编码为英文”<”
? 将英文”>”编码为英文”>”
? 如果用户输入内容包含需要编码的文本且文本中需加入控制标签,则应先进行文本编码,再加入控制标签
16.2.4. 接收者解码
? 接收到即时消息时,接收者应该对用户输入的文字中的特殊字符进行解码。以免将原始的消息显示错误。
? 将英文”&”解码为英文”&”
? 将英文”<”解码为英文”<”
? 将英文”>”解码为英文”>”
? 如果用户输入内容包含需要编码的文本且文本中包含控制标签,则应先处理控制标签,再进行文本解码。
16.3. 文件共享
文件共享就是使用控制标签的一个例子。
16.3.1. 标签名
? 标签为:友好的文件名
? 示例:
“我今天去了长城,这是我的照片长城英俊照.jpg,不许说我变胖了。”
16.3.2. 功能描述
? 用于标识标签内的内容为一个内容共享文件。在展现在用户界面表现为一个可点击的“友好的文件名”。接收方呈现给用户该“友好的文件名”。
? 其中href属性指向的是共享文件的相对地址。
16.4. 文本格式
17. 全局错误
状态码 Error-Info 状态码 Error-Info
全局
200 没有错误 400 未知的客户端请求错误
441 Sip体数据不完整或格式错误 413 数据体中的数据超长
403 无权限操作 404 用户不存在
500 未知的服务器错误
18. 用户统一状态编码
? 格式:6位数字组成的字符串。如:110201
? 左起1-2位,定义Amigo状态:
? 11:在线
? 12:离线
? 左起3-4位,定义用户状态:
? 00:正常
? 01:忙碌
? 02:片刻回来
? 03:离开
? 04:就餐
? 05:电话中
? 11:开会
? 50-70:用户自定义状态
? 左起5-6位,定义用户的手机状态:
? 00:未知
? 01:开机
? 02:通话中
? 08:不在服务区
? 09:关机
附录1 系统状态码
附录2 消息格式索引
0