移动代理服务器MAS短信SOCKETAPI接口协议

1、移动代理服务器mas短信socket api 接 口协议v1.0嘉讯软件2006-3修订记录id修订历史修改人口期初稿v1.0陈铁钢2006-3-30初稿v2.0陶永江2007-12-14初稿v2陈宏海2008-9-271简介本协议用于mas与通过api接入mas的客户端的数据传输通讯。两者的数据传输通讯采 用tcp协议、短连接方式，mas为服务器方，tcp监听端口为73010缩略语清单：sapp(soket api peer to peer):嘉讯socket api接口 点对点协议client：所有通过socket api协议接入mas的客户端mas(information machine

2、)：信息机1.1 api原理socket api短信收发使用原理请参照mas产品发布时附带的文件mas移动信息机api2.0 开发手册。木文档不再垂复阐述。木文档解决的是如何通过tcp连接方式使jij socket apio1-2 sapp功能概述木协议主要提供以下两类业务操作：(1) client发送数据到mas典型的业务操作为发送短信到mas(2) client从mas接收数据典型的业务操作为接收mas发送过來的状态报告和mo短信2通信方式2.1短连接通信交互采川短连接方式。短连接是指通信双方右数据交互时，就建立一个tcp连接，数据发送完成后，则断开 此tcp连接，即每次tcp连接只完成一

3、对sapp消息的发送。通信双方以客八-服务器方式建立tcp连接，应答与请求在同一个连接中完成。系统采川客户/服务器模式，操作以客户端驱动方式发起连接请求，完成一次操作后关闭此连接。 client与mas之间消息发送片等待t秒厉未收到响应，应立即重发，再连续发送n1 次后仍未得到响应则停发。现阶段建议取值为：t=60秒，n=3。短连接的操作流程举例如图6所示：客八端/服务器建立tcp连接服务器/客户端sapp消息1对sapp消息1的响应拆除tcp连接建v/： tcp连接过程如下:sapp消息2对sapp消息2的响应拆除tcp连接图1短连接的操作流程建立连接：建立连接过程由客户端发起。如果建立连接

4、失败，重复发起连接，每次间隔 30秒。登录校验：连接建立成功后，client发送“连接请求”包到mas进行身份校验。注意, 每个api只支持单连接，不支持多连接。校验响应：如果验证成功，用户可以进行发送消息、接收状态报告、或者mo的操作。 如果校验失败，则发送失败响应包后主动断开连接，client收到失败响应包 厉也随之断开连接。如果校验成功，则发送成功响应包。发送消息：在client收到mas登录成功响应包后，client就开始发送submit消息。要 求每包号码记录不超过100个，如果盂耍发送的号码过多，则进 行多次上传。mo：建立连接后，可接收mo信息，如果等待10秒能未有消息获得，断开

5、连接，等 待卜次继续请求获取。状态报告：建立连接后，可接收状态报告信息，如果等待10秒能未有消息获得，断开 连接，等待下次继续请求获取。请求拆除连接：发送消息、mo接收、状态报告接收完成后，要求主动断开连接。2.2本协议中涉及的端口号端口号应用7301mas侦听端口，client连接该端口3消息定义3.1基本数据类型无符号整数unsigned integer3.2消息结构项目说明message header消息头（所有消息公共包头）message body消息体3.3 消息头格式(message header)字段名字节数类型描述7btal_le ngth4unsignedinteger消息总

6、长度（含消息头及消息体）comma ndd4unsignedinteger命令或响应类型seque nce_ld4unsignedinteger消息流水号，顺序累加,步长为1,循环使用（一 对请求和应答消息的流水号必须相同）version1unsignedinteger协议版本，目前版本填1reserved1unsig nedinteger保留字段，方便以后扩充，比如是否采川压缩 加密等3.4 client与mas间的消息定义client向作为服务器端的mas发起连接请求，只有在通过身份验证之后通过client才能 与mas之间进行业务数据传输。每个请求都有一个相应的应答返冋。3.4.1 连接

7、请求（connect）客八端与服务器端建立连接 connect (client mas)commanded: connect<?xml version=n1.0" encoding'田k'?>v!连接请求，保证只是合法用户连接到mas-><im apicode=utestn>vconn ect><encrypttype>o</encrypttype>v usr> user namev/usr>v pwd> 1234< /pwd></co nnect>&l

8、t;/im>字段解释：apicode： api编码，对应mas接口新增的接口编码。encrypttype：密码加密类型，0位不加密，1为我们选定的加密方式，其他数字留与扩展 usr：接口创建时的接口登录名pwd：接口创建时的接口沓录密码 connect_resp (mastclient)command_id: connect_resp<?xml version=n1.0n encoding'gbk”？> <im apicode=“test”>v! 通用应答><ge neral_resp><!结果0：正确1：其他错误一&

9、lt;res>0</res>v! 具体错误描述"><comment> 正确 v/comment></general_resp></im>字段解释：ftes:结果0：正确其他错误comment:具体错误描述3.4.2 发送消息(submit)服务器客八端处理模块发出消息请求，并返冋消息应答，需要注意的是发送的内容长度将不 超过260个文字(一个英文字母也算是一个字) submit (client tmas)conunand_id: submit<?xml version="1.0"

10、 encoding="gbk'?> <im apicode=,ftestf, ><sms>v!短信提交请求smjd:短信id, 0到99999999中的某一整数。确保唯-后可以用来找到对应的冋 执、回复content:短信内容，内容不超过260个汉字><submit smd=”12345" contenf f午三点有会，谢谢 合作” uii= ”www.si ”><!- mobile: b 的方号码->vline mobile' />vline mobile=h 139

11、00000001" /></submit></sms></im>字段解释：apicode： api编码，对应mas接口新增的接口编码。sm_id：短信id, 0到99999999中的某一整数。确保唯一后可以用来找到对应的回执、回 复.content：短信内容，内容不超过260个汉字（当是wap push短信时，该字段意思为title, 即wap push短信的标题）url:wap push短信的url地址。如果url不为空则该短信为wap push短信,为空表示该短 信是普通短信。url不需要加“http:/”前缀。mobile：手机号码，包

12、括移动、联通、小灵通号码。号码前不需要加86,小灵通号码格式为“区号+号码”，如075512345678。每个 包体可以包含多个手机号码，但是每个包最人请不要超过100个号码。注意：wap push短信url不能人于110字节，url和内容总长不能超过120字节。如果url超 过110字节，则mas接收后可能做异常处理不予发送，如果总长超过120字节，则发送时 标题内容将被截取。 submi t_resp (mastclient)command_id: submit_resp v?xml version'1.0“ encoding=,gbk,'?> <

13、imapicode="testn >v! 通用应答一<general_resp><!结果0：正确1：英他错误> <res>0</res>v!具体错误描述>字段解释:res:结杲0：正确仆：其他错误comment:具体错谋描述3.4.3mo(deli ver)ums根据ismg传来的mo消息，根据corpjd,把此mo转发给相应的客八端 deu ver (mastclient)conunand_id: deliver<?xml version=u1.0n encodings田k'?><i

14、m apicode=utesf, ><sms>< deliver mobile= sm_id=n1h content=h请假一天”/></sms></im>字段解释:mobile：发送短信的手机号码sm_id： mo短信的短信id content：短信内容 deli ver_resp (clienttmas)commandd: deliver_resp<?xml version=n1.0n encodings gbk'?> <im apicode =utestm>v!

15、通用应答<general_resp><!结果0：正确1：其他错误一<res>0</res><! 具体错课描述->3.4.4状态报告(report)状态报告，根据状态报告对判断最终川户是否接收到前提交的短消息 report (mastclient)commanded: report<?xml version=u1.0n encoding=,(®k,?><im apicode =“test”><sms><! 最终状态报告mobile:ib的号码，也就是用户的手机终端 sm_id:

16、对应于用户发送submit消息时的mt短信的短信id code:回执编码desc:回执说明< report mobile="quot; smd="1" code="0" desc=”ih确”/> </sms></im> report_resp(clie nttmas)commanded: report_resp<?xml version=n1.0" encoding=" gbk'?> <im apicode=utestn&g

17、t;< !通用应答><ge neral_resp><!结果0：正确其他错误><res>0</res>v!-具体错误描述-<comment> 正确 v/comment></ge neral_resp></im>3.4.5client 或 mas 请求拆除连接(terminate)terminate操作的r的是client或mas棊于某些原因决定拆除当前的应川层连接而发起 的操作。此操作完成后client与mas之间的应用层连接被释放，此后client若再要与mas 通信时应发起onnect操作。

18、client或mas以terminate.resp消息响应请求。 termi nate 消息定义(clientmas 或 mas 9 client)无消息体。3452 termi nate_resp 消息定义(clientmas 或 mas 9 client)无消息体。3.5系统定义3.4.6command_ld 定义消息command id 值说明connect0x00000001请求连接connect resp0x80000001请求连接应答terminate0x00000002终止连接termi nafe resp0x80000002终止连接应答submit0x000000

19、04提交短信submi t resp0x80000004提交短信应答deliver0x00000005短信下发deliver resp0x80000005下发短信应答repoft0x00000006状态报告report resp0x80000006状态报告应答3.5.1错误码使用说明对于错误码的处理，o始终衣示成功，其他表示失败，具体错误代码见附录的错误列表。3.4.7xml的解析方式xml的解析基本上分为sax和dom方式，sax方式有效率高但是代码稍复朵的缺点，dom 方式效率低但代码量少，xl观，考虑到系统的性能及以jn xml可能包含多业务的情况，衣 服务器端将采川sax方式。4附录4.1错误列表4.1.1 登录响应(connect_resp)i错误代码描述10101消息结构错10102非法的api code10103用户名密码错误10104版本不对10105系统忙，暂时不能登录1010