中国移动语音平台通讯接口协议-V1.12003-10-07# 1.doc

中国移动语音服务平台 接口协议 VSPP V1 1 中国移动通信集团公司 2003 年年 10 月月 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 2 页 共 18 页 目目 录录 1 介绍介绍 4 1 1 目的 4 1 2 适用范围 4 1 3 参考资料 4 1 4 缩略语 4 1 5 术语定义 4 1 6 版本变更记录 5 2 VSPP 概述概述 6 2 1 VSPP 定义 6 2 1 1业务数据接口 D 6 2 1 2网络数据接口 N 6 2 2 VSPP 协议会话描述 6 2 3 错误处理 7 2 4 超时处理 8 3 VSPP PDU 数据类型和格式定义数据类型和格式定义 9 3 1 VSPP PDU 数据类型定义 9 3 2 VSPP PDU 格式概述 9 3 3 VSPP PDU 布局 10 3 4 VSPP PDU 的原子性 11 4 VSPP 包体定义包体定义 11 4 1 D 接口 PDU 包体定义 11 4 2 连接信息和包体定义的 XML 描述 12 4 3 N 接口 PDU 包体定义 13 4 3 1VSClient 端 BIND 绑定发送请求操作 13 4 3 2VSServer端 BIND 绑定验证请求操作 13 4 3 3VSClient端回复绑定验证请求操作 13 4 3 4VSServer端回复验证请求操作 13 4 3 5 N ENQUIRE LINK 检测通信连接操作 13 4 3 6 N UNBIND 解除绑定操作 14 5 VSPP PDU 包定义举例包定义举例 14 5 1 业务背景 14 5 2 包定义 14 附录附录 1 PDU 应用码应用码 15 A1 分类码汇总 CATEGORY 15 A2 子命令码汇总 SUB COMMAND 15 A3 操作码汇总 OPCODE 15 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 3 页 共 18 页 A4 消息状态码汇总 COMMAND STATUS 16 附录附录 2 API 接口接口 16 结构体定义 16 接口函数 17 服务端接口函数 17 客户端接口函数 17 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 4 页 共 18 页 1 介绍介绍 1 1 目的目的 中国移动公司统一建设全网的语音服务网络和组建类似梦网的商业模式 承载各个服 务提供商的业务 可以降低 SP 的进入门槛 促进业务的发展 中国移动语音服务平台向 各个服务提供商提供业务加载的平台 并结合服务提供商提供的业务流程和业务数据为用 户提供语音服务 为取得业务流程所需的业务数据 语音服务平台需要从各服务提供商取得业务数据 语音服务平台接口协议 VSPP Voice Service Platform Protocol 定义了相关客户服务所遵 循的协议 1 2 适用范围适用范围 本文定义了 VSPP 协议 规定了请求应答的会话方式 报文格式和语法 适用于外部 服务提供商利用 VSPP 接口加载业务时参考 1 3 参考资料参考资料 1 中国移动业务支撑系统业务规范 1 0 版 2001 年 4 月 2 CMCC 移动梦网 业务管理办法 1 0 版 1 4 缩略语缩略语 缩略语缩略语全称 英文 全称 英文 全称 中文 全称 中文 VSPPVoice Service Platform Protocol统一帐户服务协议 PDUProtocol Data Unit协议数据单元 SPService Provider服务提供商 VSPVoice Service Platform语音服务平台 1 5 术语定义术语定义 SPSP 代码 代码 中国移动确定的在语音服务平台上各 SP 服务提供商的唯一标示号 SPSP 服务代码 服务代码 各 SP 服务提供商开展的每一项业务的唯一标示号 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 5 页 共 18 页 服务操作码 服务操作码 业务流程中取得业务数据的每个操作的唯一标示号 主叫号码主叫号码 用户打入语音服务平台的手机号码 被叫号码被叫号码 用户呼叫语音平台的特定服务号 包流水号包流水号 唯一标志一次提取业务数据的标示号 由语音平台提供 1 6 版本变更记录版本变更记录 版本号版本号修订日期修订日期变更内容变更内容 V1 12003 9 24生成初始文档 搭建 VSPP 协议主体架构 V1 12003 10 7增加了消息包的包头 包尾标志 增加 API 接口函数定义 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 6 页 共 18 页 2 VSPP 概述概述 2 1 VSPP 定义定义 VSPP 协议是用于完成 VSP 与其相关外部实体 服务提供商 之间的通讯及数据传输 而编订的 VSPP 是基于字节流的协议 是一建立在 TCP IP 协议之上的应用层协议 采用请求 应 答的同步通讯模型实现 VSPP 协议定义了如下的 PDU 2 1 1 业务数据接口业务数据接口 D 该类接口简称 D Service Data 接口 供 VSP 与各个服务提供商之间取得业务数据的接 口 2 1 2 网络数据接口网络数据接口 N 该类接口简称 N Networking Management 接口 提供 VSP 系统与相关外部实体间的启 停会话 检测连接等操作 2 2 VSPP 协议会话描述协议会话描述 协议会话都采用应用服务方式 通讯协议采用 TCP IP 标准协议 双方平台均可作为客户端和服务端 如果语音平台的 网关作为 Client 发送请求 则各 SP 的网关为 Server 如果 SP 网关作为 Client 发送请求 则语音平台的网关为 Server ClientServerDB 各业务系 统的数据 库 请求包访问数据库 请求包 和 应答包 包 括包头和包体 应答包获取数据 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 7 页 共 18 页 由 Client 端发出业务请求 以请求包的形式传送至服务端 其中包括该项业务所需要的参 数信息 服务端处理相应的业务请求并以应答包的形式返回数据 下面是 VSPP 协议会话建立的过程 客户端 VSClient 建立与服务平台 VSServer 的 TCP IP 连接 尚未完成 绑定操作 客户端发送 bind rq 请求 服务器发回 bind rq resp 返回一个随机数 challenge 然后客户端将根据 challenge 生成的 response 发送回 VSServer 服务 器 最后 UASS 返回认证结果 如果认证成功 则会话建立完毕 否则断开连接 在会话期间 客户端发送一系列的 VSPP 业务命令 VSServer 服务器回复一 系列的应答 发送和回复顺序不需要一一对应 VSPP 协议会话解除的过程 VSClient 发送 unbind rq 命令 VSServer 回复一个 unbind rq resp 命令解除绑定 然后断开连接 VSClient VSServer bind rq bind rq resp bind rq sr bind rq sr resp unbind rq unbind rq resp 2 3 错误处理错误处理 所有的 VSPP 操作都是由一个请求 PDU 和对应的应答 PDU 组成 对于任何一个 VSPP 请求 PDU 接收实体必须返回应答 PDU 如果接收实体发现收到的 PDU 包含错误或因某种原因不能成功地完成指定的动作 接 收实体必须返回在包头部分的指定字段内包含适当错误码的应答 PDU 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 8 页 共 18 页 2 4 超时处理超时处理 为了提高协议双方的信息交换的效率 建议通信双方管理一个可配置的计时器 缺省 计时时间 30 秒 如果发现一定的时间间隔内双方没有联系 其中的一方可以主动地断开连 接 如果不希望断开连接而又担心对方断开连接可以发送 N enquire link 命令更改对方的 计时器 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 9 页 共 18 页 3 VSPP PDU 数据类型和格式定义数据类型和格式定义 3 1 VSPP PDU 数据类型定义数据类型定义 String字节串 如无特别说明则左齐右补空格 ASCII 码 32 字 节串的最后一字符不可为空格 Integer定长 String 它由一系列的 10 进制字符组成 0 9 右齐左补 0 ASCII 码 48 注意 当此类型字段字符值超过 4294967295 时 32 位无 符号整数的最大值 若将其转换为 32 位无符号整数会产生 溢出 程序员需要进行特别处理 Date8 位定长 String 格式 YYYYMMDD DateTime14 位定长 String 格式 YYYYMMDDHHMISS 3 2 VSPP PDU 格式概述格式概述 一个典型的 PDU 包如下表所示 VSPP PDU 包头 标志 头 heads ign len gth categor y sub c omm and opco de seq n o sp id service id operate id callingn umber called numb er errnocry t ype key no 25224104552020555 体包尾标志 bodytailsign 不定 不大于 64 128 字节2 PDU 包包括包头标志 包头 包体和包尾标志 包头标志固定为 包尾标志固 定为 包头是固定长度 包体的长度不定 各字段长度可以固定 也可以不定 双方 的请求数据包和应答数据包的包头结构是一致的 不同的是包体的定义 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 10 页 共 18 页 3 3 VSPP PDU 布局布局 下面是一个完整 PDU 的布局 VSPP PDU 域域长度长度类型类型说明说明 包头 标志 headsign2String固定为 length5Integer此域表示消息包的长度 包括包头和包尾 不包括包头标志和包尾标志 category2String01 D 接口 02 N 接口 sub command2String01 业务请求 02 业务请求应答 opcode4String操作码 取值参照附录 A3 seq no10Integer此域表示一个序列号 使用在异步通信 模式下 由消息发起者设定 应答者对 应给回此序列号 序列号范围 0000000000 9999999999 循环使用 sp id4String标志各个 SP 在语音平台的 ID 号 service id5String各 SP 的各个业务标志 从 00000 99999 operate id5String各业务的操作号 是各个业务过程中访 问数据的操作序号 callingnumber20String用户主叫号码 callednumber20String用户被叫号码 errno5String错误码 必需为数字 由应答方填写 错误码包括系统操作错误和业务处理错 误 错误码定义由 SP 提供 成功交易填 写 00000 cry type5String包体加密算法类型 00000 代表不加密 其他代表事先约定的加密类型 加密只 对包体进行 头 共 92 位 key no5String加密密钥序号 代表事先双方约定的加 密密钥的顺序号 Field 1String根据各个操作的业务需要设定长度和选 择使用 每个字段长度不大于 128 位 体 Field nString根据各个操作的业务需要设定长度和选 择使用 每个字段长度不大于 128 位 包尾 标志 tailsign2String固定为 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 11 页 共 18 页 注 n 不大于 64 3 4 VSPP PDU 的原子性的原子性 在本接口协议中 任意包体内容均为原子性操作 对于整个包体的处理只有全部成功 或全部失败两种结果 不应产生部分成功的结果 4 VSPP 包体定义包体定义 4 1 D 接口接口 PDU 包体定义包体定义 D 接口数据包最多包含 64 个字段 每个字段最大包含 128 个字节 由 SP 根据具体业 务和各业务取数据操作确定各字段长度 包体字段的定义有以下两种方式 a 包体字段定长 各个字段有长度表示 以上 XML 描述表示一个操作过程中包体收发的会话信息 operate id 00001 表示操作号 type 01 表示 pdu 包是语音平台主动发起 如果 type 02 表示 pdu 包是 SP 平台主动 发起 bodytype 01 表示 pdu 包各字段是定长的 bodytype 02 表示 pdu 包各字段是不定 长的 以分隔符分割各字段 包体结构如下 字段 1 字段 2 字段 3 字段 4 字段 X b 包体字段不定长 各个字段无长度表示 分隔符由 SP 自定义 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 12 页 共 18 页 以上 XML 描述表示一个操作过程中包体收发的会话信息 operate id 00002 表示操作号 type 01 表示 pdu 包是语音平台主动发起 如果 type 02 表示 pdu 包是 SP 平台主动 发起 bodytype 02 表示 pdu 包各字段是不定长的 以分隔符分割各字段 sep 表示分割符是 包体结构如下 字段 1 分割符 字段 2 分割符 字段 3 分割符 字段 4 分割符 字段 X 4 2 连接信息和包体定义的连接信息和包体定义的 XML 描述描述 SP 应该向平台提供的连接信息和包体定义的 XML 描述 连接信息的 XML 描述将每个 SP 的连接信息写入一个 xml 文件中 连接信息的 XML 描 述举例如下 文件命名为serverinfo xml 如 SP 的 ID 为 0001 文件名为 0001serverinfo xml sp id 代表 SP 的 ID 号 一个 SP 可以有多个 Server 包体定义的 XML 描述将每个 SP 的各个业务的包体描述写入一个 xml 文件文件名为 举 例如下 如果 SPID 为 0001 serviceid 为 00001 则业务文件名为 000100001service xml 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 13 页 共 18 页 sendbody 表示请求包 receivebody 表示回应包 servername chat1 表示 SP 服务器的信息 4 3 N 接口接口 PDU 包体定义包体定义 4 3 1 VSClient 端端 BIND 绑定发送请求操作绑定发送请求操作 域名域名长度长度类型类型描述描述 auth method2Integer 绑定采用的认证方法 01 CRAM MD5 02 99 保留未用 必需 参数 version flag2Integer 指明 VSPP 协议的版本号 如 10 表 示 1 0 版本 4 3 2 VSServer 端端 BIND 绑定验证请求操作绑定验证请求操作 域名域名长度长度类型类型描述描述 random number size4Integer 认证所采用的随机数大小 必需 参数 random numberMax 9000 String 认证所采用的随机数 为二进 制数 所有字符均有效 包括 空格 4 3 3 VSClient 端回复绑定验证请求操作端回复绑定验证请求操作 域名域名长度长度类型类型描述描述 client id20String 客户标识 response length 4Integer 认证所返回的响应数的大小必需 参数 responseMax 9000 String 认证所返回的响应数 为二进制数 所有字符均有效 包括空格 4 3 4 VSServer 端回复验证请求操作端回复验证请求操作 域名域名长度长度类型类型描述描述 client id20String 客户标识必需 参数 response4String 验证结果 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 14 页 共 18 页 4 3 5 N ENQUIRE LINK 检测通信连接操作检测通信连接操作 N enquire link 操作用于检测通信连接是否仍然有效 由 N enquire link 命令和 N enquire link resp 应答组成 通信连接建立后 如果较长时间双方都无数据交换 则客 户端发送 N enquire link 命令 则服务器端向客户端发送 N enquire link resp 响应 4 3 5 1 N ENQUIRE LINK 检测连接请求语法检测连接请求语法 除需要设定头部的域外 N enguire link 不需要其它的参数 4 3 5 2 N ENQUIRE LINK RESP 检测连接应答语法检测连接应答语法 除需要设定头部的域外 N enquire link 不需要其它的参数 4 3 6 N UNBIND 解除绑定操作解除绑定操作 N unbind 操作用于断开通信连接 由 N unbind 命令和 N unbind resp 应答组成 通信连接建立以后 客户端如果要停止通信 需要发送 N unbind 命令 服务器端收到 N unbind 命令后 向客户端发送 N unbind resp 相应 然后双方断开连接 5 VSPP PDU 包定义举例包定义举例 5 1 业务背景业务背景 某 SP 加载 外呼聊天 业务 用户 A 手机打入后 输入想要聊天的用户 B 的注册 ID 号 系统向 SP 取得相关业务数据后 外呼用户 B 手机并接通话路聊天 操作 语音平台向 SP 发出请求数据请求 在请求包中加入用户 A 手机号码 用户 B 注册 ID SP 向语音平台回复请求数据 在回复包中加入用户 B 手机号码及是否允许聊天 信息 5 2 包定义包定义 请求 PDU 的体格式如下 域名域名长度长度类型类型描述描述 bodyField120String 用户 B 注册 ID 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 15 页 共 18 页 回复 PDU 的体格式如下 域名域名长度长度类型类型描述描述 bodyField220String 用户 B 手机号码 同时回复包规定在包头 errno 字段中的错误码如下 错误码错误码含义含义 00000 成功 00001 请求用户没有注册用户 ID 00002 请求用户被被请求用户加入黑名单 00003 被请求用户注册 ID 不存在 00004 被请求用户没有注册手机号码 附录附录 1 PDU 应用码应用码 A1 分类码汇总 分类码汇总 category 分类 分类 category 值值描述描述 D 01 业务数据操作接口 N 02 网络管理接口 A2 子命令码汇总 子命令码汇总 sub command 子命令码 子命令码 sub command 值值描述描述 01 01 请求 02 02 请求应答 A3 操作码汇总 操作码汇总 opcode OPCodeCatalogSub Command OP ClassSub OP Code 01 D 01 请求 02 请求应答 0101 一般性业务 01绑定随机数 02 N 01 请求 02 请求应答 01绑定 02绑定核实 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 16 页 共 18 页 02 通用的错 误应答 01通用的错误应答 03检测连接01检测连接 04解除绑定01解除绑定 A4 消息状态码汇总 消息状态码汇总 command status 消息状态码消息状态码 command status 描述描述备注备注 0000成功 0001未知错误不知名错误都作为此类 注 1 2 3 字头代码仅为示例 附录附录 2 API 接口接口 初期 语音服务平台提供 Windows 操作系统下的 VSPP 接口 API 其它操作系统下的 API 根据实际应用情况确定 结构体定义结构体定义 包头结构体定义 其字段含义与 VSPP 协议中包头的描述一致 struct Packet Head unsigned intPACKETLENGTH unsigned char CATEGORY SOCKET CATEGORY LENGTH 1 unsigned char SUBCOMMAND SOCKET SUB COMMAND LENGTH 1 unsigned char OPCODE SOCKET OPCODE LENGTH 1 unsigned char SEQNO SOCKET SEQNO LENGTH 1 unsigned char SPID SOCKET SPID LENGTH 1 unsigned char SERVERID SOCKET SERVERID LENGTH 1 unsigned char OPERATEID SOCKET OPERATEID LENGTH 1 中国移动语音服务平台接口协议 VSPP V1 1 中国移动通信集团公司 第 17 页 共 18 页 unsigned char CALLINGNUMBER SOCKET CALLINGNUMBER LENGTH 1 unsigned char CALLEDNUMBER SOCKET CALLEDNUMBER LENGTH 1 unsigned char RESULT SOCKET ERROR LENGTH 1 unsigned char CRYTYPE SOCKET CRY TYPE LENGTH 1 unsigned char KEYNO SOCKET KEY NO LENGTH 1 各字段长度定义 define SOCKET LENGTH LENGTH 5 define SOCKET CATEGORY LENGTH 2 define SOCKET SUB COMMAND LENGTH 2 define SOCKET OPCODE LENGTH 4 define SOCKET SEQNO LENGTH 10 define SOCKET SPID LENGTH 4 define S