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