ISMP网关API开发手册(JAVA).doc

ISMP网关API开发手册（JAVA语言版） ISMP网关API开发手册（SMGP协议JAVA语言版）深圳协尔信息系统有限公司200412修改记录用于说明对文档加附页或文档版本升级时对文档的改动情况，一般设计类文档需要日期修改版本描述作者2003.81.0初稿编写曾宪志2004.8.61.0修改JDK的版本说明（由1.4改为1.3.1）和部分描述曾宪志2004.8.301.0配置参数“RequestTimeout”单位由“秒”改为“毫秒”；新增群发的接口”SMGPSendMulti”曾宪志目 录1.概述42.安装说明53.配置说明54.数据结构定义64.1submitStruct64.2deliverStruct74.3deliverMsg85.API函数介绍85.1InitSMGPAPI85.2SMGPSendSingle85.3SMGPSendMulti95.4SMGPDeliver95.5SMGPActiveTest105.6int SMGPDisconnect()106.附录1:FAQ117.附录2 错误代码118.附录3 短消息格式表129.附录4 短消息参数表1310.附录5 Demo程序使用简介131. 概述ISMP网关SMGP API针对SMGP协议开发，具有良好的性能和扩展性，是为ICP提供的方便的应用开发工具。本手册介绍JAVA语言版API，具体包括如下接口函数：InitSMGPAPI获取配置文件的配置参数，初始化API的配置SMGPSendSingle发送短信SMGPDeliver接收短信和状态报告SMGPActiveTest检查短消息网关是否能够提供服务SMGPDisconnect 从网关注销登录身份，中止相关线程 API说明：l InitSMGPAPI只是读取配置文件初始化参数，不与网关建立连接；l API采用长连接的方式连接网关，并维护连接，断连后自动重连，用户不需关心；l 不同的接口实现模式（即配置文件中“ServiceMode”项配置）有不同的处理方式：ServiceMode1：u 用户应用程序的收发采用公用的收发类型接口发送和接收消息，用户在第一次调用发送或接收函数时，API自动与网关连接，建立收发类型接口，登录网关并保持连接，断连时自动重连；u 这种方式下，若用户使用多个线程处理发送或接收，则所有的发送和接收都是公用同一个收发类型接口ServiceMode2：u 用户应用程序的收发会采用独立的接收类型接口和发送类型接口方式工作，当用户第一次调用发送函数或接收函数时API自动与网关连接建立发送类型或接收类型的接口，登录网关并自动与网关握手保持连接。发送或接收接口建立后若连接中断，API都会自动重连并保持连接u 这种方式下，若用户使用多个线程处理发送或接收，所有的接收都共用同一个接收类型接口，所有的发送都共用同一个发送类型接口。l 用户调用SMGPSendSingle、SMGPDeliver函数时，若API发现还没有连接登录网关或断连，API将自动连接登录。l SMGPActiveTest只是检测系统连接状态，不触发登录网关的操作；l SMGPDisconnect从网关注销登录身份，断开连接；l API提供的所有数据结构体的各属性均提供get、set方法。2. 安装说明1. API是基于JDK1.3.1运行开发，如果版本比这个低，有可能会产生运行时错误；2. 将smgpApi.jar文件加入CLASSPATH；3. 在调用的API的class中导入：“import com.ut.smgp.api.*”“import com.ut.smgp.api.structure.*”3. 配置说明API开发包采用配置文件smgpc.ini需要配置，以下是配置文件配置项的说明：名称说明CpIdCP编号，必须与License的一致。CpShareKeyCP的密码，如果填写不正确会导致应用程序不能通过SMGP用户认证。ServiceMode取值1为“收发公用收发类型接口”，取值2为“收发分别用独立的接收接口和发送接口”ClientIP客户主机的IP地址，必须填写接入Internet的公网地址。如果主机是通过Gateway接入Internet，就填写Gateway地址。此项配置填写错误会导致应用程序不能通过网关对CP的IP地址校验。SubmitRetry发送短消息自动重试次数（1表示只发送1次，0不重新发送）RequestTimeout发送请求超时时间，这个参数要配置成大于0，否则会返回运行时错误，单位：毫秒ActiveTestCycle握手间隔时间，单位毫秒ActiveTestRetryactive test的重试次数，若重复多次没能连接，则重新建立通讯端口。ServerIP短消息网关的IP地址ServerPort短消息网关的端口4. 数据结构定义4.1 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的数值才有效，否则为空。4.2 deliverStruct字段数据类型说明msgIdbyte10网关产生的短消息流水号，由三部分组成：网关代码：3字节（BCD码）时间：4字节（BCD码）序列号：3字节（BCD码）isReportint是否状态报告（0=不是，1=是）msgFormatint短消息格式（参见第7.1节短消息格式代码表）recvTimebyte14短消息接收时间（格式：yyyymmddhhmiss，例如20010301200000）srcTermIdbyte21短消息发送号码destTermIdbyte21短消息接收号码msgLengthint短消息长度msgContentbyte短消息内容。对应于不同的业务，短消息内容域具有不同的格式。reservebyte8保留4.3 deliverMsg字段数据类型说明resultint记录当前数据接收的状态： 0：当前接收状态正常； 其它：当前接收出错。若没有接收到deliver消息，可用通过result判断：是网关没有消息送过来，还是接收过程出现故障。deliverdeliverStruct接收到的deliver消息5. API函数介绍5.1 InitSMGPAPIl 功能：初始化SMGP API，此方法将获取配置文件中的配置参数。每个进程必须并且只能调用一次此函数。l 函数原型：int initSMGPAPI(String initFile)int initSMGPAPI()initFile为SMGP API的配置文件路径，缺省为”./config/smgpc.ini”。l 返回值：0=成功其它=失败，具体数值表示失败的错误码参见附录25.2 SMGPSendSinglel 功能：向短消息网关发送1条短消息到1个终端用户。短消息长度最长为140个英文字符或70个汉字，目前不支持消息的自动分割。本函数为阻塞函数，API给网关提交成功或发生错误时返回。l 函数原型：int SMGPSendSingle( submitStruct submit);l 返回值：0=成功，（submit发送成功后，submit的msgId的数值被赋值，可以对其进行读取）其余为失败，具体数值表示失败的错误码参见附录25.3 SMGPSendMultil 功能：短信群发。短消息长度最长为140个英文字符或70个汉字，目前不支持消息的自动分割。本函数为阻塞函数，API给网关提交成功或发生错误时返回。l 函数原型：int SMGPSendMulti( submitStruct submit,int timeout);l 输入参数submit ：要发送的消息，数组结构；timeout ：超时时间；若全部发送成功，则立即返回；否则重新发送失败的信息或等待接收状态报告直至到达超时时间；单位：毫秒l 返回值：发送结果，返回的结果数组下标与submit的数组下标对应；返回值定义为：0=成功，（submit发送成功后，submit的msgId的数值被赋值，可以对其进行读取）；-2=信息还未发送；-1=信息已发送（或发送失败后重发），但未接收到状态报告；其余为失败，具体数值表示失败的错误码参见附录25.4 SMGPDeliverl 功能：从接收队列中获取从短消息网关收到的deliver消息。l 函数原型：deliverMsg SMGPDeliver(int timeout)l 输入参数：timeout：接收数据时最长的等待时间（单位ms），若timeout0则无限期等待；l 返回值：deliverMsg，其中： int deliverMsg.getResult():：当前接收端口的状态。deliverStruct deliverMsg.getDeliver() ：接收到的信息。5.5 SMGPActiveTestl 功能：检查短消息网关是否能够提供服务l 函数原型：int SMGPActiveTest ()l 返回值：0=成功其余为失败，具体数值表示失败的错误码参见附录2 l 调用示例：int nReturn =SMGPActiveTest ();5.6 int SMGPDisconnect()l 功能：断开与网关的连接l 函数原型：int SMGPDisconnect()l 返回值：0=成功其余为失败，具体数值表示失败的错误码参见附录2 l 注意事项：断开连接前，请关闭用户建立的所有接收、发送进程。因为API能够自动连接登录，若先调用SMGPDisconnect（）关闭连接，但用户的建立接收、发送线程还在运行，这是就可能导致API再次自动连接l 调用示例：int nReturn = int SMGPDisconnect();6. 附录1:FAQ问：使用API连接时为何频繁发生重连和断连现象，造成链路不稳定答：API在连接网关时，如果维持链路的握手消息时间太长（超过了网关那边设置的最大时间长度），则网关会将API连接的客户端链路断开，然后API又发生重连，如此继续下去，解决的方法时将握手消息的时间间隔配置为合适的长度，即更改配置文件中ActiveTestCycle的值，一般不要太长（如4000）。问：为什么我在一个等待MO消息的线程中中访问返回结构体deliverStruct中来判断是否有消息时有时候发生异常？答：在访问Result之前先判断一下连接的状态，即访问结构体的变量判断一下result的值是否为0。7. 附录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超时其他保留8. 附录3 短消息格式表代码含义0ASCII编码3短消息写卡操作4二进制短消息8UCS2编码15GB18030编码其他保留9. 附录4 短消息参数表字段长度（字节）数据类型说明sMsgType1integer短消息类型（1取消订阅，2订阅请求，3点播，4订阅，5交互式操作，6=查询，8扣费专用，其他保留）sFeeType2Octet String收费类型（00免费，01按条收费，02包月，03封顶，其他保留）10. 附录5 Demo程序使用简介Demo程序使用当前运行路径下的配置文件，启动（javac smgpapidemo.smgp）后，首先在“源地址”栏中输入CP编号，在“目的地址”输入接受手机的号码，按下“初始化”按钮进行初始化。初始化成功后“关闭”按钮和“发送”按钮按钮将变成可用状态。在文本框中输入短消息的内容，可以改变短消息的优先级和编码方式，确定是否需要状态报告，按下“发送”按钮发送短消息。点击“开始接收按钮”，demo将自动接收短消息。13