搜档网
当前位置:搜档网 › MAS2.0 JAVA API接口插件开发手册

MAS2.0 JAVA API接口插件开发手册

MAS2.0 JAVA API接口插件开发手册
MAS2.0 JAVA API接口插件开发手册

中国移动代理服务器MAS V2.0 JAVA API接口插件

开发手册

深圳市嘉讯软件有限公司

2008年9月

目录

1.引言 (4)

1.1.编写目的 (4)

1.2.背景说明 (4)

1.3.相关术语与缩略语解释 (4)

2. API结构说明 (4)

3. 运行环境 (5)

4. 开发步骤 (5)

4.1. 在Mas服务器新建一个企业应用 (5)

4.2.启动企业应用 (6)

4.3.开发时需要引入的包 (6)

4.4.接口开发及使用举例 (6)

4.4.1. APIClient工厂类-ApiClientFactory类 (7)

4.4.1.1. 创建短信API客户端-createSmsApiClient方法 (7)

4.4.2. 短信接口 (7)

4.4.2.1. 短信API客户端主要操作类-SmsApiClient类 (7)

4.4.2.1.1. 设置自动重连服务器-setTimingConnect方法 (7)

4.4.2.1.2. 设置自动重连服务器相隔时间-setConnectTime方法 (7)

4.4.2.1.3. 设置与服务连接超时时长-setConnectTimeout方法 (8)

4.4.2.1.4. 设置发送超时时长-setSendTimeout方法 (8)

4.4.2.1.5. 启动API-start方法 (8)

4.4.2.1.6. 获得网关连接状态-getConnStatusIAGW方法 (8)

4.4.2.1.7. 取消短信发送- canelSms方法 (8)

4.4.2.1.8. 获得短信队列中未发送的条数-getStat方法 (8)

4.4.2.1.9. 获得扩展服务代码长度- getXCodeLength方法 (8)

4.4.2.1.10. 计算短信条数和字数-getSmsCount方法 (8)

4.4.2.1.11. 获得预览的短信内容-getSmsContentPreview方法错误!未定

义书签。

4.4.2.1.12. 短信API退出-loginOut方法 (8)

4.4.2.1.13. 获得MAS短信提交的限制数量-getDestAddrsLimit方法 (9)

4.4.2.1.14. 发送短信-sendSms方法 (9)

4.4.2.2. 短信回调对象处理类-SmsApiClientHandler类 (10)

4.4.2.2.1. 发送响应通知-notifySmsSendResponse方法错误!未定义书签。

4.4.2.2.2. 状态报告通知-notifySmsDeliveryStatus方法 (10)

4.4.2.2.3. MO短信通知-notifySmsReception方法 (10)

4.4.2.2.4. 通知取消成功的手机号码-notifyCanelSmsList方法 (11)

4.4.2.3. 短信开发客户端代码举例 (11)

4.4.3. 彩信接口 (14)

4.4.3.1. 彩信API客户端主要操作类-MmsApiClient类 (14)

4.4.3.1.1. 设置是否自动重连到服务器-setTimingConnect方法 (14)

4.4.3.1.2. 设置自动重连服务器相隔时间-setConnectTime方法 (14)

4.4.3.1.3. 设置与服务连接超时时长-setConnectTimeout方法 (14)

4.4.3.1.4. 设置发送超时时长-setSendTimeout方法 (14)

4.4.3.1.5. 启动API -start方法 (14)

4.4.3.1.6. 彩信API退出-loginOut方法 (14)

4.4.3.1.7. 获得网关连接状态-getConnStatusIAGW方法 (14)

4.4.3.1.8. 获得MAS彩信提交的限制数量-getDestAddrsLimit方法 (15)

4.4.3.1.9. 发送彩信-sendMms方法 (15)

4.4.3.1.10. 获取该次发送还未提交到彩信网关的数量-getStat方法 (15)

4.4.3.1.11. 取消彩信发送-canelMms方法 (16)

4.4.3.2. 彩信服务回调对象进行处理类-MmsApiClientHandler类 (16)

4.4.3.2.1. 发送响应通知-notifyMmsSendResponse方法 (16)

4.4.3.2.2. 状态报告通知-notifyMmsDeliveryStatus方法 (16)

4.4.3.2.3. MO彩信通知-notifyMmsReception方法 (17)

4.4.3.2.4. 通知取消成功的手机号码-notifyCanelMmsMobile方法错误!未

定义书签。

4.4.3.3. 彩信多媒体消息内容格式定义说明 (17)

4.4.3.3.1. 彩信多媒体内容类型 (17)

4.4.3.3.2. 彩信多媒体内容加密 (17)

4.4.3.3.3. 彩信多媒体内容编码 (17)

4.4.3.3.4. 彩信多媒体内容支持附件的类型 (18)

4.4.3.3.5. 彩信多媒体消息内容示例 (18)

4.4.3.3.6. 彩信多媒体消息具体加密前后内容示例 (18)

4.4.3.4. 彩信开发客户端代码举例 (20)

4.4.4. API异常错误对应常量 (22)

5. 接口描述 (23)

5.1.短信接口描述 (23)

5.1.1. 接口说明 (23)

5.1.2. 流程说明 (23)

5.1.3. 主要类说明 (24)

5.2. 彩信接口描述 (24)

5.2.1. 接口说明 (24)

5.2.2. 流程说明 (24)

5.2.3. 主要类说明 (25)

6. API短信DEMO使用说明 (25)

6.1.1. 使用说明 (25)

6.1.2. 主要命令说明 (25)

7. 注意事项 (27)

8. 参考文档 (27)

1.引言

1.1.编写目的

本手册详细描述了中国移动代理服务器(MAS)短信、彩信API的开发步骤以及注意事项。

其阅读对象为需要MAS开发、工程支持人员、集成开发人员、SI厂商开发人员、企业客户IT开发人员。

1.2.背景说明

近年来移动业务高速发展,MAS业务也开展的如火如荼,但同时许多集团客户有许多自己的IT系统,他们如何把自己的IT系统也“移动”化起来呢?MAS做为移动代理服务器,提供了许多手段来供企业IT系统接入(如WS接口、DB接口、W AP适配),但此次API又为这许多手段之外再增加了一种方式,并且这种方式更为高效、更稳定、扩展性更强。

本手册适用于产品“中国移动代理服务器MAS”V2.0版本。只描述了以JA V A语言客户端来接入MAS的内容,其它语言开发客户端可以参考本手册。

1.3.相关术语与缩略语解释

2.API结构说明

企业应用通过APIClient来与MAS通信,底层采用Socket,这样可以保证高性能与稳定性。

API方式通信适配插件接口封装了以下移动通信能力:

●短信

●彩信

此外,还提供基座与企业应用之间的插件管理功能接口。

MAS服务器应提供配置工具,指定对于某个集团客户应用系统或应用插件,通过API 方式通信适配插件或数据库方式通信适配插件接入MAS服务器。

这是当应用作为插件的身份来接入MAS时才考滤的开发环境。当应用不作为插件而做为集团客户应用的身份来接入时不需关注,只需通过标准的API接口即可。

3.运行环境

●MAS2.0基座运行环境

●MAS服务平台环境

●JDK1.5及以上

4.开发步骤

4.1.在Mas服务器新建一个企业应用

●运行MAS2服务器,登录到系统管理->“插件管理”中新建一个企业应用

在开发完成后准备调试前,先运行MAS2.0服务器,然后在插件管理里新建一个应用或插件。

图4-1新增插件页面

注意:新建时“通信接口方式”选择“API”。

4.2.启动企业应用

图4-2插件管理页面

要新建的插件API接口可用,需要点击“开关”列的运行按钮。否则在使用API接口通信时可能会报POL0906错误。当然要确保API接口能正常使用,还需要管理平台相应的业务能力。

4.3.开发时需要引入的包

客户端开发时,要引入mas-api.3.x.ja r包。

4.4.接口开发及使用举例

4.4.1.APIClient工厂类-ApiClientFactory类

描述:APIClient工厂类,用来创建短信APIClient与彩信APIClient。

4.4.1.1.创建短信API客户端-createSmsApiClient方法

4.4.1.2.创建彩信API客户端- createMmsApiClient方法

功能:创建彩信API客户端,一个MmsApiClient绑定了一个Socket连接。

4.4.2.短信接口

4.4.2.1.短信API客户端主要操作类-SmsApiClient类

短信API客户端主要操作接口,通过ApiClientFactory类来创建期实例,一个SmsApiClient对象代表了与服务器连接,在正常与服务器通信时需要先调其start方法来初始化。

4.4.2.1.1.设置自动重连服务器-setAutoConnect方法

功能:设置是否自动重连到服务器。

4.4.2.1.2.设置自动重连服务器相隔时间-setReConnectInterval方

功能:设置自动重连服务器相隔时间(单位:秒),默认为30秒

4.4.2.1.3.设置与服务连接超时时长-setConnectTimeout方法

功能:设置与服务连接超时时长,单位:millisecond,需要在调用start方法前设置方可生效。

4.4.2.1.4.设置发送超时时长-setSendTimeout方法

功能:设置发送超时时长,单位:millisecond,需要在调用start方法前设置方可生效。

4.4.2.1.

5.启动API-start方法

功能:启动API,该方法会自动连接到MAS服务器并进行登录。所有的发送、接收等操作都需要在start成功后方可使用。

4.4.2.1.6.获得网关连接状态-getConnStatusIAGW方法

功能:获得网关连接状态。

4.4.2.1.7.取消短信发送- canelSms方法

功能:取消短信发送。

4.4.2.1.8.获得短信队列中未发送的条数-getStat方法

功能:获得短信队列中未发送的条数。

4.4.2.1.9.获得扩展服务代码长度- getXCodeLength方法

功能:获得扩展服务代码(插件短信扩展号码+流水号)长度。

4.4.2.1.10.计算短信条数和字数-getSmsCount方法

功能:计算短信条数和字数。

4.4.2.1.11.短信API退出-loginOut方法

功能:短信API退出。

4.4.2.1.12.获得MAS短信提交的限制数量-getDestAddrsLimit方法功能:获得MAS当前短信提交的限制数量。

4.4.2.1.13.发送短信-sendSms方法

4.4.2.2.短信回调对象处理类-SmsApiClientHandler类

描述:由企业应用来实现,该接口类主要是对短信服务的一些回调对象进行处理,如接收状态报告、MO短信等。

4.4.2.2.1.状态报告通知-notifySmsDeliveryStatus方法

功能:状态报告通知。如果在发送时指定不要状态报告将不会调用到此方法

注:一条状态报告成功与否有以下几种情况

1.sendResult 如果为0,则看stat,stat为“DELIVRD”则表示发送成功,stat为其它则表示发送失败,errDesc为错误描述

2.sendResult 不为0,则表示发送失败,不用看stat, 直接看errDesc错误描述

4.4.2.2.2.MO短信通知-notifySmsReception方法

功能:MO短信通知。其sms参数说明如下

4.4.2.2.3.通知取消成功的手机号码-notifyCanelSmsList方法

功能:通知取消成功的手机号码,其参数说明如下

4.4.2.3.短信开发客户端代码举例

由图4-1所示,新建了API插件,API插件标识为“API插件”,API插件密码“123123”,下面代码演示API客户端发送短信及相关方法。

//设置是否自动重连到服务器(可以不需要设置)

smsApiClient .setAutoConnect (true);

//设置自动重连服务器相隔时间(单位:秒), 默认为30秒(可以不需要设置)

smsApiClient.setReConnectInterval (60);

//设置与服务连接超时时长,单位:millisecond(可以不需要设置)

smsApiClient.setConnectTimeout(100000);

//设置发送超时时长,单位:millisecond(可以不需要设置)

smsApiClient.setSendTimeout(1000000);

//获得短信群发提交的数量限制

int ret = smsApiClient.getDestAddrsLimit();

//获取网关连接状态(Connect:连接正常, Disconnect:断连, NotConnect:没有连接, Other:其他)

ConnectStatus connectStatus= smsApiClient.getConnStatusIAGW();

if (!ConnectStatus.Connect.equals(connectStatus))

{

System.out.println("网关未连接");

return;

}

//计算短信条数和字数

SmsCount smsCount= smsApiClient.getSmsCount(content, MsgFmt.GB2312, SmsType.Normal);

//获得扩展服务代码(插件短信扩展号码+流水号)长度

int xcodeLength= smsApiClient.getXCodeLength()

//发送短信

//======构造发送短信对象开始,下面代码演示发送短信对象几个比较主要的属性值,其它的属性可以不设置,如果要设置可以参考sendSms方法中 SmsSendRequest参数===SmsSendRequest smsSendRequest = new SmsSendRequest();

List list = new ArrayList();

//每次群发数量不能超过最大限制数

for (int i = 0; i < ret; i++)

{

long address = mobile + i;

list.add(String.valueOf(address));

smsSendRequest.destAddrs = list;

smsSendRequest.validTime = 10000; // 短信存活期,单位秒

smsSendRequest.xCode = xCode; //短信扩展码

smsSendRequest.message = content; //短信内容

smsSendRequest.msgFormat =MsgFmt.GB2312; //短信编码类型

smsSendRequest.isNeedReport = true; //短信是否需要状态报告

smsSendRequest.priority = 1;//短信网关优先级,短信优先级大于0 的整数0为最高优先级,数字越大级别越低

//Normal: 普通短信,Instant:免提短信, Long:长短信,Structured:二进制短信,WapPush://WapPush短信

smsSendRequest.type = SmsType.Normal;

smsSendRequest.appID = appID;

//======构造发送短信对象结束=======

SmsSendResponse smsSendResponse = smsApiClient.sendSms(smsSendRequest); System.out.println("提交成功,requestID:" + smsSendResponse.requestID);

}

catch (Exception e)

{

System.out.println("API短信客户端调用失败:" + e.getMessage());

return;

}

如提交成功会收到requestID,如有网络连接、密码错误等问题,则会抛相应的异常,相关异常信息请参考4.4.4API异常错误对应常量。

SmsApiClientHandler接口类主要是对短信服务的一些回调对象进行处理,如接收状态报告、

4.4.3.彩信接口

4.4.3.1.彩信API客户端主要操作类-MmsApiClient类

彩信API客户端主要操作接口,通过ApiClientFactory类来创建期实例,一个MmsApiClient对象代表了与服务器连接,在正常与服务器通信时需要先调其start方法来初始化。

4.4.3.1.1.设置是否自动重连到服务器-setAutoConnect方法

功能:设置是否自动重连到服务器。

4.4.3.1.2.设置自动重连服务器相隔时间-setReConnectInterval方

功能:设置自动重连服务器相隔时间(单位:秒),默认为30秒。

4.4.3.1.3.设置与服务连接超时时长-setConnectTimeout方法

功能:设置与服务连接超时时长,单位:millisecond,需要在调用start方法前设置方可生效。

4.4.3.1.4.设置发送超时时长-setSendTimeout方法

功能:设置发送超时时长,单位:millisecond,需要在调用start方法前设置方可生效。

4.4.3.1.

5.启动彩信API -start方法

功能:启动API,该方法会自动连接到MAS服务器并进行登录。所有的发送、接收等操作都需要在start成功后方可使用。

4.4.3.1.6.彩信API退出-loginOut方法

功能:彩信API退出。

4.4.3.1.7.获得网关连接状态-getConnStatusIAGW方法

功能:获得网关连接状态。

4.4.3.1.8. 获得MAS 彩信提交的限制数量-getDestAddrsLimit 方法

功能:获得MAS 当前彩信提交的限制数量。

4.4.3.1.9. 发送彩信-sendMms 方法

其MmsSendResponse 参数说明如下

4.4.3.1.10. 获取该次发送还未提交到彩信网关的数量-getStat 方法

4.4.3.1.11. 取消彩信发送-canelMms 方法

4.4.3.2. 彩信服务回调对象进行处理类-MmsApiClientHandler 类

由企业应用来实现,该接口类主要是对彩信服务的一些回调对象进行处理,如接收状态报告、MO 彩信等。

4.4.3.2.1. 发送响应通知-notifyMmsSendResponse 方法

功能:发送响应通知。其mmsSendResponse 说明如下

4.4.3.2.2. 状态报告通知-notifyMmsDeliveryStatus 方法

功能:状态报告通知。如果在发送时指定不要状态报告将不会调用到此方法

4.4.3.2.3.MO彩信通知-notifyMmsReception方法

4.4.3.3.彩信多媒体消息内容格式定义说明

4.4.3.3.1.彩信多媒体内容类型

mas提供的各种彩信发送接口,彩信内容(content)一项均是字符串类型。

4.4.3.3.2.彩信多媒体内容加密

彩信多媒体消内容必须经是过BASE64加密的字符串

4.4.3.3.3.彩信多媒体内容编码

彩信多媒体消内容文本附件内容必须采用utf-8编码

4.4.3.3.4.彩信多媒体内容支持附件的类型

text/plain, text/xml, application/smil, audio/amr, audio/midi, text/i-melody, text/e-melody,image/gif, image/jpeg, image/vnd.wap.wbm, image/png

4.4.3.3.

5.彩信多媒体消息内容示例

以下为加密前内容示例,通过mas发送彩信必须将此内容采用BASE64加密后发送:

--SubPart_7452684322002_77645

Content-Type:application/smil

Content-Transfer-Encoding:8bit

Content-ID:20080815103000023.smil

Content-Location:20080815103000023.smil smil

附件内容……

--SubPart_7452684322002_77645

Content-Type:image/gif

Content-Transfer-Encoding:8bit

Content-ID:20080815102800026.gif

Content-Location:20080815102800026.gif

gif附件内容……

--SubPart_7452684322002_77645

Content-Type:text/plain;charset=UTF-8

Content-Transfer-Encoding:8bit

Content-ID:200808151030000231.txt

Content-Location:200808151030000231.txt

文本附件内容……

--SubPart_7452684322002_77645--

----NextPart_0_2817_24856—

示例内容说明,内容中可以存在多个附件,每个附件前必须“--SubPart_7452684322002_77645

”开始,最后一个附件后加--SubPart_7452684322002_77645--

----NextPart_0_2817_24856—

附件内容属性说明

Content-Type 附件类型

Content-Transfer-Encoding 附件编码位数,默认采用8位编码

Content-ID 附件名称

Content-Location 附件名称

4.4.3.3.6.彩信多媒体消息具体加密前后内容示例

--SubPart_7452684322002_77645

Content-Type:application/smil

Content-Transfer-Encoding:8bit

Content-ID:20080815114700048.smil

Content-Location:20080815114700048.smil

--SubPart_7452684322002_77645

Content-Type:text/plain;charset=UTF-8

Content-Transfer-Encoding:8bit

Content-ID:200808151147000481.txt

Content-Location:200808151147000481.txt

HELLO MMS!

--SubPart_7452684322002_77645--

----NextPart_0_2817_24856—

加密后:

LS1TdWJQYXJ0Xzc0NTI2ODQzMjIwMDJfNzc2NDUNCkNvbnRlbnQtVHlwZTphcHBsaWNh dGlvbi9zbWlsDQpDb250ZW50LVRyYW5zZmVyLUVuY29kaW5nOjhiaXQNCkNvbnRlbnQtS UQ6MjAwODA4MTUxMTQ3MDAwNDguc21pbA0KQ29udGVudC1Mb2NhdGlvbjoyMDA4M DgxNTExNDcwMDA0OC5zbWlsDQoNCjxzbWlsPjxoZWFkPjxtZXRhIG5hbWU9InRpdGxlIiB jb250ZW50PSIiLz48bGF5b3V0Pjxyb290LWxheW91dCB3aWR0aD0iMTAwJSIgaGVpZ2h0PSI xMDAlIiAgLz48cmVnaW9uIGlkPSJ0eHRfdG9wIiB3aWR0aD0iMTAwJSIgaGVpZ2h0PSIxNiUi IGxlZnQ9IjAiIHRvcD0iMCIgZml0PSJzY3JvbGwiLz48cmVnaW9uIGlkPSJ0eHRfYnV0dG9uIi B3aWR0aD0iMTAwJSIgaGVpZ2h0PSIxNiUiIGxlZnQ9IjAiIHRvcD0iODQlIiBmaXQ9InNjcm9s bCIvPjxyZWdpb24gaWQ9ImltZ190b3AiIHdpZHRoPSIxMDAlIiBoZWlnaHQ9Ijg0JSIgbGVmd D0iMCIgdG9wPSIwIiBmaXQ9ImZpbGwiLz48cmVnaW9uIGlkPSJpbWdfYnV0dG9uIiB3aWR0 aD0iMTAwJSIgaGVpZ2h0PSI4NCUiIGxlZnQ9IjAiIHRvcD0iMTYlIiBmaXQ9ImZpbGwiLz48c mVnaW9uIGlkPSJhbGwiIHdpZHRoPSIxMDAlIiBoZWlnaHQ9IjEwMCUiIGxlZnQ9IjAiIHRvc D0iMCIgZml0PSJmaWxsIiAvPjwvbGF5b3V0PjwvaGVhZD48Ym9keT48cGFyIGR1cj0iMTAw MDBtcyI+PHRleHQgc3JjPSIyMDA4MDgxNTExNDcwMDA0ODEudHh0IiByZWdpb249ImFs

4.4.3.4.彩信开发客户端代码举例

由图4-1所示,新建了API插件,API插件标识为“API插件”,API插件密码“123123”,下面代码演示API客户端发送彩信及相关方法。

彩信开发客户端相关方法调用代码example

MmsApiClient mmsApiClient = null;

String appID="API插件";//API插件标识ID

String appPwd="123123";//API插件密码

long mobile = 138********l;

String xcode="222";//彩信扩展码

String version=”3.0”;

int masApiPort =61617;

String masIP="192.168.0.238";

//MmsApiClientHandlerImpl是自己实现的

MmsApiClientHandler mmsHandler = new MmsApiClientHandlerImpl();

try

{

mmsApiClient = new MmsApiClientImpl(apiID, appPwd, version, masIP, masApiPort, mmsHandler);

//设置是否自动重连到服务器(可以不需要设置)

mmsApiClient.setTimingConnect(true);

//设置自动重连服务器相隔时间(单位:秒), 默认为30秒(可以不需要设置)

mmsApiClient.setConnectTime(60);

//设置与服务连接超时时长,单位:millisecond(可以不需要设置)

mmsApiClient.setConnectTimeout(100000);

//设置发送超时时长,单位:millisecond(可以不需要设置)

mmsApiClient.setSendTimeout(1000000);

int ret = mmsApiClient.getDestAddrsLimit();//获得彩信群发提交的数量限制

//获取网关连接状态(Connect:连接正常, Disconnect:断连, NotConnect:没有连

相关主题