infoX-MASAPI接口说明(JAVA)

1、infoX-MASAPI接口说明(JAVA)表格目录目 录1 总体说明1-11.1 JAVA接口概述1-21.2 读者范围1-21.3 相关约定1-22 API说明2-12.1 API概述2-22.2 基本数据类型介绍2-32.3 数据结构详细描述2-32.4 接口介绍2-72.4.1 DBSMProxy2-72.4.2 initConn2-72.4.3 initConn2-82.4.4 initConn2-92.4.5 sendSm2-92.4.6 sendMultiSm2-102.4.7 getReceivedSms2-112.4.8 querySmsResult2-122.4.9 log

2、in2-122.4.10 isConnected2-132.4.11 logout2-132.4.12 destroy2-133 安装使用指导3-153.1 介绍安装JAVA SMS API3-13.2 导入开发库3-13.3 方法调用3-14 示例代码4-14.1 初始化连接对象并登录4-24.2 发送短信4-24.3 查询短信发送情况4-44.4 查询短信接收情况4-44.5 销毁连接或者退出登录4-55 配置文件说明5-15.1 Apiconf.xml5-2文档版本 01 (2007-12-25)华为技术有限公司5-1表格目录表2-1 Java API的短信接口2-2表2-2 基本数据类

3、型简介2-3表2-3 SmReceiveBean字段说明2-3表2-4 SmSendBean字段说明2-4表2-5 SmSendResultBean字段说明2-6infoX-MASAPI接口说明(JAVA)5 配置文件说明1 总体说明关于本章本章描述内容如下表所示。标题内容1.1 JAVA接口概述介绍JAVA接口的背景知识。1.2 读者范围介绍本手册的读者对象。1.3 相关约定介绍本手册的相关约定。1.1 JAVA接口概述为了企业用户更加简便、灵活地实现相关的业务，企业业务系统可以接入MAS（Mobile Agent Server）的应用开发接口。MAS以JAVA的方式封装其短信接口，提供给企

4、业应用系统调用。该JAVA组件封装的对象可以提供短信单发接口、数据库初始化接口、用户登录初始化接口、短信接收接口、短信查询接口，其中短信查询接口用于查询已经发送的短信的情况。该版本不提供短信群发接口和点点通短信接口。1.2 读者范围本手册适用于华为公司MAS开发人员，企业IT管理、维护部门的相关开发人员。1.3 相关约定在本文中，每个API（Application Programming Interface）函数的描述由四部分组成：函数功能、函数原型、参数说明和返回码/值。函数功能描述API的主要功能。函数原型描述API原型，可直接拷贝程序中的函数原型代码。参数说明l 名称：参数名称l 如何理

5、解：对参数的简单解释l 备注：输入/输出参数的相关信息返回码/值API调用过程中的返回码/值，分为成功时的返回和异常返回。如果是异常返回，分别对每一个可能的异常进行详细描述，包括异常名称及相应说明。2 API说明关于本章本章描述内容如下表所示。标题内容2.1 API概述介绍JAVA短信API的基本组成。2.2 基本数据类型介绍各类数据结构介绍。2.1 API概述本文档定义了开发程序和MAS之间的所有短信API，如表2-1所示。表2-1 Java API的短信接口序号接口名称描述1public DBSMProxy()建立一个和MAS短信接口访问的代理对象。2public final void i

6、nitConn() throws Exception初始化和MAS系统的连接。3public final void initConn(String confFile) throws Exception初始化和MAS系统的连接。4public final void initConn(Map args) throws Exception初始化和MAS系统的连接。5public final int SendSm(SmSendBean sendBean) throws Exception发送短消息接口消息。6int sendMultiSm(SmSendBean sendBean)发送短消息接口，提交一

7、条群发消息到MAS的发送消息队列。7getReceivedSms(int maxCount, java.util.Date fromTime, java.util.Date endTime, java.lang.String orgAddr, java.lang.String destAddr) throws java.lang.Exception从MAS接收的消息队列中获取消息。8public final SmSendResultBean querySmsResult(int sm_id, java.util.Date fromTime,java.util.Date endTime,Stri

8、ng orgAddr,String destAddr) throws Exception查询短消息发送结果。9public final void login(String userName, String password) throws Exception根据用户名、密码登录系统，登录MAS，如果失败抛出异常。10boolean isConnected()判断API是否已经和MAS建立了连接。11public final void logout()退出登录函数仅仅清理当前的用户，可以在此基础上再次登录，连接仍然是存在的。12public final void destroy()销毁函数，将清

9、理连接，关闭数据库连接。2.2 基本数据类型介绍短信API中各种基本数据类型表示如下。表2-2 基本数据类型简介名称如何理解SmSendBean短信发送的消息结构体。SmReceiveBean接收消息的结构体描述。SmSendResultBean发送结果的消息体描述。2.3 数据结构详细描述SmReceiveBean接收消息的结构体描述。从MAS中获取消息，获取完成之后自动在tbl_smreceived表中把Reserve1字段配置为1。结构体各字段的说明请参见表2-3。SmReceiveBean继承于SmSendBean。表2-3 SmReceiveBean字段说明字段名字段类型字段说明sm

10、ActionIDprivate java.lang.String接收消息的请求类型。CMPP（China Mobile Peer to Peer）3消息点播使用，参见CMPP3协议。SMPP（Short Message Peer to Peer）不使用。smActionReasonIDprivate java.lang.String接收消息的请求原因。CMPP3消息点播使用。SMPP不使用。smDestAddrprivate java.lang.String接收消息的目的地址，对应的就是SP的接入号。smIdprivate int接收消息id（唯一标识），为-1的时候表明此消息为无效消息。sm

11、MessageIDprivate java.lang.String接收消息的类型。CMPP3消息点播使用。SMPP不使用。smMsgContentprivate java.lang.String接收消息的消息内容。smOrgAddrprivate java.lang.String接收消息的源地址，对应于发送方手机号码。smOrgAddrTypeprivate int接收消息的源地址类型，包括两种类型：l 掩码l 真实手机号码CMPP3消息点播使用。SMPP不使用。smRecvTimeprivate java.util.Date接收消息的接收时间。smReserve1private java.l

12、ang.String接收消息的保留标识，暂时没有使用。smReserve2private java.lang.String接收消息的保留标识，暂时没有使用。smServiceIDprivate java.lang.String接收消息的请求业务id。CMPP3消息点播使用。SMPP不使用。smTypeprivate int接收消息的类型。CMPP3消息点播使用，SMPP不使用。SmSendBeanSmSendBean是短信发送的消息结构体。在这个结构体中，必要填写的字段只有目的地址和消息内容，其他字段使用文件或者API中的缺省值。如果缺省值不对，将导致无法调用，调用者需要自己在调用API初始化

13、的时候，指定API属性配置文件，或者在程序中设定非必填字段。结构体各字段的说明请参见表2-4。表2-4 SmSendBean字段说明字段名字段类型字段说明priorityprotected int优先级别，对应于masdb的SENDLEVEL。sendSMIDprotected int返回发送到MAS的smid，唯一标识发送短信的ID。sendTypeprotected int发送类型。l 0：SMSEND_TYPE_TEXT，普通文本消息l 5：SMSEND_TYPE_WAPPUSH，WAP PUSH消息默认值：0smDestAddrsprotected java.lang.String目的

14、手机号码。填写接收该条短信的手机号码。可以为任意多个，API函数自动拆分成多条短信发送。该字段为必填字段。smDestAddrTypeprotected int目的地址类型。CMPP3消息点播使用，SMPP不使用。smFeeCodeprotected java.lang.String配合smFeeType，用来标识计费多少费用。l 在CMPP协议中，单位为分。l 在国外，需要根据当地的协议规定填写。smFeeTypeprotected java.lang.String计费类型，标识包月、封顶、单条、免费、不计费等。根据当地协议规定。l CMPP：请参考CMPP协议填写。l SMPP：无意义。s

15、mMessageIDprotected java.lang.StringCMPP3点播使用，SMPP无须填写。smMsgContentprotected java.lang.String短消息内容。此字段为必填字段。smMsgIDprotected java.lang.String用作第三方计费使用，SMPP等协议暂时不使用。smNeedStateReportprotected int该条消息是否需要状态报告。smOrgAddrprotected java.lang.String消息的源地址。如果是SP业务，则是对应的SP接入号。smReserve1protected int保留字段。smRe

16、serve2protected java.lang.String保留字段，暂无意义。SMSEND_TYPE_TEXTstatic int发送类型，等于此数值的时候为普通文本下发。SMSEND_TYPE_WAPPUSHstatic int发送类型，当发送类型为5的时候是WAP PUSH消息。格式：URL,消息正文（中间用逗号分隔）。smSendTimeprotected java.util.Date计划发送短信的时间。smServiceIdprotected java.lang.String在CMPP中对应于对应的service-id。在SMPP中对应业务类型字段。smSmTypeprotect

17、ed intSMType，用来标识消息类型，普通文本消息可以不填写。国外无须填写此字段。smTryTimesprotected int需要重发的次数。taskNameprotected java.lang.String应用程序可以自己定义任务名称。根据此任务名称可以从发送结果表中查询对应的一批任务。SmSendResultBeanSmSendResultBean为发送结果的消息体描述。结构体各字段的说明请参见表2-5。表2-5 SmSendResultBean字段说明字段名字段类型字段说明smFeeCodeprotected int短信发送时候的资费代码。CMPP、SGIP中单位为分，SMPP

18、暂时没有意义。smFeeTerminalIDprotected java.lang.String此条短消息的计费终端号码。CMPP、SGIP使用。smFeeTypeprotected java.lang.String计费用户类型。smFeeUserTypeprotected java.lang.String计费用户类型。CMPP、SGIP使用。smMsgFmtprotected int此条短消息的消息内容格式。smMsgStatusprotected java.lang.String短信的发送状态，即短信提交到短信网关后的错误码。请参见短信网关错误码参考。smRecvStatusprotect

19、ed java.lang.String短信的接收状态，即手机收到短信的状态码。l 0：成功l 其他：失败smRecvTimeprotected java.util.Date短信被手机终端收到的时间。当短信设置了需要状态报告的时候，本字段有意义。smResultIdprotected int每日发送结果的短信生成id。暂时未用。smSentTimeprotected java.util.Date短信提交到短信网关的时间。smSm_Typeprotected int目前此字段暂无意义。smSmIdprotected int代表此消息的唯一标识id。请参见send函数返回的sm_id。smSubmi

20、tTimeprotected java.util.Date短信提交到MAS的时间。smValidTimeprotected java.util.Date短信发送完成，被记录入MAS历史库的时间。2.4 接口介绍2.4.1 DBSMProxypublic DBSMProxy()函数描述该函数用于建立一个和MAS短信接口访问的代理对象。调用前提无。2.4.2 initConnpublic final void initConn(java.util.Map args)throws java.lang.Exception函数描述该函数根据指定的map参数，初始化和MAS的连接，根据传递的参数，初始化数

21、据库连接。这些字段必须小写。l 必要字段必须是String类型，包括： url：JDBC连接数据库的URL user：连接数据库的用户名 password：连接数据库的用户对应的密码l 非必要字段包括： test-sql：测试数据库连接的语句 name：数据库名 correct-charset：字符集 watch-interval：检测数据库是否连接正常的间隔时间 driver：数据库JDBC驱动调用前提无。参数args：初始化参数列表抛出调用错误的时候抛出异常，异常包括：l API使用状态不对l 初始化失败l 参数不对2.4.3 initConnpublic final void initC

22、onn(java.lang.String confFile)throws java.lang.Exception函数描述该函数根据指定的配置文件，初始化和MAS的连接。xml文件中关于数据库的描述路径：config/database/eiedb下包含配置。具体参数配置参见开发包的配置文件样例。调用前提无。参数confFile ：API配置文件路径抛出调用错误的时候抛出异常，异常包括：l API使用状态不对l 初始化失败l 参数不对2.4.4 initConnpublic final void initConn()throws java.lang.Exception函数描述该函数根据API内部约

23、定的默认的配置文件路径，初始化和MAS的连接。配置文件默认存放在相对当前工作目录下的apiConf，名称为：smApiConf.xml。调用前提无。抛出调用错误的时候抛出异常，异常包括：l API使用状态不对l 初始化失败l 参数不对2.4.5 sendSmpublic final int sendSm(SmSendBean sendBean)throws java.lang.Exception函数描述该函数为发送短消息接口，用于提交消息到MAS的发送消息队列。l 可以一次性填写任意多个号码，由API自行拆分成多条单发写入MAS单发队列。l 必要参数包括短信内容和目的地址。l 对于源地址、业务

24、id等参数，系统内部有默认配置值。 如果有短信属性配置文件存在，则从短信默认属性配置文件中加载。 如果调用者设定了这些值，将以调用这设定的这些值为准。l 如果消息内容超过了300字节，抛出异常。函数内部校验：调用实现类去发送短信。调用前提API已经初始化并且成功调用login()函数。参数sendBean：参见SmSendBean结构描述。返回int返回所需要的sm_id，有多少个目的地址，就返回多少个sm_id，并且参照destAddrs的顺序排列。抛出调用错误的时候抛出异常，异常包括：l API使用状态不对l 初始化失败l 参数不对2.4.6 sendMultiSmpublic final

25、 int sendMultiSm(SmSendBean sendBean)throws java.lang.Exception函数描述该函数为发送短消息接口，用于提交一条群发消息到信息机的发送消息队列。l 由API自行拆分成多条单发写入MAS单发队列。l 必要参数包括短信内容和目的地址。l 对于源地址、业务id等参数，系统内部有默认配置值。 如果有短信属性配置文件存在，则从短信默认属性配置文件中加载。 如果调用者设定了这些值，将以调用这设定的这些值为准。l 如果消息内容超过了300字节，抛出异常。l 对于消息目的地址过长，抛出异常，目的地址最多150个。函数内部校验：调用实现类去发送消息。调用

26、前提API已经初始化并且成功调用login()函数。参数sendBean：参见SmSendBean结构描述。 返回返回所需要的sm_id，类型为int，失败时返回-1。抛出调用错误的时候抛出异常，异常包括：l API使用状态不对l 初始化失败l 参数不对2.4.7 getReceivedSmspublic final SmReceiveBean getReceivedSms(int maxCount,java.util.Date fromTime,java.util.Date endTime,java.lang.String orgAddr,java.lang.String destAddr)

27、throws java.lang.Exception函数描述该函数用于从MAS接收的消息队列中获取消息。查询条件为最大返回条数、时间段、源地址、目的地址。以上条件任意组合，是“与”的关系，如果某个参数为null，则此条件无效。调用前提API已经初始化并且成功调用login()函数。参数l maxCount：最大返回条数，如果为正数则最大只返回这些条数，如果小于等于0，则不限制查询返回结果数。l fromTime：指定获取接收短信的起始时间范围，如果为空，则不限制。l endTime：指定获取接收短信的结束时间范围，如果为空，则不限制。l orgAddr：指定获取接收短信的源地址，比如手机，获取

28、时模糊匹配前缀，如果为空，则此条件限制失效。l destAddr：指定获取接收短信的目的地址，比如接入号，获取时模糊匹配前缀，如果为空，则此条件限制失效。返回int返回所需要的sm_id，有多少个目的地址，就返回多少个sm_id。如果没有查询到数据，则返回一个长度为0的数组抛出调用错误的时候抛出异常，异常包括：l API使用状态不对l 初始化失败l 参数不对2.4.8 querySmsResultpublic final SmSendResultBean querySmsResult(int sm_id,java.util.Date fromTime,java.util.Date endTim

29、e,java.lang.String orgAddr,java.lang.String destAddr)throws java.lang.Exception函数描述该函数用于查询短信发送结果。以下关系全部是“与”的关系，指定的参数越多，限制条件越多。l sm_id>0，并且查询起始、结束时间只要有一个为空，则默认从近3天之内的消息中查询符合此sm_id的消息，否则，按照指定的起始、结束时间查询。l 如果sm_id0，则sm_id不生效，不限制sm_id。l 对于orgAddr，destAddr，如果为空则查询所有号码，如果不为空，则条件生效。l 只有当起始时间和结束时间都指定了，该查询

30、才按照指定的时间段进行查询，否则只查询近3天的消息。调用前提API已经初始化并且成功调用login()函数。参数l sm_id：如果为-1，则此不生效，大于0的时候，按照此sm_id查询。l fromTime：开始时间，为空，则不生效，时间为当前时间的3天前。l endTime：结束时间，为空，则不生效，时间为当前时间。l orgAddr：源地址，比如接入号，如果为空，则此条件不生效。l destAddr：目的地址，比如手机号码，如果为空，则此条件不生效。返回SmSendResultBean返回的查询结果，任何时候，都不返回null，没有查询到结果，返回长度为0的数组。抛出调用错误的时候抛出异

31、常，异常包括：l API使用状态不对l 初始化失败l 参数不对2.4.9 loginpublic final void login(java.lang.String userName, java.lang.String password)throws java.lang.Exception函数说明该函数用于根据用户名、密码登录MAS应用接口。如果失败抛出异常，这里的用户名密码，参数对应于MAS Web界面登录的用户名、密码。调用前提已经初始化连接。参数l userName：登录MAS的用户名，和登录MAS Web界面的用户名一样。l password：登录MAS应用的密码，和登录MAS Web

32、界面的密码一样。抛出调用错误的时候抛出异常，异常包括：l API使用状态不对l 初始化失败l 参数不对2.4.10 isConnectedpublic boolean isConnected()该函数用于检查API是否已经与MAS建立了连接。调用前提：API已经初始化并且成功调用login()函数。2.4.11 logoutpublic final void logout()该函数用于清理当前登录的用户，可以在此基础上再次登录，连接仍然存在。调用前提已经建立连接，并登录应用接口。抛出本函数不抛出异常。2.4.12 destroypublic final void destroy()函数描述该函

33、数为销毁函数，用于清理连接，关闭数据库连接。如果调用函数的时候没有退出登录，则将直接退出登录，然后销毁连接。只有API处于已经可用状态，或者已经建立连接状态下可以调用，否则调用无效。调用前提已经建立连接或者已经登录应用接口。抛出本函数不抛出异常。3 安装使用指导关于本章本章描述内容如下表所示。标题内容3.1 介绍安装JAVA SMS API介绍安装JAVA SMS API3.2 导入开发库介绍导入开发库。3.3 方法调用介绍JAVA SMS API接口函数调用示例。3.1 介绍安装JAVA SMS API请直接拷贝，放入classpath中即可。3.2 导入开发库根据使用的开发工具不同，导入方

34、法略有差异，但是都是把java sms api开发包导入到环境变量classpath中，以jbuilder 2006为例：步骤 1 在jbuilder 2006选择“Project > Project properties > path > required libraries > add > new”菜单，根据向导创建一个lib（jbuilder的library）。步骤 2 选择“Project > Project properties > path > required libraries > add”，选择刚才创建的lib，添加到工程

35、中。-结束3.3 方法调用步骤 1 以jbuilder 2006为例，按照“3.2 导入开发库”的方法在工程中添加开发库。步骤 2 新建一个类DBSMProxyTest。步骤 3 拷贝如下代码到新建的class文件中。修改程序中的如下信息：l 连接MAS短信应用接口的URLl DB登录用户名l DB登录密码l 业务登录用户名l 业务登录密码-结束4 示例代码关于本章本章描述内容如下表所示。标题内容4.1 初始化连接对象并登录初始化连接对象并登录代码举例。4.2 发送短信发送短信代码举例。4.3 查询短信发送情况查询短信发送情况代码举例。4.4 查询短信接收情况查询短信接收情况代码举例。4.5

36、销毁连接或者退出登录销毁连接或者退出登录代码举例。4.1 初始化连接对象并登录测试代码示例：DBSMProxy smproxy = new DBSMProxy(); Map paras = new HashMap(); /MAS短信接口DB的URL。paras.put("url","jdbc:microsoft:sqlserver:/10.71.99.70:1433;DatabaseName=db_customsms");/MAS短信接口db登录用户名。paras.put("user","customsms");/

37、MAS短信接口db登录的密码。paras.put("password","123456");/以下示例提供了3种初始化连接的方法。 smproxy.initConn(paras);/通过上面设定的参数初始化。/ smproxy.initConn();/自动查找配置文件的方式初始化，参见上面函数说明。/手动查找配置文件的方式，参见上面函数说明。/ smproxy.initConn("./apiconf/smapiconf.xml");/登录MASmas短信应用接口，业务登录用户名、业务登录密码。 smproxy.login("

38、admin", "0");4.2 发送短信/* * 发送测试代码样例。 * param smproxy DBSMProxy * param count int * throws Exception */ public static final void testSend(DBSMProxy smproxy, int count) throws Exception SmSendBean bean = new SmSendBean();ArrayList<String> arrs = new ArrayList();/构造多个手机号码，目的地址。 for

39、(int index = 0; index < count; index+) arrs.add("1380000" + index); String addrs = new Stringarrs.size(); arrs.toArray(addrs);bean.setSmDestAddrs(addrs);/构造短信内容。 bean.setSmMsgContent("sms content test info.!#$%&*()_+|.");long firstTime = System.currentTimeMillis();/调用发送接口。

40、 int ret = smproxy.SendSms(bean); long lastTime = System.currentTimeMillis(); System.out.println("="); System.out.println(" inserted:" + count + " records,consumed " + (lastTime - firstTime) + " ms"); System.out.println(" avg Speed:" + (count) * 1000

41、.0 / (lastTime - firstTime); System.out.println("="); System.out.print("returned sm_id(s):"); for (int index = 0; index < ret.length; index+) System.out.print(" " + retindex); System.out.println(""); 4.3 查询短信发送情况/* * 查询消息发送结果，代码样例。 * param smproxy DBSMProxy * throws Exception */ public static final void testQuerysmResult(DBSMProxy smproxy) throws Exception /构造查询条件，入口参数详细说明参见上面函数说明。 SmSendResultBean beans = smproxy.querySmsResult(-1 , new java.util.Date(System.currentTimeMillis() - 86400