中国移动MM7-API用户手册.doc

《中国移动MM7-API用户手册.doc》由会员分享，可在线阅读，更多相关《中国移动MM7-API用户手册.doc（135页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、Four short words sum up what has lifted most successful individuals above the crowd: a little bit more.-author-date中国移动MM7-API用户手册中兴MM7 API用户手册中国移动MM7 API用户手册版本：V1.5.1 中国移动集团公司修改记录文件编号版本号拟制人/修改人拟制/修改日期更改理由主要更改内容（写要点即可）V1.1胡冬梅2004.03.22修改、整理V1.2胡冬梅2004.04.14增加内容增加安装说明V1.3胡冬梅2004.4.21增加内容增加状态码等说明 V1.5

2、.1胡冬梅2004.5.12增加内容增加获取API版本信息、API返回码说明等目 录1.概述52.概念52.1企业代码52.2服务代码62.3业务代码62.3.1上行业务的业务代码规范62.3.2下行业务的业务代码规范82.4操作指令码102.5下行业务112.6上行业务112.7递送报告113.安装方法113.1 MM7 API的使用113.2配置文件的设置114.开发方法134.1 VASP接收传送请求（上行业务）134.1.1 方式1：普通应用程序中的用法134.1.2 方式2：Web应用程序中的用法144.2发送多媒体消息的过程（下行业务）154.2.1准备154.2.2创建待发送消息

3、164.2.2.1 创建提交增值业务的多媒体消息（MM7SubmitReq）164.2.2.2 创建取消多媒体消息（MM7CancelReq）184.2.2.3 创建替换多媒体消息（MM7ReplaceReq）184.2.3 创建消息内容体194.2.4 发送多媒体消息204.2.5发送MM7SubmitReq消息到移动终端实例204.3 VASP接收传送消息以及发送提交消息实例214.4 VASP接收状态报告（上行业务）244.4.1方式1：普通应用程序中的用法244.4.2方式2：Web应用程序中的用法254.5 VASP接收读后回复报告（上行业务）264.5.1方式1：普通应用程序中的用

4、法264.5.2方式2：Web应用程序中的用法274.6 发送取消消息（下行业务）274.7 发送替换消息（下行业务）285.开发过程中需用的一些Status解释295.1 关于VASP接收到消息后设置返回响应（Res）的状态码及状态报告的解释295.2 关于VASP收到DeliverReq中MMStatus的解释305.3 关于VASP收到ReadReplyReq中ReadStatus的解释306.获取MM7 API版本信息的方法307. MM7 API返回StatusCode说明301.概述该文档说明了SP如何使用中国移动集团公司的MM7 API程序与彩信中心进行对接，实现MM7接口的通讯

5、，开发增值业务应用。该MM7 API是使用纯Java开发的，使用的JDK的版本为JDK1.4.0。所以使用该API进行开发时，要求使用的JDK版本必须是JDK1.4.0以上版本。该API所使用的通讯承载协议是HTTP/1.1。缩略词： MM： Multimedia Message （多媒体消息） MMS： Multimedia Message Service（多媒体消息服务） MMSC： Multimedia Message Service Center（多媒体消息服务中心） VAS： Value Added Service（增值业务） SP： Service Provider（业务提供商）

6、HTTP： Hypertext Transfer Protocol（超文本传输协议）2.概念2.1企业代码企业代码是企业身份的标识，网络中地址翻译、计费、结算等均以企业代码为依据。企业代码的数据需要在MMSC和BOSS系统中进行配置。企业代码以数字表示，共6位，从“8XY000”至“8XY999”，其中“XY”为各移动分公司代码。彩信全网业务的SP企业代码为8XY0018XY999。（目前短信全网业务的企业代码为9XY0019XY500，WAP全网业务的企业代码为9XY5019XY999。）彩信地方业务的SP企业代码由各地方移动公司按照业务许可的顺序依次分配制定，“XY”具体分配情况见相关表格

7、。2.2服务代码服务代码是：用户使用彩信的发送、上传等上行类业务时，需要输入的接收方号码；或SP在根据用户的点播请求在向用户发送、下载等下行类业务时，用户终端中显示的发送方的号码。服务代码的数据需要在MMSC上进行配置，用于路由的查找和状态报告的返回。服务代码以数字表示。全国业务的服务代码长度统一为4位，即“1000”“9999”；本地业务服务代码长度统一为5位，即“01000”“09999”。以下号码或号段暂不分配：13XX（XX00-99）、20XX（XX0199）、168X（X0-9）、186X（X=0-9）、1258/1259、172X（X=0-9）、6XXX、7XXX。上述代码的分配

8、和使用情况均可以在上查询。如果SP已经开展了短信等业务，原则上彩信的服务代码依照SP原有的服务代码进行分配，以保证用户的使用习惯。目前全网业务的服务代码，由集团公司统一分配。2.3业务代码业务代码表示业务类别，并且区分不同业务的信息服务费。业务代码的数据需要在MMSC和BOSS系统中进行配置。业务代码用数字表示，并且不能使用000。为便于进行业务统计和分析，业务代码尽量按照不同的业务分类如下：互联网点播类： 以1开头 WAP点播类： 以2开头短信点播类： 以3开头 STK点播类： 以4开头彩信点播类： 以0开头业务代码在遵循原则的前提下其余内容由SP自己制定。2.3.1上行业务的业务代码规范上

9、行业务的业务代码为三位，其构成如下：第1位：0、7、9开头的业务代码保留，其他代码由彩信SP自行编排。第23位：由彩信SP自行编排特例：如果用户直接给四位服务代码发送上行彩信，系统会默认加上业务代码“0”，该业务代码默认开通，仅用于上行彩信到服务代码。2.3.2下行业务的业务代码规范下行业务的业务代码为六位，其构成如下：第1位：功能标识位，目前有如下两种选择：l 1，代表一般下行业务l 7，代表用于“先机时代”项目中手机内置并参与渠道分成的业务l 6，代表用于集团客户应用的业务（免费）其他数字目前保留。第2位：彩信业务一级分类，具体如下面表格：第3位：彩信业务二级分类，具体如下面表格：一级分类

10、及标识代码二级分类及标识代码新闻天气（1）天气预报（1）热点快讯（2）社会新闻（3）体育新闻（4）娱乐新闻（5）财经新闻（6）综合新闻（0）游戏娱乐（2）聊天交友（1）笑话幽默（2）彩信游戏（3）影音视线（4）互动有奖（5）五花八门（0）时尚生活（3）时尚有约（1）车迷世界（2）文化教育（3）情感画廊（4）爱情家庭（5）两性健康（6）证券财经（7）位置服务（8）五花八门（0）卡通动漫（4）欧美（1）日本（2）韩国（3）港台（4）本地原创（5）五花八门（0）彩信铃声（5）明星专辑（1）精品影视（2）流行音乐（3）古典音乐（4）卡拉OK（5）特殊音效（6）五花八门（0）彩图动画（6）人物剪影（1）

11、动物一族（2）美丽心情（3）温馨祝福（4）电影名画（5）体育纵横（6）大千世界（7）3D动画（8）五花八门（0）彩信DIY（7）贺卡类（1）形象类（2）文字类（3）五花八门（0）特色用途（0）免费客服（1）优惠套餐（2）第4位：业务模式位，各个模式及其数字标识如下：l 1：按条点播l 2：按条定制l 3：包月定制l 4：包月点播第56位：由彩信SP自行编排2.4操作指令码操作指令码是指用户通过短信点播或定制彩信业务时，在短信的信息体内输入的代码，或用户上行发送彩信时，在彩信消息体内的文本信息中输入的代码。操作指令码用于标识对彩信的处理方式。此代码出现在短信或彩信的消息体内，由SP自行处理，彩信

12、中心不负责处理该代码。在短信中输入的操作指令码应严格区分用户是点播、定制短信业务还是彩信业务。如果用户通过短信点播或定制彩信业务，操作指令码应以CX开头。如：用户在短信或彩信文本信息体内输入“CX XW”发送至8888，就是定制新浪提供的彩信图片新闻业务。2.5下行业务由SP主动发起的业务。这里主要指SP向MMSC发起的业务。2.6上行业务SP被动接收的业务。这里主要指从MMSC那里接收业务。2.7递送报告报告是接收方（终端）对接收到消息的处理方式信息。递送报告指MMSC在获取这个报告后把这个信息发送给发送方（SP）。接收方对消息的处理可能是接收或者拒绝等。处理流程如下：l SP发送消息（通过

13、MMSC）给终端，并且要求递送报告；l 终端接收到消息后做相应处理（接收或拒绝）；l MMSC把终端对消息的处理信息（递送报告）发送给SP。3.安装方法 这里主要介绍一下如何将MM7 API运用到VASP自己开发的程序中以及在配置文件中需要注意修改的地方。3.1 MM7 API的使用在VASP用Java开发自己程序时，只要将中国移动集团公司提供的mm7api.jar和lib下的所有的Jar文件加入到classpath中即可。3.2配置文件的设置 配置文件mm7Config.xml需要根据SP情况进行修改。vasp:MM7Config xmlns:vasp=1zxmezxme100000000c

14、:vas_log1100120200UTF-81 /mm7192.120.231.180true192.120.231.2288050100005一些地方需要进行修改，下面一一说明：1表示VASP作为服务端接收消息时是否进行鉴权或进行什么样的鉴权，0表示不鉴权，1表示进行基本鉴权，2表示进行摘要鉴权。zxmezxme表示彩信中心对VASP进行鉴权时的用户名和密码，同时也是VASP对接入的彩信中心进行鉴权时用户名和密码，是双向的，要VASP和MMSC双方进行约定。c:vas_log表示日志存放的路径，在Windows操作系统下和Linux下是不一样的，要注意进行修改。1表示MMSC网关的序号，需

15、要从MMSC处得到。 /mm7192.120.231.180分别表示MMSC网关的URL地址和IP（或主机名），也需要MMSC处得到。这里也可以填成ip:port。例如：192.120.231.180:8080,不填端口号使用默认端口号80。192.120.231.22880表示当VASP用应用程序方式进行接收消息时的监听地址和端口号。以上为这个配置文件中主要需要注意修改的地方，当然其他的内容也可以进行修改，如1可以根据需要进行修改，0表示不产生日志；1表示产生错误日志；3表示产生信息日志；6表示产生完整信息日志。10000表示设置发送的超时时间，到发送超过这个时间，则自动进行重新发送。5表示

16、设置重发的次数，建议在10次以下，一般用35次即可。4.开发方法这里主要介绍从SP接收MMSC发过来的DeliverReq开始，到SP发送SubmitReq到MMSC的整个流程，SP所需要做的工作。4.1 VASP接收传送请求（上行业务）VASP接收可以有两种方式：l 如果SP的增值应用是一个普通应用程序，可以使用方式1，即接收代理会自动打开一个监听端口，启动一个监听线程来接收来自MMSC的多媒体消息；l 如果SP的增值应用是一个Web应用，则可以使用方式2，即接收代理作为一个Servlet运行，并自动处理从HttpRequest中搜索数据，并解码成多媒体消息。4.1.1 方式1：普通应用程序

17、中的用法public class MyReceiver extends MM7Receiver/定义一个MM7DeliverReq，以便得到MMSC发过来的Deliver消息。（必备）public static MM7DeliverReq deliverReq = new MM7DeliverReq();/Main方法public static void main(String args)/初始化VASPMM7Config mm7Config = new MM7Config(“./config/mm7Config.xml”);/设置ConnConfig.xml文件的路径mm7Config.se

18、tConnConfigName(“./config/ConnConfig.xml”); /必备/构造MyReceiverMyReciever receiver = new MyReceiver();myReceiver.setConfig(mm7Config); /必备/创建MM7消息发送接口MM7Sender mm7Sender = new MM7Sender(mm7Config);/启动接收器receiver.start();public MM7VASPRes doDeliver(MM7DeliverReq request)/*接收从MMSC发过来的传送消息，以便取出其中的部分值构造提交消

19、息或得到一些有用信息，如MMSC的标识符等*/deliverReq = request;System.out.println(“收到手机”+request.getSender()+“提交的消息，标题为：”+request.getSubject(); System.out.println(MMSC的标识符为：+request. GetMMSRelayServerID();/SP需要进行一些处理，例如构建MM7DeliverRes消息，设置ServiceCode或StatusCodeMM7DeliverRes mm7DeliverRes = new MM7DeliverRes();mm7Deliv

20、erRes.setServiceCode(服务代码); /设置ServiceCode，可选mm7DeliverRes.setStatusCode(MMConstants.RequestStatus.SUCCESS);/*设置请求完成状态，必备，以便表明SP已经接收到传送消息。一般设1000。*/mm7DeliverRes.setStatusText(所用状态文本说明); /*设置所用状态的文本说明，应限定请求状态，可选*/返回给MM7 API，以便API将MM7DeliverRes返回给MMSC。return(MM7VASPRes)mm7DeliverRes;4.1.2 方式2：Web应用程序

21、中的用法public class MyReceiver extends MM7RecieveServletpublic MM7VASPRes doDeliver(MM7DeliverReq request)System.out.println(“收到手机”+request.getSender()+“提交的消息，标题为：”+request.getSubject();System.out.println(MMSC的标识符为：+request. GetMMSRelayServerID();/SP需要进行一些处理，例如构建MM7DeliverRes消息，设置ServiceCode或StatusCode

22、MM7DeliverRes mm7DeliverRes = new MM7DeliverRes();mm7DeliverRes.setServiceCode(服务代码); /设置ServiceCode，可选mm7DeliverRes.setStatusCode(MMConstants.RequestStatus.SUCCESS);/*设置请求完成状态，必备，以便表明SP已经接收到传送消息。一般设1000。*/mm7DeliverRes.setStatusText(所用状态文本说明); /*设置所用状态的文本说明，应限定请求状态，可选*/返回给MM7 API，以便API将MM7DeliverRe

23、s返回给MMSC。return(MM7VASPRes)mm7DeliverRes;4.2发送多媒体消息的过程（下行业务）发送多媒体消息的过程就是使用MM7 API组织消息，并通过MM7Sender发送给MMSC的过程。主要步骤如下：4.2.1准备1. 初始化VASP初始化VASP使用的是MM7Config类，该类定义了有关本VASP和对应的MMSC的配置信息。系统在初始化时，必须对该对象进行定义，它将用于通信类的控制。MM7Config mm7Config = new MM7Config(./config/mm7Config.xml );其中mm7Config.xml为配置文件，其格式如下：v

24、asp:MM7Config xmlns:vasp=1111111111111100000c:vas_log1UTF-8/mm7202.202.202.202!MMSC网关的序号9100101102.102.102.102801001010002. 创建MM7消息发送接口：创建发送接口使用的是MM7Sender类，其中已经封装了和MMSC连接的通讯机制，使用时只要创建它的一个带MM7Config参数的实例即可。MM7Sender mm7Sender = new MM7Sender(mm7Config);4.2.2创建待发送消息创建待发送消息使用的类均是由MM7Message继承得到的。主要有MM

25、7SubmitReq、MM7CancelReq、MM7ReplaceReq等类，具体设置方法将分别进行介绍。4.2.2.1 创建提交增值业务的多媒体消息（MM7SubmitReq）1.创建消息对象MM7SubmitReq submitReq = new MM7SubmitReq();2.设置消息属性submitReq.setTransactionID(关联标识); /*设置MM7_submit.REQ/MM7_submit.RES对的标识，必备*/submitReq.setVASPID(SP代码); /设置SP代码，必备submitReq.setVASID(服务代码); /设置服务代码，必备s

26、ubmitReq.setServiceCode(业务代码); /设置业务代码，必备submitReq.setSenderAddress(MM始发方的地址);设置MM始发方的地址（填写SP的服务代码，或者填写让用户回复SP的长号码，长号码构成：SP的服务代码业务代码操作码），必备submitReq.setChargedPartyID(“付费方手机号码”); /设置付费方的手机号码，必备submitReq.setTo(接收方地址); /设置接收方MM的地址submitReq.addTo(单个接受方地址); /增加单个接受方地址submitReq.setCc(抄送方地址); /设置抄送方MM的地址s

27、ubmitReq.addCc(单个抄送方地址); /增加单个抄送方地址submitReq.setBcc(密送方地址); /设置密送方MM的地址submitReq.addBcc(单个密送方地址); /增加单个密送方地址注：在设置或增加To，Cc和Bcc时，至少需要设置其中一个，这些地址可能存在多个地址或使用指示使用分发表的别名。可以标记仅供参考的地址。submitReq.setLinkedID(链接标识); /*设置链接标识，标识传送至VASP的上一个有效消息的对应关系；可选*/submitReq.setMessageClass(MM的类别); /*设置MM的类别（例如，广告、信息服务和计费），

28、可选，具体有：Auto、Personal、Advertisement、Informational*/submitReq.setTimeStamp(提交MM的日期和时间); /*提交MM的时间和日期（时间戳）,格式如2004-02-09T10：21：07，可选*/submitReq.setExpiryDate(指定超时时间); /*设置MM指定的超时时间（绝对或相对时间），可选*/submitReq.setEarliestDeliveryTime(最早理想时间); /*设置将MM传送给接收方的最早理想时间(绝对或相对时间)，可选*/submitReq.setDeliveryReport(发送报告

29、的请求); /*设置是否需要发送报告的请求（boolean值）,可选*/submitReq.setReadReply(需要读取报告的请求); /*设置通过请求传送一个读取报告进行确认，可选*/submitReq.setReplyCharging(应答计费的请求); /*设置应答计费的请求（boolean值），可选*/submitReq.setReplyDeadline(提交应答的最迟时间); /*设置在应答计费的情况下，向接收方提交应答的最迟时间（绝对或相对时间），可选*/submitReq.setReplyChargingSize(应答MM的最大大小); /*设置在应答计费的情况下，提供给接

30、收方的应答MM的最大大小，可选*/submitReq.setPriority(消息的优先级); /*消息的优先级（重要性）（0=最低优先级，1=正常，2=紧急），byte类型的值，可选*/submitReq.setSubject(多媒体消息的标题); /*设置多媒体消息的标题，可选*/submitReq.setAllowAdaptations(VASP是否允许修改内容); /*设置VASP是否允许修改内容（boolean值，默认为真），可选*/submitReq.setChargedParty(VASP所提交MM的付费方); /*设置VASP所提交MM的付费方，例如，发送方、接收方、发送方和接

31、收方或两方均不付费，可选，0：Sender、1：Recipients、2：Both、3：Neither、4：ThirdParty*/submitReq.setContent(多媒体消息的内容); /*设置多媒体消息的内容，可选，注意当要设置时，一定要设置其ContentType。*/submitReq.setDistributionIndicator(是否可重新分发); /*设置VASP是否可重新分发MM的内容（boolean值，true为可以，false为不可以），可选*/4.2.2.2 创建取消多媒体消息（MM7CancelReq）1.创建消息对象MM7CancelReq cancelRe

32、q = new MM7CancelReq();2. 设置消息属性cancelReq.setTransactionID(关联标识); /*MM7_cancel.REQ/MM7_cancel.RES对的标识，必备*/cancelReq.setVASPID(SP代码); /*设置SP代码，可选*/cancelReq.setVASID(服务代码); /*设置服务代码，可选*/cancelReq.setSenderAddress(MM始发方地址); /*设置MM始发方地址，可选*/cancelReq.setMessageID(待取消的消息的标识符); /*设置待取消的消息的标识符，必备*/4.2.2.3

33、 创建替换多媒体消息（MM7ReplaceReq）1.创建消息对象MM7ReplaceReq replaceReq = new MM7ReplaceReq();2. 设置消息属性replaceReq.setTransactionID(关联标识); /*设置MM7_replace.REQ/MM7_replace.RES对的标识，必备*/replaceReq.setVASPID(SP代码); /*设置SP代码，可选*/replaceReq.setVASID(服务代码); /*设置服务代码，可选*/replaceReq.setMessageID(被当前消息所替换的消息的标识符); /*被当前消息所替

34、换的消息的标识符，必备*/replaceReq.setServiceCode(业务代码); /*设置业务代码，可选*/replaceReq.setTimeStamp(提交MM的日期和时间); /*设置提交MM的时间和日期（时间戳）,格式如2004-02-09T10：21：07，可选*/replaceReq.setEarliestDeliveryTime(最早理想时间); /*设置将MM传送给接收方的最早理想时间(绝对或相对时间)，可选*/replaceReq.setReadReply(需要读取报告的请求); /*设置通过请求传送一个读取报告进行确认（boolean值，true为需要，false

35、为不需要），可选*/replaceReq.setAllowAdaptations(VASP是否允许修改内容); /*设置VASP是否允许修改内容（boolean值，默认为真），可选*/replaceReq.setContent(多媒体消息内容); /*设置多媒体消息的内容，可选，注意当要设置时，一定要设置其ContentType。*/replaceReq.setDistributionIndicator(是否可重新分发); /*设置VASP是否可重新分发MM的内容（boolean值，true为可以，false为不可以），可选*/4.2.3 创建消息内容体每个消息内容体就是一个MMContent

36、实例，可以添加多个消息内容体，但是所有消息内容体大小之和不能超过MMSC允许大小（目前最大支持128K）。MMContent content = new MMContent();/*设置附件的类型，若不包含SMIL格式的文件，则设置类型为MMConstants.ContentType. MULTIPART_MIXED，若包含SMIL格式的文件，则设置类型为MMConstants.ContentType. MULTIPART_RELATED*/*content.setContentType(MMConstants.ContentType. MULTIPART_MIXED);/*添加类型为Gif的

37、附件一 */MMContent sub1 = MMContent.createFromFile(f:yellow.gif);sub1.setContentID(1.gif); /可以不设/*设置子附件的类型，有两种设置方式：一种是在setContentType里面填写MMConstants.ContentType里面定义的常量，另一种是在setContentType里面填写一个String的类型，如text/plain等。*/sub1.setContentType(MMConstants.ContentType.GIF); /一定要设置content.addSubContent(sub1);/

38、*添加类型为Txt的附件二*/MMContent sub2 = MMContent.createFromString(This is a Test2!);sub2.setContentType(MMConstants.ContentType. TEXT); /一定要设置sub2.setContentID(2.txt);content.addSubContent(sub2);/*将附件进行设置，设需发送消息为MM7SubmitReq*/submitReq.setContent(content);4.2.4 发送多媒体消息调用MM7Sender的send方法发送多媒体消息，返回MM7RSRes类型的消息。举例，发送MM7SubmitReq类型的消息：MM7RSRes res = mm7Sender.send(submitReq);