校讯通软件接口规范

1、 校讯通公话软件接口规范（V1.4）目录1介绍61.1目的61.2适用范围61.3缩略语62接口协议概述72.1GPRS协议72.2接口分类72.2.1普通公话接口72.2.2校园数据库接口72.2.3公话管理接口73数据类型和格式定义83.1数据类型定义83.2PDU格式概述83.3UASP PDU布局84公话PDU接口定义104.1“PHONE_AUTHEN”公话认证104.1.1公话认证(由公话发给Server端)104.1.2公话认证应答(由Server发给公话)104.2“STDT_CARD_LOGIN”学生卡登录操作104.2.1学生卡登录请求语法(由公话发给Server端)104

2、.2.2学生卡登录应答语法(由Server发给公话)104.3“STDT_NO_LOGIN”学号登录操作114.3.1学号登录请求语法(由公话发给Server端)114.3.2学号登录应答语法(由Server发给公话端)114.4“STDT_READ_MSG”学生卡读取留言操作114.4.1学生卡读取留言请求语法(由公话发给Server端)114.4.2学生卡读取留言应答语法(由Server发给公话)124.5“CALL_BILLING”通话话单操作124.5.1通话话单请求语法(由公话发给Server端)124.5.2通话话单应答语法(由Server发给公话)124.6“STDT_SIGN_

3、RECS”学生签到记录134.6.1学生签到记录请求语法(由公话发给Server端)134.6.2学生签到记录应答语法(由Server发给公话)134.7“CONNECT_STATUS”网络连接状态查询134.7.1网络连接状态查询语法(由公话发给Server端)134.7.2网络连接状态查询应答语法(由Server发给公话)135公话管理接口定义145.1“ABT_STATUS”公话状态查询145.1.1公话状态查询语法(由Server端发给公话)145.1.2公话状态查询应答语法(由公话发给Server)145.2“EDIT_ABT_SET”修改终端设置145.2.1修改终端参数请求语法(

4、由Server发给公话)145.2.2修改终端参数应答语法(由公话发给Server)155.3“SET_ABT_RESET”设置终端重启155.3.1设置终端重启请求语法(由Server发给公话)155.3.2设置终端重启应答语法(由公话发给Server)155.4“UPDATE_NOTICE”程序更新通知155.4.1程序更新通知语法(由Server端发给公话)155.4.2程序更新通知应答语法(由公话发给Server)155.5“UPDATE_PROGRAM”程序更新165.5.1程序更新语法(由Server端发给公话)165.5.2程序更新应答语法(由公话发给Server)165.6“S

5、YNC_ID_UPDATE”亲情号码更新同步165.6.1亲情号码更新同步请求语法(由Server发给公话)165.6.2亲情号码更新同步应答语法(由公话发给Server)165.7“SEND_ID_UPDATE”亲情号码更新数据发送175.7.1亲情号码更新数据发送请求语法(由Server发给公话)175.7.2亲情号码更新数据发送应答语法(由公话发给Server)175.8“ID_DELETE_ALL”亲情号码删除（全部删除）175.8.1亲情号码删除请求语法(由Server发给公话)175.8.2亲情号码删除应答语法(由公话发给Server)175.9“ID_DELETE_ONE”亲情号

6、码删除卡信息（删除某个卡的卡信息）185.9.1亲情号码删除卡信息请求语法(由Server发给公话)185.9.2亲情号码删除卡信息应答语法(由公话发给Server)185.10“SET_TALK_DURATION”设置单次通话时长185.10.1设置单次通话时长请求语法(由Server发给公话)185.10.2设置单次通话时长应答语法(由公话发给Server)185.11“CLASS_LIST” 班级列表185.11.1班级列表请求语法(由公话发给Server)185.11.2班级列表应答语法(由Server发给公话)195.12“STUDENT_LIST” 学生列表195.12.1学生列表

7、请求语法(由公话发给Server)195.12.2学生列表应答语法(由Server发给公话)195.13“TEACHER_CALL_BILLING”教师通话话单操作195.13.1教师通话话单请求语法(由公话发给Server)195.13.2教师通话话单应答语法(由Server发给公话)205.14“ME_STATUS_UPDATE”终端状态上报205.14.1终端状态上报请求语法(由公话发给Server)205.14.2终端状态上报应答语法(由Server发给公话)205.15“STDT_BUS_SIGN”学生校车签到。215.15.1学生签到记录请求语法(由公话发给Server端)215.

8、15.2学生签到记录应答语法(由Server发给公话)216参数取值定义226.1功能号（func_no）取值221 介绍1.1 目的中国移动校讯通业务可允许用户在学校使用公话享受移动服务。校讯通公话接口协议定义了校讯通业务中校园公话与校讯通公话服务器之间的接口协议及公话与读卡器的通讯协议。校讯通公话接口采用GPRS或有线的通讯方式。1.2 适用范围本文定义了校讯通公话接口协议，规定了请求应答的会话方式、报文格式和语法，适用于外部实体开发商利用校讯通公话接口访问校讯通公话服务时参考。1.3 缩略语l SC (Service Center)：数据采集中心l ABT (Child-caring S

9、ystem Teminal)：校讯通公话终端l SRFC (Student RF Card)：学生专用的RF卡2 接口协议概述2.1 GPRS协议l 校讯通公话接口采用GPRS协议与移动SC进行数据通讯。本质上是基于TCP/IP协议之上的应用层协议，以TCP协议进行数据传输，采用请求/应答的同步通讯模型实现。l SC使用公网地址，在某个端口侦听校讯通公话连接，可以使用认证方式建立连接。2.2 接口分类公话接口分为以下几类：2.2.1 普通公话接口提供普通公话服务。如校讯通卡登录，读取留言，通话话单上传等。2.2.2 校园数据库接口校园学校签到/刷卡设备使用。2.2.3 公话管理接口提供公话设备

10、的系统管理接口。包括更新通知，程序更新，公话状态查询等。3 数据类型和格式定义3.1 数据类型定义类型说明String字节串。如无特别说明则左齐右补空格（ASCII码32），字节串的最后一字符不可为空格。VST变化的字符串。字符串的最大长度由协议给出。字符串的具体长度根据PDU包头的length字段给出。因此VST必须放在每个包的最后一个。Integer定长String, 它由一系列的10进制字符组成（0-9），右齐左补0（ASCII码48）。注意：当此类型字段字符值超过时（32位无符号整数的最大值），若将其转换为32位无符号整数会产生溢出，程序员需要进行特别处理。Date8位定长String

11、，格式:YYYYMMDDDateTime14位定长String，格式:YYYYMMDDHHMISSnDataType某种数据类型的列表。前面的n用2位Integer表示。Binary二进制数据3.2 PDU格式概述一个典型的信息格式如下表所示：UASP PDU头体lengthfunc_noseq_noBody424=(length值 10)4=(length值 4)3.3 UASP PDU布局下面是一个完整PDU的布局：BOSS.UAS PDU 域长度类型说明头command_length4Integer此域表示消息包的长度，UASP PDU的最大包体长度为9999字节func_no2Stri

12、ng操作码，取值参照第Error! Reference source not found.节seq_no4Integer此域表示一个序列号，使用在异步通信模式下，由消息发起者设定，应答者对应给回此序列号。序列号范围：00009999，循环使用。同步方式下该域保留。体必需参数MixedPDU里必须包含的参数注：seq_no字段在同步中也可以使用，使用该字段作为请求包和响应包的对应字段。任何交易发起时，由client端产生seq_no，server收到请求后在响应包头中填入此字段内容，client端收到响应后，同发送包的该字段内容进行校验，以确认是该发送包的响应，然后继续处理。4 公话PDU接口定

13、义4.1 “PHONE_AUTHEN”公话认证4.1.1 公话认证(由公话发给Server端)序号域名长度类型描述1DeviceId18String公话ID2Reserved8String保留4.1.2 公话认证应答(由Server发给公话)序号域名长度类型描述1valid_flag1Integer1:认证成功0:认证失败注：1.终端在连上服务器时要进行一次终端认证,而且要接收到认证成功后才可继续进行其他的交互动作。2.如果终端在未认证时连接进来,SEVER端要发送认证失败的包给公话,然后再断开连接（可防止未知设备连到服务器）。4.2 “STDT_CARD_LOGIN”学生卡登录操作4.2.1

14、 学生卡登录请求语法(由公话发给Server端)序号域名长度类型描述1Device_msisdn15String公话手机号2Device_id18String公话ID3card_id18String学生卡号4student_id18String学生ID5request_time14DateTime请求时间注：1.学生卡号以十六进制上传。2学生ID字段和公话手机号字段暂时保留，服务器收到这两个字段暂时不处理4.2.2 学生卡登录应答语法(由Server发给公话)序号域名长度类型描述1valid_flag1Integer学生卡是否有效0 无效 (0 有效)1为学生卡2为教师卡2Family_num

15、2Integer亲情号码个数3Family_msisdn15nString亲情号码列表4Family_relation4nString亲情号码关系（汉字形式）5message_num4Integer留言数目6System_time14DateTime系统时间7Talking_duration6Integer拨打时长0 限制呼出0 可以通话时长注：如果亲情号码个数为，则亲情号码列表和关系不用发送，n=0。4.3 “STDT_NO_LOGIN”学号登录操作4.3.1 学号登录请求语法(由公话发给Server端)序号域名长度类型描述1Device_id18String公话ID2student_id1

16、8String学生ID3request_time14DateTime请求时间4.3.2 学号登录应答语法(由Server发给公话端)序号域名长度类型描述1valid_flag1Integer学号是否有效0 无效 1 有效2Family_num2Integer亲情号码个数3Family_msisdn15nString亲情号码列表4Family_relation4nString亲情号码关系（汉字形式）4.4 “STDT_READ_MSG”学生卡读取留言操作 4.4.1 学生卡读取留言请求语法(由公话发给Server端)序号域名长度类型描述1Device_msisdn15String公话手机号2De

17、vice_id18String公话ID3card_id18String学生卡号4student_id18String学生ID5request_time14DateTime请求时间4.4.2 学生卡读取留言应答语法(由Server发给公话)序号域名长度类型描述1Message_len4Integer留言长度2MessageMessage_lenString留言内容3重复(1,2)message_num-1次 (message_num的定义见4.1.2的)4.5 “CALL_BILLING”通话话单操作4.5.1 通话话单请求语法(由公话发给Server端)序号域名长度类型描述1device_ms

18、isdn15String公话手机号2device_id18String公话ID3card_id18String学生卡号4student_id18String学生ID5Call_times2Integer话单个数6start_time14DateTime开始呼叫时间7called_duration6Integer通话时长8other_party24String被叫号码9重复(6,7,8)Call_times-1次注：学生ID字段和公话手机号字段暂时保留，服务器收到这两个字段暂时不处理4.5.2 通话话单应答语法(由Server发给公话)序号域名长度类型描述1valid_flag1Integer学

19、生卡是否有效0 无效 1 有效注：话单包由终端发出后T秒未收到响应，终端应该立即重发，或终端发送不成功，秒后应该立即重发，建议T=30。4.6 “STDT_SIGN_RECS”学生签到记录4.6.1 学生签到记录请求语法(由公话发给Server端)序号域名长度类型描述1device_id18String公话ID2card_id18String学生卡号3student_id18String学生ID4start_time14DateTime签到时间4.6.2 学生签到记录应答语法(由Server发给公话)序号域名长度类型描述1valid_flag1Integer学生卡是否有效0 无效 1 有效注：

20、签到包由终端发出后T秒未收到响应，终端应该立即重发，或终端发送不成功，秒后应该立即重发，建议T=30。为了提高签到包的发送效率，建议采用并发方式发送，加以滑动窗口流量控制，滑动窗口参数W可配置，建议W=10，即接收方在应答前一次收到的消息最多不超过10个包（流量控制在1K字节以内）。4.7 “CONNECT_STATUS”网络连接状态查询4.7.1 网络连接状态查询语法(由公话发给Server端)序号域名长度类型描述4.7.2 网络连接状态查询应答语法(由Server发给公话)序号域名长度类型描述注：当信道上没有数据传输时，通信双方应每隔时间C发送链路检测包以维持此连接，当链路检测包发出超时时

21、间T后未收到响应，应立即再发送链路检测包，再连续发送N-1次后仍未得到响应则断开此连接。现阶段建议取值为：C=分钟，T=60秒，N=3。4.8 “STDT_REMOTE_SIGN”学生签到记录4.8.1 学生签到记录请求语法(由公话发给Server端)序号域名长度类型描述1device_id18String公话ID2card_id18String学生卡号3student_id18String学生ID4start_time14DateTime签到时间5in_out1String0 进校 1 出校4.8.2 学生签到记录应答语法(由Server发给公话)序号域名长度类型描述1valid_flag1

22、Integer学生卡是否有效0 无效 1 有效注：签到包由终端发出后T秒未收到响应，终端应该立即重发，或终端发送不成功，秒后应该立即重发，建议T=30。为了提高签到包的发送效率，建议采用并发方式发送，加以滑动窗口流量控制，滑动窗口参数W可配置，建议W=10，即接收方在应答前一次收到的消息最多不超过10个包（流量控制在1K字节以内）。5 公话管理接口定义5.1 “ABT_STATUS”公话状态查询5.1.1 公话状态查询语法(由Server端发给公话)序号域名长度类型描述1Cur_time14DateTimeServer端的当前时间5.1.2 公话状态查询应答语法(由公话发给Server)序号域

23、名长度类型描述1Device_id18String设备ID2VersionInfo18String版本信息3MinitorInfo72String预留监控信息注:版本信息的格式为 VERx.xx YYYY/MM/DD 例如(VER1.00 2004/05/10)MinitorInfo前3个字节分别代表市电状态、手柄线状态、外壳门状态第1个字节代表市电状态： 1为外电，2为电池供电，3为电池电压低第2个字节代表手柄线状态：1为正常状态，2为继线状态第3个字节代表外壳门状态：1为关闭状态，2为打开状态第55个字节到第72个字节（后18个字节）为短消息版本信息，格式为：VERx.xx YYYY/MM

24、/DD 例如(VER1.00 2004/05/10)5.2 “EDIT_ABT_SET”修改终端设置5.2.1 修改终端参数请求语法(由Server发给公话)序号域名长度类型描述1edit_flag3String是否修改对应的参数1 修改0 不修改第1个字节对应 IP第2个字节对应 PORT第3个字节对应 ID2sc_ip20StringSC IP地址3sc_port10StingSC 端口号4device_id18String终端ID号5.2.2 修改终端参数应答语法(由公话发给Server)序号域名长度类型描述1valid_flag1Integer0-接收失败 1-接收成功5.3 “SET

25、_ABT_RESET”设置终端重启 5.3.1 设置终端重启请求语法(由Server发给公话)序号域名长度类型描述1device_id18String终端号5.3.2 设置终端重启应答语法(由公话发给Server)序号域名长度类型描述1valid_flag1Integer0-接收失败 1-接收成功5.4 “UPDATE_NOTICE”程序更新通知5.4.1 程序更新通知语法(由Server端发给公话)序号域名长度类型描述1Version18String要更新的版本号2Length6Integer更新程序的长度5.4.2 程序更新通知应答语法(由公话发给Server)序号域名长度类型描述1val

26、id_flag1Integer目前版本情况0 目前版本和要更新的版本不一致,要进行更新1 目前版本和要更新的版本一致,无需再更新2Version18String目前公话的版本号5.5 “UPDATE_PROGRAM”程序更新5.5.1 程序更新语法(由Server端发给公话)序号域名长度类型描述1Data1024Binary要更新的程序数据注：seq_no字段表示程序更新数据包的序号，从0开始,依次递增5.5.2 程序更新应答语法(由公话发给Server)序号域名长度类型描述1valid_flag1Integer0- 数据接收错误1- 数据接收正确注：seq_no字段表示程序更新数据包的序号5

27、.6 “SYNC_ID_UPDATE”亲情号码更新同步5.6.1 亲情号码更新同步请求语法(由Server发给公话)序号域名长度类型描述注：每次亲情号码更新前，需先进行同步请求，有应答才发更新数据。5.6.2 亲情号码更新同步应答语法(由公话发给Server)序号域名长度类型描述1valid_flag1Integer0-未就绪 1-就绪5.7 “SEND_ID_UPDATE”亲情号码更新数据发送5.7.1 亲情号码更新数据发送请求语法(由Server发给公话)序号域名长度类型描述1Data_nums4Integer更新数据的条数2type1Integer数据的处理方式0-删除 1-增加3car

28、d_id18String卡号4card_type1Integer卡属性0-学生 1-教师5Family_msisdn15String亲情号码6Family_relation4String亲情号码关系（汉字形式）7重复(2,3,4,5,6) Data_nums -1次注：如果要传输的数据量较大，则进行分次传输。一次传输的数据条数不大于20条（数据包大小控制在1K内）。5.7.2 亲情号码更新数据发送应答语法(由公话发给Server)序号域名长度类型描述1valid_flag1Integer0-接收失败 1-接收成功5.8 “ID_DELETE_ALL”亲情号码删除（全部删除）5.8.1 亲情号码

29、删除请求语法(由Server发给公话)序号域名长度类型描述1Card_type1Integer0-学生 1-教师注：卡属性为时，删除所有学生的卡信息，卡属性为时，删除所有教师的卡信息5.8.2 亲情号码删除应答语法(由公话发给Server)序号域名长度类型描述1valid_flag1Integer0-删除失败 1-删除成功5.9 “ID_DELETE_ONE”亲情号码删除卡信息（删除某个卡的卡信息）5.9.1 亲情号码删除卡信息请求语法(由Server发给公话)序号域名长度类型描述1Card_type1Integer0-学生 1-教师2card_id18String卡号注：卡属性为时，删除指定

30、学生的卡ID信息，卡属性为，删除指定教师的卡ID信息5.9.2 亲情号码删除卡信息应答语法(由公话发给Server)序号域名长度类型描述1valid_flag1Integer0-删除失败 1-删除成功5.10 “SET_TALK_DURATION”设置单次通话时长5.10.1 设置单次通话时长请求语法(由Server发给公话)序号域名长度类型描述1talk_duration6Integer默认单次通话时长注：设置为0表示不限制。5.10.2 设置单次通话时长应答语法(由公话发给Server)序号域名长度类型描述1valid_flag1Integer0-接收失败 1-接收成功5.11 “CLAS

31、S_LIST” 班级列表5.11.1 班级列表请求语法(由公话发给Server)序号域名长度类型描述1device_id18String公话设备编号2card_id18String教师的IC卡号5.11.2 班级列表应答语法(由Server发给公话)序号域名长度类型描述1Class_num2Integer最多99个2Class_id8NStringN的值是班级数量3Class_name20NStringN的值是班级数量5.12 “STUDENT_LIST” 学生列表5.12.1 学生列表请求语法(由公话发给Server)序号域名长度类型描述1device_id18String公话设备编号2Cl

32、ass_id8String班级ID5.12.2 学生列表应答语法(由Server发给公话)序号域名长度类型描述1Student_num2Integer最多99个2Student_id18NStringN的值是学生数量3Student_name10NStringN的值是学生数量5.13 “TEACHER_CALL_BILLING”教师通话话单操作5.13.1 教师通话话单请求语法(由公话发给Server)序号域名长度类型描述1device_msisdn15String公话手机号2device_id18String公话ID3card_id18String教师卡号5Call_times2Intege

33、r话单个数6Student_id18String学号6start_time14DateTime开始呼叫时间7called_duration6Integer通话时长8other_party24String被叫号码5.13.2 教师通话话单应答语法(由Server发给公话)序号域名长度类型描述1valid_flag1Integer成功:1 失败:05.14 “ME_STATUS_UPDATE”终端状态上报5.14.1 终端状态上报请求语法(由公话发给Server)序号域名长度类型描述1device_id18String终端ID2Imsi_num18String设备sim卡imsi3Imei_num

34、18String模块imei4power_status1Integer市电状态： 1为外电，2为电池供电，3为电池电压低5handset_status1Integer手柄线状态：1为正常状态，2为继线状态6door_status1Integer外壳门状态：1为关闭状态，2为打开状态7reader_allcnt2Integer读卡器总数量8reader_count2Integer在线读卡器数量9reader_num2Integer在线读卡器号码：00 ：内置读卡器01-99 ：外置读卡器10重复第9项reader_count-1次11reserved预留数据，填充空白，长度为（160-57-2-2- reader_count*2）保证一个数据包长度为160字节注：终端状态上报默认24小时上报一个包，时间从第一次开机上报之后计算5.14.2 终端状态上报应答语法(由Server发给公话)序号域名长度类型描述1valid_flag1Integer0-上报失败 1-上报成功2next_time2Integer下次上报