小灵通短信网关API开发手册.doc

小灵通短信网关API开发手册（SMGP协议JAVA语言版）UT公司20038修改记录用于说明对文档加附页或文档版本升级时对文档的改动情况，一般设计类文档需要日期修改版本描述作者2003.81.0初稿编写曾宪志目 录1.概述4矚慫润厲钐瘗睞枥庑赖賃軔朧碍鳝绢。2.安装说明5聞創沟燴鐺險爱氇谴净祸測樅锯鳗鲮。3.配置说明5残骛楼諍锩瀨濟溆塹籟婭骒東戇鳖納。4.数据结构定义6酽锕极額閉镇桧猪訣锥顧荭钯詢鳕驄。4.1Submit消息体（submitStruct）6彈贸摄尔霁毙攬砖卤庑诒尔肤亿鳔简。4.2Submit Response消息体（submitRespStruct）7謀荞抟箧飆鐸怼类蒋薔點鉍杂篓鳐驱。4.3Deliver 消息体（deliverStruct）7厦礴恳蹒骈時盡继價骚卺癩龔长鳏檷。4.4Deliver Response (deliverRespStruct)8茕桢广鳓鯡选块网羈泪镀齐鈞摟鳎饗。5.API函数介绍8鹅娅尽損鹌惨歷茏鴛賴縈诘聾諦鳍皑。5.1InitSMGPAPI8籟丛妈羥为贍偾蛏练淨槠挞曉养鳌顿。5.2SMGPSendSingle9預頌圣鉉儐歲龈讶骅籴買闥龅绌鳆現。5.3SMGPDeliver9渗釤呛俨匀谔鱉调硯錦鋇絨钞陉鳅陸。5.4SMGPActiveTest9铙誅卧泻噦圣骋贶頂廡缝勵罴楓鳄烛。5.5int SMGPDisconnect()10擁締凤袜备訊顎轮烂蔷報赢无貽鳃闳。6.附录2 错误代码10贓熱俣阃歲匱阊邺镓騷鯛汉鼉匮鲻潰。7.附录3 短消息格式表12坛摶乡囂忏蒌鍥铃氈淚跻馱釣缋鲸鎦。8.附录4 短消息参数表12蜡變黲癟報伥铉锚鈰赘籜葦繯颓鲷洁。9.附录5 Demo程序使用简介12買鲷鴯譖昙膚遙闫撷凄届嬌擻歿鲶锖。概述小灵通短消息网关SMGP API针对SMGP协议开发，具有良好的性能和扩展性，是为ICP提供的方便的应用开发工具。綾镝鯛駕櫬鹕踪韦辚糴飙钪麦蹣鲵殘。本手册介绍JAVA语言版API，具体包括如下接口函数：InitSMGPAPI获取配置文件的配置参数，初始化API的配置SMGPSendSingle发送短信SMGPDeliver接收短信和状态报告SMGPActiveTest检查短消息网关是否能够提供服务SMGPDisconnect 从网关注销登录身份，中止相关线程 API说明：InitSMGPAPI只是读取配置文件初始化参数，不与网关建立连接；API采用长连接的方式连接网关，并维护连接，断连后自动重连，用户不需关心；不同的接口实现模式（即配置文件中“ServiceMode”项配置）有不同的处理方式：ServiceMode1：用户应用程序的收发采用公用的收发类型接口发送和接收消息，用户在第一次调用发送或接收函数时，API自动与网关连接，建立收发类型接口，登录网关并保持连接，断连时自动重连；驅踬髏彦浃绥譎饴憂锦諑琼针咙鲲鏵。这种方式下，若用户使用多个线程处理发送或接收，则所有的发送和接收都是公用同一个收发类型接口ServiceMode2：用户应用程序的收发会采用独立的接收类型接口和发送类型接口方式工作，当用户第一次调用发送函数或接收函数时API自动与网关连接建立发送类型或接收类型的接口，登录网关并自动与网关握手保持连接。发送或接收接口建立后若连接中断，API都会自动重连并保持连接猫虿驢绘燈鮒诛髅貺庑献鵬缩职鲱样。这种方式下，若用户使用多个线程处理发送或接收，所有的接收都共用同一个接收类型接口，所有的发送都共用同一个发送类型接口。锹籁饗迳琐筆襖鸥娅薔嗚訝摈馍鲰钵。用户调用SMGPSendSingle、SMGPDeliver函数时，若API发现还没有连接登录网关或断连，API将自动连接登录。構氽頑黉碩饨荠龈话骛門戲鷯瀏鲮晝。SMGPActiveTest只是检测系统连接状态，不触发登录网关的操作；SMGPDisconnect从网关注销登录身份，断开连接；API提供的所有数据结构体的各属性均提供get、set方法。安装说明API是基于JDK1.4运行开发；将smgpApi.jar文件加入CLASSPATH；在调用的API的class中导入：“import com.ut.smgp.api.*”“import com.ut.smgp.api.structure.*”配置说明API开发包采用配置文件smgpc.ini需要配置，以下是配置文件配置项的说明：名称说明CpIdCP编号，必须与License的一致。CpShareKeyCP的密码，如果填写不正确会导致应用程序不能通过SMGP用户认证。ServiceMode取值1为“收发公用收发类型接口”，取值2为“收发分别用独立的接收接口和发送接口”ClientIP客户主机的IP地址，必须填写接入Internet的公网地址。如果主机是通过Gateway接入Internet，就填写Gateway地址。此项配置填写错误会导致应用程序不能通过网关对CP的IP地址校验。SubmitRetry发送短消息自动重试次数（1表示只发送1次，0不重新发送）RequestTimeout发送请求超时时间，单位：秒ActiveTestCycle握手间隔时间，单位毫秒ActiveTestRetryactive test的重试次数，若重复多次没能连接，则重新建立通讯端口。ServerIP短消息网关的IP地址ServerPort短消息网关的端口数据结构定义submitStruct字段数据类型说明msgTypeint短消息类型（1取消订阅，2订阅请求，3点播，4订阅，5交互式操作，6=查询，其他保留）needReportint是否要求返回状态报告（0=不要求，1=要求）priorityint发送优先级（从0到9）serviceIdString业务类型feeTypeString收费类型（参见第7.2节收费类型代码表）feeCodeString资费代码（单位为分）按条扣费时填写fixedFeeString包月费/封顶费（单位为分）包月扣费时填写msgFormatint短消息格式（参见第7.1节短消息格式代码表）validTimeString有效时间，格式遵循SMPP3.3协议atTimeString定时发送时间，格式遵循SMPP3.3协议srcTermIdString短信息发送方的电话号码（格式为“电话号码*子信箱号“），当短消息来自CP时，电话号码为118+CP ID或者发送方主叫号码。chargeTermIdString计费用户号码destTermIdCountint短消息接收号码总数（100）destTermIdString短消息接收号码（多个DestTermIDCount号码，每一个接收方号码的的最长长度为21，格式为“电话号码*子信箱号“，0表示公共信箱,1表示一号子信箱,2表示二号子信箱,3表示三号子信箱msgLengthint短消息长度msgContentbyte短消息内容。对应于不同的业务，短消息内容域具有不同的格式。reserveString保留msgIdStringsubmit response信息中的msgId信息，submit发送成功后msgId的数值才有效，否则为空。deliverStruct字段数据类型说明msgIdbyte10网关产生的短消息流水号，由三部分组成：网关代码：3字节（BCD码）时间：4字节（BCD码）序列号：3字节（BCD码）isReportint是否状态报告（0=不是，1=是）msgFormatint短消息格式（参见第7.1节短消息格式代码表）recvTimebyte14短消息接收时间（格式：yyyymmddhhmiss，例如20010301200000）srcTermIdbyte21短消息发送号码destTermIdbyte21短消息接收号码msgLengthint短消息长度msgContentbyte短消息内容。对应于不同的业务，短消息内容域具有不同的格式。reservebyte8保留deliverMsg字段数据类型说明resultint记录当前数据接收的状态： 0：当前接收状态正常； 其它：当前接收出错。若没有接收到deliver消息，可用通过result判断：是网关没有消息送过来，还是接收过程出现故障。deliverdeliverStruct接收到的deliver消息API函数介绍InitSMGPAPI功能：初始化SMGP API，此方法将获取配置文件中的配置参数。每个进程必须并且只能调用一次此函数。函数原型：int initSMGPAPI(String initFile)int initSMGPAPI()initFile为SMGP API的配置文件路径，缺省为”./config/smgpc.ini”。返回值：0=成功其它=失败，具体数值表示失败的错误码参见附录2SMGPSendSingle功能：向短消息网关发送1条短消息到1个终端用户。短消息长度最长为140个英文字符或70个汉字，目前不支持消息的自动分割。本函数为阻塞函数，API给网关提交成功或发生错误时返回。輒峄陽檉簖疖網儂號泶蛴镧釃邊鲫釓。函数原型：int SMGPSendSingle( submitStruct submit);返回值：0=成功其余为失败，具体数值表示失败的错误码参见附录2SMGPDeliver功能：从接收队列中获取从短消息网关收到的deliver消息。函数原型：deliverMsg SMGPDeliver(int timeout)输入参数：timeout：接收数据时最长的等待时间（单位ms），若timeout0则无限期等待；返回值：deliverMsg，其中： int deliverMsg.getResult():：当前接收端口的状态。deliverStruct deliverMsg.getDeliver() ：接收到的信息。SMGPActiveTest功能：检查短消息网关是否能够提供服务函数原型：int SMGPActiveTest()返回值：0=成功其余为失败，具体数值表示失败的错误码参见附录2 调用示例：int nReturn =SMGPActiveTest ();int SMGPDisconnect()功能：断开与网关的连接函数原型：int SMGPDisconnect()返回值：0=成功其余为失败，具体数值表示失败的错误码参见附录2 注意事项：断开连接前，请关闭用户建立的所有接收、发送进程。因为API能够自动连接登录，若先调用SMGPDisconnect（）关闭连接，但用户的建立接收、发送线程还在运行，这是就可能导致API再次自动连接尧侧閆繭絳闕绚勵蜆贅瀝纰縭垦鲩换。调用示例：int nReturn = int SMGPDisconnect();附录2 错误代码编号含义4非法短消息长度5非法资费代码（FeeCode）6短消息长度超长7非法业务类型（ServiceId）8短消息发送速度太快10非法CP编号11非法信息格式（MsgFormat）12非法自费类别（FeeType）13非法存活有效期（ValidTime）14非法定时发送时间（AtTime）15非法计费号码（ChargeTermId）16非法目标号码（DestTermId）17不能打开目标号码文件（DestTermIdFile）18不能打开短消息内容文件（MsgFile）19非法短消息（MsgContent）20连接短消息网关失败21登录失败22接收结果数据包失败23发送队列满24超出系统限制25系统忙26超过最大连接数27消息结构错28命令字错29序列号重复30IP地址错31认证错32版本太高33非法消息类型（SMType）34非法优先级（Priority）35非法时间格式36有效期已过37路由错误96等待回应数据包超时97发送数据包失败99系统错误100ACK超时其他保留附录3 短消息格式表代码含义0ASCII编码3短消息写卡操作4二进制短消息8UCS2编码15GB18030编码其他保留附录4 短消息参数表字段长度（字节）数据类型说明sMsgType1integer短消息类型（1取消订阅，2订阅请求，3点播，4订阅，5交互式操作，6=查询，8扣费专用，其他保留）sFeeType2Octet String收费类型（00免费，01按条收费，02包月，03封