爱贝通公话软件接口规范.docx
《爱贝通公话软件接口规范.docx》由会员分享，可在线阅读，更多相关《爱贝通公话软件接口规范.docx（25页珍藏版）》请在冰豆网上搜索。
爱贝通公话软件接口规范
校迅通接口规范
（V1.0）
修订记录
日期
版本
说明
作者
注：
1
介绍
1.1目的
中国移动校讯通业务可允许用户在学校使用公话享受移动服务。
校讯通公话接口协议定义了校讯通业务中校园公话与公话服务器之间的接口协议及公话与读卡器的通讯协议。
校讯通公话接口采用GPRS通讯方式。
1.2适用范围
本文定义了校讯通公话接口协议，规定了请求应答的会话方式、报文格式和语法，适用于外部实体开发商利用校讯通公话接口访问校讯通公话服务时参考。
1.3缩略语
SC（ServiceCenter）：
数据采集中心
ABT（Child-caringSystemTeminal）：
校讯通公话终端
SRFC（StudentRFCard）：
学生专用的RF卡
2
接口协议概述
2.1GPRS协议
校讯通公话接口采用GPRS协议与移动SC进行数据通讯。
本质上是基于TCP/IP协议之上的应用层协议，以TCP协议进行数据传输，采用请求/应答的同步通讯模型实现。
SC使用公网地址，在某个端口侦听校讯通公话连接，可以使用认证方式建立连接。
2.2接口分类
公话接口分为以下几类：
·普通公话接口
提供普通公话服务。
如IC/ID卡登录，读取留言，通话话单上传等。
·校园数据库接口
校园学校签到/刷卡设备使用。
·公话管理接口
提供公话设备的系统管理接口。
包括更新通知，程序更新，公话状态查询等。
2.3终端开机基本流程
·校讯通开机上电后，会自动用GPRS登陆校讯通平台，登陆平台后终端首先会发送“公话认证[取值:
10]”消息给服务器，服务器回应“公话认证[取值:
10]”消息并自动往终端下发“公话状态查询[取值:
82]”消息给终端，终端回应“公话状态查询[取值:
82]”给服务器完成双方握手。
·如果双方握手不成功，终端会自动断开与服务器的连接并自动重连。
·完成以上动作后校讯通就可正常工作，终端会在空闲时每3分钟主动发送心跳包（“网络连接状态查询[取值:
05]”消息）给服务器，服务器需回应心跳包。
服务器依靠心跳包判断终端是否在线。
3数据类型和格式定义
3.1数据类型定义
类型
说明
String
字节串。
如无特别说明则左齐右补空格（ASCII码32），字节串的最后一字符不可为空格。
VST
变化的字符串。
字符串的最大长度由协议给出。
字符串的具体长度根据PDU包头的length字段给出。
因此VST必须放在每个包的最后一个。
Integer
定长String,它由一系列的10进制字符组成（‘0’---‘9’），右齐左补‘0’（ASCII码48）。
注意：
当此类型字段字符值超过‘4294967295’时（32位无符号整数的最大值），若将其转换为32位无符号整数会产生溢出，程序员需要进行特别处理。
Date
8位定长String，格式:
YYYYMMDD
DateTime
14位定长String，格式:
YYYYMMDDHHMISS
n[DataType]
某种数据类型的列表。
前面的n用2位Integer表示。
Binary
二进制数据
3.2PDU格式概述
一个典型的信息格式如下表所示：
UASPPDU
头
体
length
func_no
seq_no
body
4
2
4
=（length值–10）
4
=（length值–4）
3.3UASPPDU布局
下面是一个完整PDU的布局：
BOSS.UASPDU域
长度
类型
说明
头
command_length
4
Integer
此域表示消息包的长度，UASPPDU的最大包体长度为9999字节
func_no
2
String
操作码，取值参照第6.1节
seq_no
4
Integer
此域表示一个序列号，使用在异步通信模式下，由消息发起者设定，应答者对应给回此序列号。
序列号范围：
0000－9999，循环使用。
同步方式下该域保留。
体
必需参数
Mixed
PDU里必须包含的参数
注：
seq_no字段在同步中也可以使用，使用该字段作为请求包和响应包的对应字段。
任何交易发起时，由client端产生seq_no，server收到请求后在响应包头中填入此字段内容，client端收到响应后，同发送包的该字段内容进行校验，以确认是该发送包的响应，然后继续处理。
4
公话接口定义
4.1公话认证[取值:
10]
公话认证（由公话发给Server端）
序号
域名
长度
类型
描述
1
DeviceId
18
String
公话ID
2
Reserved
8
String
保留
公话认证应答（由Server发给公话）
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
1:
认证成功
0:
认证失败
注：
1.终端在连上服务器时要进行一次终端认证,而且要接收到认证成功后才可继续进行其他的交互动作。
2.如果终端在未认证时连接进来,SEVER端要发送认证失败的包给公话,然后再断开连接（可防止未知设备连到服务器）。
4.2“STDT_CARD_LOGIN”学生卡登录[取值:
01]
“STDT_CARD_LOGIN”学生卡登录请求语法（公话发给服务器）
序号
域名
长度
类型
描述
1
Device_msisdn
15
String
公话手机号
2
Device_id
18
String
公话ID
3
card_id
18
String
学生卡号
4
student_id
18
String
学生ID
5
request_time
14
DateTime
请求时间
“STDT_CARD_LOGIN”学生卡登录应答语法
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
学生卡是否有效
0无效（>0有效）
1为学生卡
2为教师卡
2
Family_num
2
Integer
亲情号码个数
3
Family_msisdn
15
n[String]
亲情号码列表
4
Family_relation
4
n[String]
亲情号码关系
（汉字形式）
5
message_num
4
Integer
留言数目
6
System_time
14
DateTime
系统时间
注：
如果亲情号码个数为０，则亲情号码列表和关系不用发送，n=0。
4.3“STDT_READ_MSG”学生卡读取留言[取值:
02]
“STDT_READ_MSG”学生卡读取留言请求语法
序号
域名
长度
类型
描述
1
Device_msisdn
15
String
公话手机号
2
Device_id
18
String
公话ID
3
card_id
18
String
学生卡号
4
student_id
18
String
学生ID
5
request_time
14
DateTime
请求时间
“STDT_READ_MSG”学生卡读取留言应答语法
序号
域名
长度
类型
描述
1
Message_len
4
Integer
留言长度
2
Message
Message_len
String
留言内容
3
重复（1,2）message_num-1次（message_num的定义见4.1.2的）
4.4“CALL_BILLING”通话话单[取值:
03]
“CALL_BILLING”通话话单请求语法
序号
域名
长度
类型
描述
1
device_msisdn
15
String
公话手机号
2
device_id
18
String
公话ID
3
card_id
18
String
学生卡号
4
student_id
18
String
学生ID
5
Call_times
2
Integer
话单个数
6
start_time
14
DateTime
开始呼叫时间
7
called_duration
6
Integer
通话时长
8
other_party
24
String
被叫号码
9
重复（6,7,8）Call_times-1次
“CALL_BILLING”通话话单应答语法
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
学生卡是否有效
0无效1有效
4.5“STDT_SIGN_RECS”学生签到记录[取值:
04]
学生签到记录请求语法
序号
域名
长度
类型
描述
1
device_id
18
String
公话ID
2
card_id
18
String
学生卡号
3
student_id
18
String
学生ID
4
start_time
14
DateTime
签到时间
学生签到记录应答语法
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
学生卡是否有效
0无效1有效
注：
为加快考勤上报速度，终端采用滑动窗口方式进行考勤上报，一次最多能同时
上报7条考勤记录。
4.6“CONNECT_STATUS”网络连接状态查询[取值:
05]
网络连接状态查询语法（由公话发给Server端）
序号
域名
长度
类型
描述
网络连接状态查询应答语法（由Server发给公话）
序号
域名
长度
类型
描述
4.7“STDT_NO_LOGIN”学号登录操作[取值:
07]
“STDT_NO_LOGIN”学号登录请求语法
序号
域名
长度
类型
描述
1
Device_id
18
String
公话ID
2
student_id
18
String
学生ID
3
request_time
14
DateTime
请求时间
“STDT_NO_LOGIN”学号登录应答语法
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
学号是否有效
0无效1有效
2
Family_num
2
Integer
亲情号码个数
3
Family_msisdn
15
n[String]
亲情号码列表
4
Family_relation
4
n[String]
亲情号码关系
（汉字形式）
5
公话管理接口定义
5.1“UPDATE_NOTICE”程序更新通知[取值:
80]
“UPDATE_NOTICE”程序更新通知语法（由Server端发给公话）
序号
域名
长度
类型
描述
1
Version
18
String
要更新的版本号
2
Length
6
Integer
更新程序的长度
“UPDATE_NOTICE”程序更新通知应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
目前版本情况
0目前版本和要更新的版本不一致,要进行更新
1目前版本和要更新的版本一致,无需再更新
2
Version
18
String
目前公话的版本号
5.2“UPDATE_PROGRAM”程序更新[取值:
81]
“UPDATE_PROGRAM”程序更新语法（由Server端发给公话）
序号
域名
长度
类型
描述
1
Data
1024
Binary
要更新的程序数据
注：
seq_no字段表示程序更新数据包的序号，从0开始,依次递增
“UPDATE_PROGRAM”程序更新应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
数据接收错误
数据接收正确
注：
seq_no字段表示程序更新数据包的序号
5.3“ABT_STATUS”公话状态查询[取值:
82]
“ABT_STATUS”公话状态查询语法（由Server端发给公话）
序号
域名
长度
类型
描述
1
Cur_time
14
DateTime
Server端的当前时间
“ABT_STATUS”公话状态查询应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
Device_id
18
String
设备ID
2
VersionInfo
18
String
版本信息
3
MinitorInfo
72
String
预留监控信息
注:
版本信息的格式为VERx.xxYYYY/MM/DD例如（VER1.002004/05/10）
MinitorInfo前3个字节分别代表市电状态、手柄线状态、外壳门状态
第1个字节代表市电状态：
1为外电，2为电池供电，3为电池电压低
第2个字节代表手柄线状态：
1为正常状态，2为继线状态
第3个字节代表外壳门状态：
1为关闭状态，2为打开状态
第55个字节到第72个字节（后18个字节）为短消息版本信息，格式为：
VERx.xxYYYY/MM/DD例如（VER1.002004/05/10）
5.4“GET_ADMIN_PWD”读取管理员密码[取值:
92]
读取管理员密码请求语法（由Server发给公话）
序号
域名
长度
类型
描述
1
device_id
18
String
公话ID
读取管理员密码应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
Valid_flag
1
Integer
0-设备号无效
1-设备号有效
2
Pwd
10
String
密码内容
5.5“SET_ADMIN_PWD”设置管理员密码[取值:
93]
设置管理员密码请求语法（由Server发给公话）
序号
域名
长度
类型
描述
1
device_id
18
String
公话ID
2
Pwd
10
String
新密码内容
设置管理员密码应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
Valid_flag
1
Integer
0-设置失败1-设置成功
5.6“EDIT_ABT_SET”修改终端设置[取值:
94]
修改终端参数请求语法（由Server发给公话）
序号
域名
长度
类型
描述
1
edit_flag
3
String
是否修改对应的参数
1修改
0不修改
第1个字节对应IP
第2个字节对应PORT
第3个字节对应ID
2
sc_ip
20
String
SCIP地址
3
sc_port
10
Sting
SC端口号
4
device_id
18
String
终端ID号
修改终端参数应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
0-接收失败1-接收成功
5.7“SET_ABT_RESET”设置终端重启[取值:
95]
设置终端重启请求语法（由Server发给公话）
序号
域名
长度
类型
描述
1
device_id
18
String
终端号
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
0-接收失败1-接收成功
设置终端重启应答语法（由公话发给Server）
5.8亲情号码更新同步[取值:
83]
亲情号码更新同步请求语法（由Server发给公话）
序号
域名
长度
类型
描述
注：
每次亲情号码更新前，需先进行同步请求，有应答才发更新数据。
亲情号码更新同步应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
0-未就绪1-就绪
5.9亲情号码更新数据发送[取值:
84]
亲情号码更新数据发送请求语法（由Server发给公话）
序号
域名
长度
类型
描述
1
Data_nums
4
Integer
更新数据的条数
2
type
1
Integer
数据的处理方式
0-删除1-增加
3
card_id
18
String
卡号
4
card_type
1
Integer
卡属性
0-学生1-教师
5
Family_msisdn
15
String
亲情号码
6
Family_relation
4
String
亲情号码关系
（汉字形式）
7
重复（2,3,4,5,6）Data_nums-1次
注：
如果要传输的数据量较大，则进行分次传输。
一次传输的数据条数不大于20条（数据包大小控制在1K内）。
亲情号码更新数据发送应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
0-接收失败1-接收成功
5.10亲情号码删除（全部删除）[取值:
85]
亲情号码删除请求语法（由Server发给公话）
序号
域名
长度
类型
描述
1
Card_type
1
Integer
0-学生1-教师
注：
卡属性为０时，删除所有学生的卡信息，卡属性为１时，删除所有教师的卡信息
亲情号码删除应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
0-删除失败1-删除成功
5.11亲情号码删除卡信息（删除某个卡信息）[取值:
86]
亲情号码删除卡信息请求语法（由Server发给公话）
序号
域名
长度
类型
描述
1
Card_type
1
Integer
0-学生1-教师
2
card_id
18
String
卡号
注：
卡属性为０时，删除指定学生的卡ID信息，卡属性为１，删除指定教师的卡ID信息
亲情号码删除卡信息应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
0-删除失败1-删除成功
5.12发送短消息[取值:
06]
发送短消息请求语法（由公话发给Server端）
序号
域名
长度
类型
描述
1
device_id
18
String
公话ID
2
card_id
18
String
学生卡号
3
Device_msisdn
15
String
目标手机号
4
Request_time
14
DateTime
请求时间
5
Sms_Asicc_Cont
140
String
短消息（Asicc编码）
发送短消息应答语法（由Server发给公话端）
序号
域名
长度
类型
描述
1
valid_flag
1
Integer
0-发送失败
1-发送成功
5.13更新短消息类型[取值:
89]
更新短消息类型请求语法（由Server发给公话）
序号
域名
长度
类型
描述
1
Sms_type
2
Integer
短消息类型号
2
Type
1
Integer
1-更新（增加）2-删除
3
Sms_type_text
12
String
短消息类型提示内容
更新短消息类型应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
Valid_flag
1
Integer
0-更新失败1-更新成功
2
Sms_type
2
Integer
短消息类型号
5.14更新短消息[取值:
90]
更新短消息请求语法（由Server发给公话）
序号
域名
长度
类型
描述
1
Sms_type
2
Integer
短消息类型号
2
Sms_id
2
Integer
短消息索引号
2
Type
1
Integer
1-更新（增加）2-删除
3
Sms_Text_Cont
140
String
短消息内容（asicc字符）
4
Sms_Unicode_Cont
140
String
短消息内容（unicode编码）
更新短消息应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
Valid_flag
1
Integer
0-更新失败1-更新成功
2
Sms_type
2
Integer
短消息类型号
3
Sms_id
2
Integer
短消息索引号
5.15更新短消息版本[取值:
91]
更新短消息版本请求语法（由Server发给公话）
序号
域名
长度
类型
描述
1
Version
18
String
短消息版本号
注:
版本信息的格式为VERx.xxYYYY/MM/DD例如（VER1.002004/05/10）
更新短消息版本应答语法（由公话发给Server）
序号
域名
长度
类型
描述
1
Valid_flag
1
Integer
0-更新失败1-更新成功
5.16巡检注册与修改手机号[取值:
62]
巡检注册与修改手机号请求语法（由公话发给Server）
序号
域名
长度
类型
描述
1
Dev_IMEI
20
String
IMEI
2
TeleNum
11
String
巡检员手机号码
巡检注册与修改手机号应答语法（由Server发给公话）
序号
域名
长度
类型
描述
1
valid_flag
1
Intege
升级会员 