SMP开放接口协议.docVIP

SMPSMP 开发接口协议规范开发接口协议规范 (V1.00)(V1.00) 华为技术有限公司华为技术有限公司 20022002 年年 0606 月月 2 前言前言 本规范适用于营帐系统和 SMP 间的开放接口。 本规范目前定稿为版本 1.00，如果以后本规范内容有任何修改，使用本规范 的各方应以最新版本为准。 在开发前，请详细阅读本文档。 3 目录 目录目录3 一、一、SMPSMP 与营帐系统组网方式与营帐系统组网方式 4 二、二、SCSC 接口协议结构接口协议结构4 三、三、SCSC 接口协议接口协议4 3.1 SC 接口协议的消息4 3.1.1 SC 接口协议业务消息的编码.5 3.1.2 SC 心跳消息的编码6 3.2 SC 接口协议的参数编码6 3.2.1 版本号6 3.2.2 服务名6 3.2.3 终端标识.7 3.2.4 会话 ID7 3.2.5 会话控制字7 3.2.6 事务 ID7 3.2.73.2.7 事务控制字事务控制字7 3.33.3 操作员的权限管理操作员的权限管理.7 3.43.4 MMLMML 命令命令8 3.4.13.4.1 MMLMML 命令格式命令格式.8 3.4.23.4.2 MMLMML 命令使用的字符集命令使用的字符集.11 3.4.33.4.3 MMLMML 语法语法11 3.4.43.4.4 MMLMML 特性特性13 3.4.53.4.5 MMLMML 命令集命令集.13 3.53.5 SCSC 接口协议的应用说明接口协议的应用说明14 3.5.13.5.1 概念概念14 3.5.23.5.2 业务系统与业务系统与 SMPSMP 交互的完整过程交互的完整过程14 附录附录 A A SMPSMP 与营帐系统的消息交互图与营帐系统的消息交互图 16 4 一、 SMP 与营帐系统组网方式 SMP 与营帐系统的组网方式如图 1-1 所示。 二、 SC 接口协议结构 SC 接口的下层采用 TCP/IP 协议。接口协议栈如图 2 所示。 三、 SC 接口协议 3.1 SC 接口协议的消息 SC 接口协议的业务消息用于传递用户的操作信息，其结构如下图所示： SC SMP 省公司营业服务器 TCP/IP 物理连接 接口协议 SC TCP/IP 物理连接 接口协议 图图 2 2 SCSC 接口协议栈接口协议栈 消息开始 标志 消息长度消息头会话头事务头操作信息校验和 消息开始 标志 消息发送顺序 SMP SC 接口 营帐系统 1 SC 接口 营帐系统 2 图图 1 1 组网方式组网方式 SC 接口：SMP 与营帐系统的接口。 SC接口协议的心跳消息用于检测业务中心与SMP间的连接是否正常，在检测到连接空 闲120秒后发送。SC心跳消息结构如下图所示： 3.1.1 SC 接口协议业务消息的编码 消息开始标志消息开始标志 消息开始标志用于确定消息的开始和结束，长度为4Byte。编码为SC。 消息长度消息长度(4Byte)(4Byte) 消息长度用来指出从消息头到操作信息的总长度。长度值用16进制字符(0-F)表示 的4位整数来表示。消息长度取值范围为0到65000(0000-FFFF)。 消息头消息头(20Byte)(20Byte) 消息头包含以下参数： - 版本号：用来识别SC接口的协议版本。编码为4个八位位组的字符串。目前的版 本为1.00。 - - 终端标识：用于标识接入SMP的业务系统。编码为8个八位位组的字符串。 - 服务名：操作员所要请求的服务。编码为8个八位位组的字符串。 会话头会话头(18Byte)(18Byte) 会话是接入SMP的业务系统与SMP之间的一个虚拟连接(逻辑连接)，唯一标识业务 系统到SMP的一次有效登录。会话头包含以下部分： 会话ID：16进制字符(0-F)表示的32位整数(8B)，从1开始。 会话控制字：6个八位位组的字符串(6B)。 保留（4B） 事务头事务头(18Byte)(18Byte) 事务是接入SMP的业务系统与SMP之间的一次交易。一次交易可以由一到多个MML命 令组成(可以在一到多条消息中)，交易的结果也可以通过一到多个MML ACK返回。事务 必定归属于某个会话。事务头由以下部分组成： 事务ID：16进制字符(0-F)表示的32位整数(8B) ，从1开始。 事务控制字：6个八位位组的字符串(6B)。 会话 ID会话控制字 保留 比特发送顺序 消息开始 标志 消息长度填充内容校验和 消息发送顺序 6 保留（保留（4B4B） 操作信息操作信息 操作信息的内容为MML命令，MML命令的格式和内容见3.4。如果MML命令的长度不是 4的倍数，则在后面填充空格补齐。 校验和校验和(8Byte(8Byte) 校验和的算法如下： 对“消息头会话头事务头操作信息”按 32 位异或，对异或结果取反后的值 为校验和（8 个 16 进制的明文）。 3.1.2 SC 心跳消息的编码 消息开始标志消息开始标志 消息开始标志用于确定消息的开始和结束，长度为4Byte。编码为SC。 消息长度消息长度(4Byte)(4Byte) 消息长度用来指出从消息头到操作信息的总长度。长度值用16进制字符(0-F)表示的4位整数来表示。 消息长度固定取值为4。 - 心跳消息心跳消息(4Byte)(4Byte) 心跳消息内容为HBHB。 - 校验和校验和(8Byte)(8Byte) 编码固定为B7BDB7BD。 具体参见后面 1.5.2.2 消息流。心跳消息的发送时间间隔为 120 秒。三次心跳接收不到视为连接中断。 3.2 SC 接口协议的参数编码 参数编码应符合以下原则： 1） 16 进制字符表示的 16 位或 32 位整数是将高八位位组在前，低八位位组在后。 2） 如果字符串不满规定长度，用空格填充； 3） 除了消息的开始标志和校验和，其它部分不允许出现不可见字符（如控制字符） 。 3.2.1 版本号 目前的版本号为：1.00。如果以后有协议升版，按新版本进行编码即可。 3.2.2 服务名 服务名由打斜英文字母组成。举例如下 PPC：PPC 用户服务 事务 ID事务控制字 保留 比特发送顺序 7 VPN: WVPN 用户服务 FPH：FPH 用户服务 CHRG：PPC 充值服务 MSISDN：号码资源管理 SRVM：SMP 系统通用服务（登陆时使用该服务名） PPS：PPS 业务 注意：一般服务名是 MML 操作吗的中间一个单词，如果 CREATE PPS MSUB 的服务名就是 PPS 3.2.3 终端标识 终端标识的编码为 PPZZABCD，其中，PP 和 ZZ 可以是字母和数字的任意组合，ABCD 只能是数字。 PP 表示业务区（以省、自治区和直辖市为单位），PP 的编码在由集团公司统一分 配。 ZZ 表示归属于大区的子区（以地/市为单位），ZZ 的编码由各省、自治区和直辖市 自行分配。 ABCD 表示终端序号，由各子区自行分配。 3.2.4 会话 ID 会话 ID 由业务中心自行分配，用于唯一标识一个由业务中心发起的会话，不同的会 话有不同的 ID 值并且不等于 0 即可。在 SMP 端，则根据 TCP 连接(物理连接)和会话(逻辑 连接)ID 两者唯一确定消息发送的通道。 3.2.5 会话控制字 会话控制字的编码如下： DlgLgn：请求登录 DlgCon：会话保持 DlgEnd：会话结束 保留： 4Byte 3.2.6 事务 ID 事务 ID 由业务中心自行分配，用来标识一个事务，在同一会话中不同的事务必须 有不同的 ID 值并且不等于 0。 3.2.73.2.7 事务控制字事务控制字 TxBeg：开始事务 TxCon：事务继续 TxEnd：事务结束 保留： 4Byte 3.33.3 操作员的权限管理操作员的权限管理 对操作员的权限管理由业务系统完成。原则上，根据操作员可进行的操作内容将操作 员分为三级。 高级操作员：直接从SMAP接入且可进行所有SMP支持的操作的操作员； 中级操作员：地/市业务系统所属的操作员，能进行大部分操作； 低级操作员：所有营业系统的操作员，只能完成一些操作。 高级操作员的权限鉴别由SMP完成，其可以允许的操作原则上由SMP的功能决定。中级 和低级操作员的权限鉴别由业务系统完成，具体操作内容见3.4。 3.43.4 MMLMML 命令命令 3.4.13.4.1 MMLMML 命令格式命令格式 3.4.1.13.4.1.1 MMLMML 命令命令 一个命令从命令码开始。命令码规定了系统应该执行的功能。如果要求进一步的信 息，那么在命令码后跟参数部分，并用：(冒号)把命令码和参数部分分隔开。参数部分由 参数块定义。采用分号来分隔多条命令。在单条命令中，分号可以省略。 参数块 命令码 ： 多条命令暂不提供。多条命令暂不提供。 3.4.1.23.4.1.2 命令码命令码 由命令前缀和命令体组成。 命令码不区分大小写。 命令前缀主要用来标识某条命令是否为回应命令，如果为回应命令则前缀为ACK，通 过冒号与命令体分开。命令前缀还可为“MON”，表示一条检测命令，或“NOTIFY”表示 通知消息。MON前缀可暂不提供。 命令体最多由三个标识符组成，它们之间用空格分隔开。 命令码意义： 标识 符 标识 符 标识 符 spsp23 命令前 缀 1 ： 图图 3.8 命令格式命令格式 9 标识符 1： 长度最大为 8 的标识符，表示执行动作，如 ADD, DISP, MOD, CRE。 标识符 2：长度最大为 8 的标识符，表示执行动作所处的服务，如：PPC, FPH, SYS。 标识符 3：长度最大为 8 的标识符，表示执行动作的对象实体，如：ACNT, OPER。 举例如下： 列出 PPC 帐号的命令：DISP PPC ACNT : MSISDN= 3.4.1.33.4.1.3 参数块参数块 参数块为执行命令码中指定的功能所必须的信息。参数块中的信息根据具体的命令 由特定的一些参数来表示。 如果参数块包含两个或多个参数，用逗号把它们分隔开。 所有参数都是按名字定义的。 用户的输入顺序不会影响命令的执行。 3.4.1.3.13.4.1.3.1 参数定义参数定义 参数包括参数名和一个参数值，之间用=（等号）分隔开来。 如果没有参数值，那么相应的参数名和分隔符“=（等号）”以及跟随该参数的分隔 符“,（逗号）”也要省略掉。 在参数省略的情况下，认为缺省值已被指定。也可以不省略参数，而用一个指定的 参数值来代表缺省值。 3.4.1.3.23.4.1.3.2 参数名称参数名称 参数名称用最多 16 个字符的标识符表示。 参数名不区分大小写。 3.4.1.3.33.4.1.3.3 参数值参数值 参数值由一个信息单元或信息单元的复合组成。 10 3.3.1.3.43.3.1.3.4 信息单元信息单元 3.4.1.3.53.4.1.3.5 复合信息单元复合信息单元 把信息单元组合起来就可以在一个命令的一个参数中输入一个以上的信息单元。如 前所述，这里不考虑复合信息单元的组合。以后凡是提到信息单元的组合，指的就是简单 信息单元的组合。SC接口应支持灵活的信息单元组合方式。 在一个参数值内能够指明几个信息单元，办法是把它们用&（与号）分隔开。例如： 5&9指简单的信息单元5和9。 对于一个连续序列的信息单元（隐含增量值=1），只要写出最低的和最高的信息单 元，中间插入&（与号与号）就可以表示这些变元。例如：5&9指简单信息单元 5、6、7、8、9。示号码数为10000的号码段。 可以把隐含增量值明确地写在最高的信息单元之后，用+（加加）分隔开。例如： 5&9+2指简单信息单元5、7、9。与增量值有关的命令可暂不要求。 当需要时也可以使用上述规则的其他组合。例4：5&9+2&10指简单信息单元 5、7、9、10。 组合的数目仅受限于协议中单条消息的大小，目前是65000BYTE。 3.4.1.3.63.4.1.3.6 缺省参数缺省参数 一个命令的参数可以是必备参数、可选参数、缺省参数。必备参数是执行该命令必 须给出的参数，可选参数是在使用该命令时可以选择输入的参数；缺省参数是在没有输入 该参数时系统自动使用缺省值的参数。 使用缺省参数遵循以下原则： 标识符 十进制数 日期 时间 字符串 11 (1) 对于能提供缺省值的参数都应该指定为缺省参数（如增加一个用户时非关键参 数都可以指定一个缺省值）； (2) 同一命令中缺省参数的缺省值是唯一的； (3) 不同命令中含义相同的缺省参数可以有不同的缺省值； (4) 缺省值应该是该参数在大多数情况下使用的参数值 3.4.23.4.2 MMLMML 命令使用的字符集命令使用的字符集 3.4.2.13.4.2.1 字母字母 包括从A到Z的全部大写字母，a到z的全部小写字母， *符和#符。 3.4.2.23.4.2.2 数字数字 包括从0到9的全部十进制数码。 3.4.2.33.4.2.3 分隔字符分隔字符 这些特殊的字符用于分隔输入对话中的各个单元。 冒号(：)用于把命令名称或命令码同第一个参数分隔开。 连号()用于分隔同一命令名称内的助记符，仅限于位域类型。 等号()把参数名称或参数码与其第一项参数值分开。 逗号(，)用于分隔各参数。 &用于分隔同一参数内的各等效符。 &用于分隔同一等效符内范围的上、下极限值。 撇号()将数值指示符与数值分开。 分号(；)用于分隔多条命令。 3.4.2.43.4.2.4 数制指示符数制指示符 B二进制 O八进制 D十进制 H十六进制 N数字字符串 3.4.2.53.4.2.5 特殊字符特殊字符 双引号(“)在助记符中划出某段正文的字符串 空格分隔命令码，也可以用于改善可读性 回车换行本系统不使用，但也可以用于改善可读性 3.4.33.4.3 MMLMML 语法语法 3.4.3.13.4.3.1 标识符标识符 标识符是由一个或几个字符组成的字符串。该字符串以字母或下划线打头，其后仅跟以数字 和或字母以及下划线，例如UPDATE、NO7。 字母|下划线 字母|下划线 数字 12 3.4.3.23.4.3.2 数值数值 3.4.3.2.13.4.3.2.1 十进制数十进制数 十进制数由一组字符组成，它包括一个或几个数字，而且在前面要有专门的字符组D（D撇） 。信息单元的缺省数制是十进制的，D可以忽略。 3.4.3.2.23.4.3.2.2 数字数字 数字字符串用于表达一些十进制数无法表达的，但其本身又是由数字组成的信息。如手机号 和PPC卡号。 3.4.3.33.4.3.3 字符串字符串 字符串（或正文串）允许输入文字正文，包括任意的定界符，这些定界符如果在正文串之外 输入是有其语法意义的。正文串由一串字符组成，字符个数可以是0个或多个，并用“（双引号） 把它在首尾两端括起来。正文串可以含有所有字符。字符串中不能出现双引号。 字符(不包括“) “ 图图 3.13.1 标识符标识符 图图 3.2 十进制数十进制数 N 数字 图 3.3（数字字符串） 图图 3.6 数字字符串数字字符串 图图 3.4 字符串字符串 数字 D 13 3.4.3.43.4.3.4 日期日期 日期的表示格式是使用“号把按全数字形式写成日历日期引起来。日历日期应按下列次序书 写：年、月、日。年由四位十进制数字组成，月由两位十进制数字组成，日由两位十进制数字组 成。年和月之间及月和日之间用连字号连接。 例如：1997 年 1 月 16 日应按下列方法书写： “1997-01-16“ 3.4.3.53.4.3.5 时间时间 时间表示格式采用 24 小时计时系统。用“号把数字和冒号表示的时刻引起来。时刻元素的顺 序从高位到低位（从左到右）：时、分、秒。小时用两位十进制数表示，范围从 00 到 23，并包 括 23；分用两位十进制数字表示，范围从 00 到 59，并包括 59；秒用两位十进制数表示，范围从 00 到 59，并包括 59。 例如：12 时 25 分 01 秒表示如下： “12:25:01“ 3.4.3.63.4.3.6 日期及时间日期及时间 日期及时间表示格式采用日期格式加上时间格式表示，中间用一个空格分隔。 例如：1997 年 1 月 16 日 12 时 25 分 01 秒表示如下： “1997-01-16 12:25:01“ 3.4.43.4.4 MMLMML 特性特性 3.4.4.13.4.4.1 批量操作批量操作 批操作是指对一批同类型的对象按照某种要求使用一个命令一次对其进行处理（增删改、查 询、操作等）。例如：对PPC用户业务一次性开户。 批操作应当具备的特性： (1) 批量操作必须提供进度反馈功能； (2) 批量操作应当在一个小的批量执行完毕后，输出一个执行结果，并在全部处理完毕后， 输出统计结果。 (3) 批操作命令可以与其它普通命令并行执行。 3.4.4.23.4.4.2 批命令批命令 批命令是指将多个命令作为一个整体发送给设备，设备对这个命令集合的处理方法是顺序执 行。批命令要求人机命令系统具有以下功能： (1) 识别批命令的功能； (2) 缓存批命令，直到接受到完整的批命令； (3) 在指定时间内，未接受到完整命令，应当取消整批命令； (4) 批命令和普通命令并行执行。 3.4.4.33.4.4.3 提示确认提示确认 重要操作应当提示用户确认，经用户确认后，才执行。命令应当启动一个定时器，在超时时 自动取消命令。 3.4.53.4.5 MMLMML 命令集命令集 MML 命令共有预付费用户服务，预付费充值服务，预付费充值卡服务，日志服务，号 码资源管理，报表管理，文件管理，操作员管理，通用服务，通用错误等十类。其中，通 用错误命令是在操作员输入错误时由 SMP 返回的。 14 根据不同操作员的权限，低级操作员（营业系统的操作员）和中级操作员（地市业务 系统操作员）可以执行的 MML 命令有所不同。每条 MML 命令在 SMP 都有一个确认命令， MML 命令及其确认的具体内容详见附录 A。 3.53.5 SCSC 接口协议的应用说明接口协议的应用说明 3.5.13.5.1 概念概念 3.5.1.13.5.1.1 连接连接 业务系统与SMP在发送消息之前，必须与SMP建立TCP/IP SOCKET连接；而在业务系统 不再需要与SMP进行交互之后，必须拆除与SMP的SOCKET连接；在空闲时段，可以保持与 SMP的连接，此时只发送心跳消息。 注意：外部系统与注意：外部系统与SMPSMP对接时，必须采用长连接。对接时，必须采用长连接。 3.5.1.23.5.1.2 会话会话 业务系统与SMP在建立SOCKET连接之后，可以在此连接上创建一到多个会话，如要在 新创建的会话上发送MML命令，必须执行登录命令并且在SMP返回登录成功的消息之后，此 会话才可被使用。在不再需要此会话时，必须执行退出登录命令，以通知SMP清除此会话 的信息。 会话由业务系统主动发起创建，使用会话ID作为标识，此ID由业务系统管理，必须 保证在同一个SOCKET连接上的会话ID不能重复。 3.5.1.33.5.1.3 事务事务 业务系统可以通过可用的会话向SMP发送消息，以执行各种操作完成业务管理的功能， 根据一个单一功能所需的MML命令和MML ACK的个数可以将操作分成四类：单命令单返回、 单命令多返回、多命令单返回、多命令多返回。由于SMP具有同时执行多个操作的能力， 业务系统可以连续发送多批命令(命令可为以上四种操作中的任意组合)，然后等待执行结 果的返回。为了标识不同操作(每一次操作的整个过程可看作一次交易)之间的MML命令与 MML ACK，使用事务ID来进行标识。事务ID由业务系统管理，必须保证在同一个会话中仍 未结束的事务ID不重复。 3.5.1.43.5.1.4 消息消息 消息是业务