移动信息机SOCKETAPI接口协议

1、移动信息机socket api接口协议v1.0嘉讯软件2006-3修订记录id修订历史修改人口期初稿v1.0陈铁钢2006-3-301简介本协议用于im与通过api接入im的客户端的数据传输通讯。两者的数据传输通讯采用 tcp协议、短连接方式，im为服务器方，tcp监听端口为7301 o缩略语清单：sapp(soket api peer to peer):嘉讯socket api接口 点对点协议client：所有通过socket api协议接入im的客户端im(information machine)：信息机1.1 api原理socket api短信收发使用原理请参照1m产品发布时附带的文件1

2、m移动信息机ap12.0开 发手册。木文档不再重复阐述。木文档解决的是如何通过tcp连接方式使用socket apio1.2 sapp功能概述本协议主要提供以下两类业务操作:(1) client发送数据到im典型的业务操作为发送短信到im(2) client从im接收数据典型的业务操作为接收im发送过來的状态报告和mo短信2通信方式2.1短连接通信交互采川短连接方式。短连接是指通信双方有数据交互时，就建立一个tcp连接，数据发送完成后，则断开 此tcp连接，即每次tcp连接只完成一对sapp消息的发送。通信双方以客户-服务器方式建立tcp连接，应答与请求在同一个连接屮完成。系统采用客户/服务器

3、模式，操作以客户端驷动方式发起连接请求，完成一次操作后关闭此连接。client与im之间消息发送后等待t秒后未收到响应，应立即重发，再连续发送n-1次后仍未得到响应则停发。现阶段建议取值为：t=60秒，n=3o短连接的操作流程举例如图6所示：客户端/服务器 建立tcp连接服务器/客户端vsapp消息1对sapp消息i的响应拆除tcp连接建立tcp连接sapp消息2对sapp消息2的响应拆除tcp连接图1短连接的操作流程过程如f：建立连接：建立连接过程山客八端发起。如果建立连接失败，重复发起连接，每次间隔30秒。登录校验：连接建立成功后，client发送“连接请求”包到im进行身份校验。注意，

4、每个api只支持单连接，不支持多连接。校验响应：如果验证成功，用八可以进行发送消息、接收状态报告、或者m0的操作。 如果校验失败，则发送失败响应包后主动断开连接，client收到火败响应包 后也随z断开连接。如果枝验成功，则发送成功响应包。发送消息：在client收到im登录成功响应包后,client就开始发送submit消息。要求 每包号码记录不超过100个，如果需要发送的号码过多，则述行 多次上传。mo：建立连接后，对接收mo信息，如果等待10秒能未有消息获得，断开连接，等 待下次继续请求获取。状态报告：建立连接后，可接收状态报告信息，如果等待10秒能未有消息获得，断开 连接，等待下次继续

5、请求获取。请求拆除连接：发送消息、mo接收、状态报告接收完成后，要求主动断开连接。22本协议中涉及的端口号端口号应用7301im侦听端口，client连接该端口3消息定义3.1基本数据类型unsigned integer无符号整数3.2消息结构项目说明message header消息头（所有消息公共包头）message body消息体3.3 消息头格式(message header)字段名字节数类型描述7btal_le ngth4unsignedinteger消息总长度（含消息头及消息体）comma ndd4unsignedinteger命令或响应类型seque nce_ld4unsigned

6、integer消息流水号，顺序累加,步长为1,循环使用（一 对请求和应答消息的流水号必须相同）version1unsignedinteger协议版本，目前版本填1reserved1unsig nedinteger保留字段，方便以后扩充，比如是否采川压缩 加密等3.4 client与i m间的消息定义client向作为服务器端的im发起连接请求，只有在通过身份验证之后通过client才能 与im之间进行业务数据传输。每个请求都有一个相应的应答返冋。3.4.1 连接请求（connect）客八端与服务器端建立连接 connect (client im)commanded: connec

7、t<?xml version="1.0n encoding*' utf-8"?> v!连接请求，保证只是合法用户连接到<im apicode=t>vconn ect><encrypttype>o</encrypttype>v usr> user namev/usr>v pwd> 1234< /pwd></co nnect></im>字段解释：apicode：接 口编码 0-9encrypttype：密码加密类型，0位不加密，1为我们选定的加密方式，其他数字留与

8、扩展 usr：接口创建时的接口登录名pwd：接口创建时的接口沓录密码 connect_resp (i mtclient)command_id: connect_resp<?xml version=n1.0n encoding=,'utf-8,'?> <im apicode=n1n>v! 通用应答><general_resp><!结果0：正确1：其他错误一<res>0</res>v! 具体错误描述"><comment> 正确 v/comment></ge

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

10、d, 0到99999999中的某一整数。确保唯-后可以用来找到对应的冋 执、回复content:短信内容，内容不超过260个汉字><submit smd=”12345" contenf f午三点有会，谢谢 合作” uii= ”www.si ”><!- mobile: b 的方号码->vline mobile' />vline mobile=hquot; /></submit></sms></im>字段解释：apicode：接 口编码 0-9sm_id

11、：短信id, 0到99999999中的某一整数。确保唯一后可以用来找到对应的回执、回 复.content：短信内容，内容不超过260个汉字（当是wap push短信时，该字段意思为title, 即wap push短信的标题）url:wap push短信的url地址。如果url不为空则该短信为wap push短信,为空表示该短 信是普通短信。url不需要加“http:/”前缀。mobile：手机号码，包括移动、联通、小灵通号码。号码前不需要加86,小灵通号码格式为“区号+号码”，如075512345678。每个 包体可以包含多个手机号码，但是每个包最人请不要超过100个号码。注意：wap pus

12、h短信url不能人于110字节，url和内容总长不能超过120字节。如果url超 过110字节，贝ijim接收后可能做异常处理不予发送，如杲总长超过120字节，则发送吋标 题内容将被截取。 submi t_resp (i mtclient)command_id: submit_resp<?xml version="1.0n encoding=" utf-8" ?> <im apicodet >v! 通用应答一<general_resp><!结果0：正确1：英他错误><res>0</re

13、s>v!具体错误描述>字段解释:res:结杲0：正确仆：其他错误comment:具体错谋描述3.4.3mo(deli ver)ums根据ismg传来的mo消息，根据corpjd,把此mo转发给相应的客八端 deuver (imclient)conunand_id: deliver<?xml version=u1.0n encoding=,utf-8h?><im apicode="1m ><sms>< deliver mobile= sm_id=n1h content=h请假一天”/>&

14、lt;/sms></im>字段解释:mobile：发送短信的手机号码sm_id： mo短信的短信id content：短信内容 deli ver_resp (client® m)command_id: deliver_resp<?xml version=n1.0n encodings utf-8h?> <im apicode ="1">v! 通用应答<ge neral_resp><!结果0：正确其他错误一<res>0</res><! 具体错课描述->3.4

15、.4状态报告(report)状态报告，根据状态报告对判断最终川户是否接收到前提交的短消息 report (imtclient)commanded: report<?xml version=u1.0n encoding=,utf-8,?><im 即icode = h1n><sms><! 最终状态报告mobile:ib的号码，也就是用户的手机终端 sm_id:对应于用户发送submit消息时的mt短信的短信id code:回执编码desc:回执说明< report mobile="quot; smd=

16、"1" code="0" desc=”ih确”/> </sms></im> report_resp(clientti m)commanded: report_resp<?xml version=n1.0n encoding' utf-8n?> <im apicode=n1n>< !通用应答><ge neral_resp><!结果0：正确其他错误><res>0</res>v!-具体错误描述-<comment>

17、正确 v/comment></ge neral_resp></im>3.4.5client 或 i m 请求拆除连接(termi nate)terminate操作的口的是client或im基于某些原因决定拆除当前的应川层连接而发起的 操作。此操作完成后client与im之间的应用层连接被释放，此后client若再要与im通信吋 应发起onnect操作。client或im以terminate_resp消息响应请求。 termi nate 消息定义(clientim 或 im 9 client)无消息体。3452 termi nate_resp 消息定义

18、(clientim 或 im 9 client)无消息体。3.5系统定义3.4.6command_ld 定义消息command id 值说明connect0x00000001请求连接connect resp0x80000001请求连接应答terminate0x00000002终止连接termi nafe resp0x80000002终止连接应答submit0x00000004提交短信submi t resp0x80000004提交短信应答deliver0x00000005短信下发deliver resp0x80000005下发短信应答repoft0x00000006状态报告report res

19、p0x80000006状态报告应答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非法的apicode10103用户名密码错误10104版本不对10105系统忙，暂时不能登录10106该apicode已被