中国电信短消息网关协议smgp协议v.doc

中国电信集团公司公司标准CT/T 1-2023基于固定电话网的信息终端及综合信息系统技术规范第七分册 短消息网关（SMGP）协议 V1.32023-04-30发布 2023-04-30实行中国电信集团公司 发布目 录前 言31合用范围42引用标准43缩略语44SMGP概述44.1.SMGP功能44.2.SMGP定义44.3.SMGP通信流程55SMGP数据包定义75.1.数据包结构75.2.请求标记说明75.3.包体结构86编码说明166.1.短消息格式代码表166.2.收费类型代码表166.3.短消息状态表166.4.Err错误代码表176.5.Status错误代码表177基于SMGP协议的API函数18附录A 基于SMGP协议的API函数说明19(提醒的附录)19A.1基本规定19A.2 API数据结构说明（以C语言为例）20A.3 API函数说明22A 3.7查询短消息流量（SMGPQuery可选）26A.4配置SMGP API26A.5短信的自动分割功能27A.6错误代码含义28 前 言本标准介绍综合信息平台系统短消息网关和服务提供商内容提供商（SPCP）之间、短消息网关和短消息网关之间的通信协议。本协议简称SMGP(Short Message Gateway Protocol)。本标准起草单位： 中国电信集团公司、中国电信集团公司上海研发中心本标准重要起草人： 特别感谢：亚信科技中国有限公司在本协议制订过程中的大力支持和帮助。1 合用范围本协议合用于短消息网关开发商和短消息服务提供商内容提供商。2 引用标准SMPP (Short Message Peer to Peer Protocol Specification) v3.4 3 3 缩略语见总册4 SMGP概述4.1. SMGP功能网关通信SMGP协议是短消息服务提供商内容提供商与短消息网关，以及短消息网关与短消息网关之间的通信协议。SMGP可以实现以下功能：(1) 服务提供商内容提供商向综合信息平台综合信息系统短消息用户发送短消息，例如邮件告知、天气预报等。(2) 综合信息平台综合信息系统短消息用户向服务提供商内容提供商点播信息，例如查询股票查询信息、航班信息等。(3) 服务提供商内容提供商以某个短消息用户的身份向综合信息平台综合信息系统短消息用户发送传情信息，例如图片传情、音乐传情等。(4) 综合信息平台综合信息系统短消息用户发送的短消息通过短消息网关前转发送给异地的短消息用户。4.2. SMGP定义网关通信SMGP协议是一个基于数据包的交互式协议，底层通过TCP/IP协议传递数据。每个数据包都包含请求标记，代表数据包的用途。服务提供商内容提供商与短消息网关或者短消息网关与短消息网关之间采用cClient-/serverServer的方式交互信息，客户端向服务器端发送一个请求包，服务器端向客户端返回回应包。客户端发送的所有请求包都包含一个唯一的序列号，服务器端返回的回应包也带有相应的序列号，以便客户辨认这是哪一个请求的回应。客户端和服务器端之间可以采用长连接或者短连接的方式通信。假如采用短连接，客户端必须以发送者、接受者或收发者的身份登录到服务器，通信完毕后断开连接。假如采用长连接，一旦认证通过建立连接，客户端与服务器端可以随时通信，在一定期间内两者之间没有发送合法的请求包，连接就中断。4.3. SMGP通信流程网关与ICPCP之间通信连接采用端标语8890，网关与网关通信连接采用端标语8900。4.3.1. SMGP登录模式 在SMGP协议的一个会话中客户端可以采用三种登录方式与服务器端相连：发送模式（send mode）、接受模式（receive mode）和收发模式（transmit mode）。在发送模式中客户端只能发送短消息、在接受模式中客户端只能接受短消息、在收发模式中客户端即可既可以发送也可以接受短消息。三种模式均可以采用长连接与短连接两种连接方式的一种，根据实际情况选择。4.3.2. SPCP发送短消息SPCP以发送者或者是收发者身份登录后，就可以发送短消息。SPCP可以不等待上一个短消息发送回应包，就发送下一个短消息。 CP SMGWlogin(send /transmit mode)login_respsubmit(1)submit(2)submit_resp (1)submit_resp (2)exitexit_resp4.3.3. SPCP接受短消息SPCP以接受者或者是收发者身份登录后，短消息网关就向SPCP下发MO发送短消息，短消息网关可以不等待上一个下发MO短消息回应包，就下发发送下一个MO短消息。 SPCP SMGWlogin(receive /transmit mode)login_respdeliver(1)deliver(2)deliver_resp (1)deliver_resp (2)exitexit_resp4.3.4. SMGW转发短消息短消息网关需要把异地MT/MO短消息转发到相应的短消息网关，在转发短消息之前短消息网关需要通过对方网关认证。 SPCP SMGWlongin(send /receive/ transmit mode)_longin_respforward(1)forward(2)forward_resp (1)forward_resp (2)exitexit_resp5 SMGP数据包定义SMGP基本数据类型定义如下表所示：Integer无符号整数Octet String定长字符串。位数局限性时，假如左补0则补ASCII表达的0，假如右补0则补二进制表达的05.1. 数据包结构SMGP数据包分为包头和包体两部分，包头的结构如下：字段长度（字节）数据类型说明PacketLength4Integer数据包长度（包头和包体的长度之和。单位：字节）RequestID4Integer请求标记SequenceID4Integer序列号（由客户端分派，循环递增）5.2. 请求标记说明请求标记（RequestID）标记数据包的类型，请求包的请求标记和回应包的请求标记一一相应。请求名称请求标记说明login0x00000001SPCP或SMGW登录请求login_resp0x80000001SPCP或SMGW登录回应submit0x00000002SPCP发送短消息请求submit_resp0x80000002SPCP发送短消息回应deliver0x00000003SMGW向SPCP发送短消息请求deliver_resp0x80000003SMGW向SPCP发送短消息回应active_test0x00000004测试通信链路是否正常请求（由客户端发起，SPCP和SMGW可以通过定期发送此请求来维持连接）active_test_resp0x80000004测试通信链路是否正常回应forward0x00000005SMGW转发MT/MO短消息请求forward_reCP0x80000005SMGW转发MT/MO短消息回应exit0x00000006退出请求exit_resp0x80000006退出回应query0x00000007CP发送短信状态记录查询请求query_resp0x80000007CP短信状态记录查询结果回应mt_route_update0x00000008MT路由更新请求mt_route_update_resp0x80000008MT路由更新回应mo_route_update0x00000009MO路由更新请求mo_route_update_resp0x80000009MO路由更新回应5.3. 包体结构5.3.1. login字段长度数据类型说明UserClientID118Octet StringstringSPCP编号或者SMGW编号编号规则参见总册第六6节PasswordAuthenticatorClient1016Octet String客户端密码用于鉴别客户端的接入请求 。其值通过单向MD5 hash计算得出，表达如下：AuthenticatorClient =MD5（ClientID+7 字节的0 +shared secret+timestamp）Shared secret 由中国电信服务器端与ICP客户端事先商定,timestamp格式为：MMDDHHMMSS，即月日时分秒，10位。LoginMode1Integerinteger登录类型（0=发送短消息, 1=接受短消息，2=转发收发短消息，其他保存）TimeStamp4Integer时间戳的明文,由客户端产生,格式为MMDDHHMMSS，即月日时分秒，10位数字的整型,右对齐 Version1integer客户端支持的版本号(高位4bit表达主版本号,低位4bit表达次版本号)5.3.2. login_resp字段长度（字节）数据类型说明ResultStatus4Integerintegerlogin请求返回结果（参照参见错误代码表）AuthenticatorServer16Octet String服务器端认证码，当客户端认证犯错时，此项为空其值通过单向MD5 hash计算得出，表达如下：AuthenticatorServer =MD5（Status+AuthenticatorClient +shared secret）Shared secret 由中国电信服务器端与ICP客户端事先商定，AuthenticatorICPClient为ICP客户端发送给SMGW服务器端的上一条消息login中的值。+Version1Integer服务器支持的最高版本号5.3.3. submit字段长度（字节）数据类型说明SubType1integer短消息子类型（0取消订阅，1订阅请求，2点播，3订阅，其他保存）NeedReport1integer是否规定返回状态报告（0=不规定，1=规定）Pk_id10Integer多包短消息标记Pk_total1Integer相同Pk_id的消息总条数，从1开始Pk_number1Integer相同Pk_id的消息序号，从1开始Priority1Integerinteger发送优先级（从0到9）ServiceID10Octet Stringstring服务类型业务类型FeeType2Octet Stringstring收费类型（参照参见收费类型代码表）FeeCode6Octet Stringstring资费代码（单位为分）MsgFormat1Octet Stringinteger短消息格式（参照参见短消息格式代码表）ValidTime17Octet Stringstring有效时间，格式遵循SMPP3.3协议AtTime17Octet Stringstring定期发送时间，格式遵循SMPP3.3协议SrcTermID21Octet String短消息发送用户号码作为短消息回执的目的地址ChargeTermID21Octet Stringstring计费用户号码点播、订阅、传情等业务的使用用户号码DestTermIDCount1Integerinteger短消息接受号码总数（小等于100）DestTermID21* DestTerm CountOctet Stringstring短消息接受号码（连续存储DestTermIDCount个号码）MsgLength1Integerinteger短消息长度MsgContent小等于252Octet Stringstring短消息内容Reserve8Octet String保存5.3.4. submit_resp字段长度（字节）数据类型说明MsgID10Octet String网关产生的短消息流水号，由三部分组成：网关代码：3字节（BCD码）时间：4字节（BCD码）序列号：3字节（BCD码）ResultStatus4IntegerintegerSubmit请求返回结果（参照参见错误代码表）5.3.5. deliver字段长度（字节）数据类型说明MsgID1Integer网关产生的短消息流水号，由三部分组成：网关代码：3字节（BCD码）时间：4字节（BCD码）序列号：3字节（BCD码）IsReport1Integerinteger是否状态报告（0=不是，1=是）MsgFormat1Integerinteger短消息格式（参照参见短消息格式代码表）RecvTime14Octet Stringstring短消息接受时间（格式：yyyymmddhhmiss，例如00）SrcTermID21Octet Stringstring短消息发送号码DestTermID21Octet Stringstring短消息接受号码MsgLength1Integerinteger短消息长度MsgContent小等于252Octet Stringstring短消息内容Reserve8Octet String保存5.3.6. deliver_resp字段长度（长度）数据类型说明MsgID1Integer网关产生的短消息流水号，由三部分组成：网关代码：3字节（BCD码）时间：4字节（BCD码）序列号：3字节（BCD码）ResultStatus4integerDeliver请求返回结果（参照参见错误代码表）5.3.7. active_test没有包体5.3.8. acitve_test_resp没有包体5.3.9. forward字段长度（长度）数据类型说明MsgID10Octet String网关产生的短消息流水号，由三部分组成：网关代码：3字节（BCD码）时间：4字节（BCD码）序列号：3字节（BCD码）DestSMGWNo6Octet Stringstring目的网关代码SrcSMGWNo6Octet Stringstring源网关代码SMCNo6Octet String短消息中心代码SMType1Integerinteger短消息类型（0=MT，1=MO，2异地点到点短消息，3异网点到点短消息，其他保存）SubType1integer短消息子类型（0取消订阅，1订阅请求，2点播，3订阅，其他保存）ReportFlag1Integerinteger当SMType=0时，表达是否规定返回状态报告（0=不规定，1=规定）当SMType=1时，表达是否状态报告（0=不是，1=是）Pk_total1Integer多包消息总条数，从1开始Pk_number1Integer多包消息序号，从1开始Priority1Integerinteger发送优先级（从0到9）ServiceID10Octet Stringstring服务类型业务类型FeeType2Octet Stringstring资费类型（参照参见收费类型代码表）FeeCode6Octet Stringstring资费代码（单位为分）MsgFormat1Integerinteger短消息格式（参照参见短消息格式代码表）ValidTime17Octet Stringstring有效时间，格式遵循SMPP3.3协议AtTime17Octet Stringstring定期发送时间，格式遵循SMPP3.3协议SrcTermID21Octet String短消息发送用户号码DestTermID21Octet String短消息接受用户号码ChargeTermID21Octet String计费用户号码MsgLength1Integerinteger短消息长度MsgContent小等于252Octet Stringstring短消息内容Reserve8Octet String保存5.3.10. forword_resp字段长度(长度)数据类型说明MsgID10Octet String网关产生的短消息流水号Pk_total1Integer多包消息总条数，从1开始Pk_number1Integer多包消息序号，从1开始ResultStatus4IntegerintegerForward请求返回结果（参照参见错误代码表）5.3.11. exit没有包体5.3.12. exit_resp没有包体query（保存）字段名字节数属性描述Time8Octet String查询时间（格式：yyyymmdd，精确到日）Query_Type1Integer查询类别0：总数查询1：按业务代码查询 其他保存Query_Code10Octet String查询码当Query_Type为0时，此项无效；当Query_Type为1时，此项填写业务代码Service_id.(业务类型)query_resp（保存）字段名字节数属性描述Time8Octet String查询时间（格式：yyyymmdd，精确到日）Query_Type1Integer查询类别0：总数查询1：按业务代码查询 其他保存Query_Code10Octet String查询码（业务类型）MT_TLMsg4Integer从SP接受信息短消息总数MT_Tlusr4Integer从SP接受用户总数MT_Scs4Integer成功转发数量MT_WT4Integer待转发数量MT_FL4Integer转发失败数量MO_Scs4Integer向SP成功送达数量MO_WT4Integer向SP待送达数量MO_FL4Integer向SP送达失败数量Reverse8Octet String保存mt_route_update （保存）字段名字节数属性描述UpdateType1Integer0 添加；1删除；2更新其他保存RouteId4Integer路由编号（若update_type 为“添加”，则此字段为零）SrcGatewayId6Octet String源网关代码SrcGatewayIP15Octet String源网关IP地址SrcGatewayPort2Integer源网关IP端口StartTermId6Octet StringMT路由起始号码段EndTermId6Octet StringMT路由截止号码段AreaCode4Octet String终端所属区号mt_route_update_resp （保存）字段名字节数属性描述Status1Integer参照参见错误代码表mo_route_update（保存）字段名字节数属性描述UpdateType1Integer0 添加；1删除；2更新其他保存RouteId4Integer路由编号(若update_type 为“添加”，则此字段为零)SrcGatewayId6Octet String源网关代码SrcGatewayIP15Octet String源网关IP地址SrcGatewayPort2Integer源网关IP端口SrcTermID21Octet StringICP代码mo_route_update_resp（保存）字段名字节数属性描述Status1Integer参照参见错误代码表5.3.13. 状态报告格式字段长度数据类型说明MsgIDid10Octet Stringstring短消息标记状态报告相应原短消息的MsgIDSubmit_date14Octet Stringstring短消息提交时间（格式：yyyymmddhhmiss，例如）done_date14Octet Stringstring短消息下发时间（格式：yyyymmddhhmiss，例如）Status7Octet Stringstring短消息状态（参照参见短消息状态表）Err3Octet Stringstring参见错误代码表5.3.14. 修改密码格式字段长度数据类型说明OldPassword10Octet Stringstring旧密码NewPassword10Octet Stringstring新密码6 编码说明6.1. 短消息格式代码表代码含义0ASCII编码3短消息写卡操作4二进制短消息8UCS2编码15含GB汉字6.2. 收费类型代码表代码含义00免费01按条收费02包月03封顶其他保存短消息状态表状态名状态值(字符串)说明DELIVEREDDELIVRD短消息转发成功EXPIREDEXPIRED短消息超过有效期DELETEDDELETED短消息已经被删除UNDELIVERABLEUNDELIV短消息是不可转发的ACCEPTEDACCEPTD短消息已经被最终用户接受(为保持与SMPP兼容，保存)UNKNOWNUNKNOWN未知短消息状态REJECTEDREJECTD短消息被拒绝(为保持与SMPP兼容，保存)Err错误代码表状态值(字符串)说明相应状态command_status相应值Command_status代码000成功DELIVRDESME_ROK0x00000001001用户不能通信EXPIREDESME_RUSRABSENT0x00000400002用户忙EXPIREDESME_RUSRUSY0x00000401003终端无此部件号UNDELIVESME_RNOPART0x00000402004非法用户UNDELIVESME_RUSRINVALID0x00000403005用户在黑名单内UNDELIVESME_RBLACKLIST0x00000404006系统错误UNDELIVESME_RSYSERROR0x00000405007用户内存满EXPIREDESME_RMEMCAP0x00000406008非信息终端UNDELIVESME_PROTOCOLERROR0x00000407009数据错误UNDELIVESME_DATAERROR0x00000408010数据丢失UNDELIVESME_DATAMISSING0x00000409注：err错误代码的定义相应了SMPP协议包头中command_status字段的相应状态值。6.3. Status错误代码表代码含义0成功1非法数据包系统忙2登录失败超过最大连接数3-9非法发送优先级保存410非法资费类型消息结构错511非法资费代码命令字错612非法短消息格式序列号反复713-19非法有效时间保存820非法定期发送时间IP地址错921非法短消息发送号码认证错1022非法短消息接受号码版本太高1123-29非法短消息长度保存1230非法目的网关代码非法消息类型（SMType）1331非法源网关代码优先级（Priority）1432非法转发短消息接受号码资费类型（FeeType）1533非法资费代码（FeeCode）修改密码失败1634保存非法短消息格式（MsgFormat）35非法时间格式36非法短消息长度（MsgLength）37有效期已过38非法查询类别（QueryType）39路由错误40-127保存128-255厂家自定义7 基于SMGP协议的API函数详见附录A。附录A 基于SMGP协议的API函数说明(提醒的附录)A.1基本规定A.1.1安装网关需要提供API软件包，解压到指定目录下后可以修改配置文献，配置参数至少涉及IcpId（ICP编号）、IcpShareKey（ICP密码）、ClientIP（客户主机的IP地址）和ServerIP（短信网关地址）。A.1.2例子程序网关至少应当提供以下例程，供ICP调试使用，分别为：Connect(参数)，检查是否可以成功登录短消息网关；TestAPI（参数），检查是否可以成功连接短信网关。SetKey （参数），修改ICP密码。SendSM（参数）尝试发送短信。RecvSM（参数）尝试接受短信等。RecvSMReport(参数)，尝试接受短消息状态报告。A.1.3操作系统平台规定网关提供的API软件包至少规定支持以下操作系统平台：Free BSD 3.x, 4.2Solaris 5.6, 5.7, 5.8(包含x86)Linux（Redhat和Slack等主流产品）Windows NT/2023等网关提供的API软件包至少规定支持以下编程语言：C/C+JAVAA.2 API数据结构说明（以C语言为例）A.2.1接受短信的返回数据结构（DeliverResp）用途保存SMGPDeliver函数返回的短信内容。字段说明字段名数据类型说明sMsgIDChar(11)短消息标记nMsgFormatInt短消息格式（参照短消息格式代码表）。网关不做鉴定, 透明传输。sSrcTermIDChar(22)短消息发送用户号码nIsReportInt是否为应答信息。代码含义：非应答信息（0）；应答信息（1）nMsgLenInt消息长度sMsgContentChar(201)消息内容sDestTermIDchar(21)CP的接入代码sRecvTimechar(15)短消息接受时间（格式：yyyymmddhhmiss，例如00）A.2.2获取群发短信的返回数据结构（SendBatchResp）用途使用SMGPSendBatch群发短信后，每条短信的“消息标记”和“错误代码”保存在文献里。SMGP API提供GetSendBatchResp函数获取每一条短信返回信息，保存在SendBatchResp中。字段说明字段名数据类型说明sMsgIDChar(11)短消息标记nErrorCodeInt错误代码（参照错误代码表）sPhoneNoChar(22)发送号码A.2.3查询短消息网关的返回数据结构（QueryResp可选）用途保存SMGPQuery函数返回的查询结果。字段说明字段名数据类型说明nMT_TLMsgInt接受短消息总数nMT_TLusrInt接受用户总数nMT_ScsInt成功转发数量nMT_WTInt待转发数量nMT_FLInt转发失败数量nMO_ScsInt成功送达数量nMO_WTInt待送达数量nMO_FLInt送达失败数量A.3 API函数说明A.3.1初始化API（InitSMGPAPI）作用初始化SMGP API，应用程序只需要调用一次此函数。参数参数名数据类型说明SiniFileChar(100)SMGPAPI配置文献名，缺省值是：”./config/smgpc.ini”。假如应用程序的执行目录不在smgpapi/bin下，就需要通过绝对或相对途径指定sINIFile。例如：InitSMGPAPI(“/opt/smgpapi/config/smgpc.ini”)返回0=成功1=失败A.3.2发送单条短信（SMGPSendSingle）作用向短消息网关发送1条短消息到1个终端用户。短消息长度最长为200， SMGP API在发送时自动建立Connection Pool，采用长连接或者短连接发送短消息。当Cache的connection中断时，API可以自动重新连接短消息网关。假如应用程序采用多线程发送短消息，多个线程共享同一个Connection Pool。在发送过程中，假如由于通信因素导致发送失败，API可以自动重新发送，重试的次数在配置文献设立。参数参数名数据类型说明nNeedReportInt是否规定返回状态报告（0=不规定，1=规定）nMsgLevelInt信息级别（09，0=最低优先级）sServiceIDChar(11)业务类型nMsgFormatInt短消息格式(参照短消息格式表)。网关不做鉴定, 透明传输。sFeeTypeChar(3)资费类别sFeeCodeChar(7)资费代码（以分为单位）sValidTimeChar(18)存活有效期，格式遵循SMPP3.3协议sAtTimeChar(18)定期发送时间，格式遵循SMPP3.3协议sChargeTermIDChar(22)计费号码sDestTermIDChar(22)短消息接受号码nMsgLenInt短消息长度sMsgContentChar(*)?短消息内容（nMsgLen=0时表达存放短消息的文献名）sMsgIDChar(11)返回的短消息标记nErrorCodeInt 错误代码（参照错误代码表）。返回0=成功1=失败A.3.3群发短信（SMGPSendBatch）作用向短消息网关发送1条短消息到多个手机用户。短消息长度最长为200，此函数使用文献传递短消息内容。SMGP API在发送时自动建立Connection Pool，采用长连接或者短连接发送短消息。当Cache的connection中断时，API可以自动重新连接短消息网关。假如应用程序采用多线程发送短消息，多个线程共享同一个Connection Pool。在发送过程中，假如由于通信因素导致发送失败，API可以自动重新发送，重试的次数在配置文献设立。参数参数名数据类型说明nNeedReportint是否规定返回状态报告（0=不规定，1=规定）nMsgLevelint信息级别。（0=最低优先级，1=正常，2=紧急，3=十分紧急）sServiceIDChar(11)业务类型nMsgFormatInt短消息格式（参照短消息格式表）。网关不做鉴定, 透明传输。sFeeTypeChar(3)资费类别sFeeCodeChar(7)资费代码（以分为单位）sValidTimeChar(18)存活有效期，格式遵循SMPP3.3协议sAtTimeChar(18)定期发送时间，格式遵循SMPP3.3协议sSrcTermIDChar(22)短消息发送用户号码（当为CP代码时须在前面加118）sChargeTermIDChar(22)计费号码（若为空，则对被叫计费）sDestTermIDFileChar(100)保存所有目的号码的文献名nMsgLenInt消息长度sMsgContentChar(*)短消息内容（nMsgLen=0时表达存放短消息的文献名）sMsgIDFileChar(