中国移动MMAPI用户手册模板.doc

中国移动MM7 API用户手册版本：V1.5.3 中国移动集团企业修改统计文件编号版本号拟制人/修改人拟制/修改日期更改理由关键更改内容（写关键点即可）V1.1胡冬梅.03.22修改、整理V1.2胡冬梅.04.14增加内容增加安装说明V1.3胡冬梅.4.21增加内容增加状态码等说明 V1.5.1胡冬梅.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创建待发送消息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：一般应用程序中使用方法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接口通讯，开发增值业务应用。该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（业务提供商） HTTP： Hypertext Transfer Protocol（超文本传输协议）2.概念2.1企业代码企业代码是企业身份标识，网络中地址翻译、计费、结算等均以企业代码为依据。企业代码数据需要在MMSC和BOSS系统中进行配置。企业代码以数字表示，共6位，从“8XY000”至“8XY999”，其中“XY”为各移动分企业代码。彩信全网业务SP企业代码为8XY0018XY999。（现在短信全网业务企业代码为9XY0019XY500，WAP全网业务企业代码为9XY5019XY999。）彩信地方业务SP企业代码由各地方移动企业根据业务许可次序依次分配制订，“XY”具体分配情况见相关表格。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。上述代码分配和使用情况均能够在.com上查询。假如SP已经开展了短信等业务，标准上彩信服务代码依据SP原有服务代码进行分配，以确保用户使用习惯。现在全网业务服务代码，由集团企业统一分配。2.3业务代码业务代码表示业务类别，而且区分不一样业务信息服务费。业务代码数据需要在MMSC和BOSS系统中进行配置。业务代码用数字表示，而且不能使用000。为便于进行业务统计和分析，业务代码尽可能根据不一样业务分类以下：互联网点播类： 以1开头 WAP点播类： 以2开头短信点播类： 以3开头 STK点播类： 以4开头彩信点播类： 以0开头业务代码在遵照标准前提下其它内容由SP自己制订。2.3.1上行业务业务代码规范上行业务业务代码为三位，其组成以下：第1位：0、7、9开头业务代码保留，其它代码由彩信SP自行编排。第23位：由彩信SP自行编排特例：假如用户直接给四位服务代码发送上行彩信，系统会默认加上业务代码“0”，该业务代码默认开通，仅用于上行彩信到服务代码。2.3.2下行业务业务代码规范下行业务业务代码为六位，其组成以下：第1位：功效标识位，现在有以下两种选择：l 1，代表通常下行业务l 7，代表用于“先机时代”项目中手机内置并参与渠道分成业务l 6，代表用于集团用户应用业务（无偿）其它数字现在保留。第2位：彩信业务一级分类，具体以下面表格：第3位：彩信业务二级分类，具体以下面表格：一级分类及标识代码二级分类及标识代码新闻天气（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）动物一族（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自行处理，彩信中心不负责处理该代码。在短信中输入操作指令码应严格区分用户是点播、定制短信业务还是彩信业务。假如用户经过短信点播或定制彩信业务，操作指令码应以CX开头。如：用户在短信或彩信文本信息体内输入“CX XW”发送至8888，就是定制新浪提供彩信图片新闻业务。2.5下行业务由SP主动提议业务。这里关键指SP向MMSC提议业务。2.6上行业务SP被动接收业务。这里关键指从MMSC那里接收业务。2.7递送汇报汇报是接收方（终端）对接收到消息处理方法信息。递送汇报指MMSC在获取这个汇报后把这个信息发送给发送方（SP）。接收方对消息处理可能是接收或拒绝等。处理步骤以下：l SP发送消息（经过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情况进行修改。1zxmezxmec: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网关序号，需要从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表示产生完整信息日志。90000表示设置发送超时时间，若发送超出这个时间，则自动进行重新发送。2表示设置重发次数，提议在3次以下，通常见2次即可。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：一般应用程序中使用方法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.setConnConfigName(“./config/ConnConfig.xml”); /必备/结构MyReceiverMyReciever receiver = new MyReceiver();myReceiver.setConfig(mm7Config); /必备/创建MM7消息发送接口MM7Sender mm7Sender = new MM7Sender(mm7Config);/开启接收器receiver.start();for(;);public MM7VASPRes doDeliver(MM7DeliverReq request)/*接收从MMSC发过来传送消息，方便取出其中部分值结构提交消息或得到部分有用信息，如MMSC标识符等*/deliverReq = request;System.out.println(“收到手机”+request.getSender()+“提交消息，标题为：”+request.getSubject(); System.out.println(MMSC标识符为：+request. GetMMSRelayServerID();/SP需要进行部分处理，比如构建MM7DeliverRes消息，设置ServiceCode或StatusCodeMM7DeliverRes mm7DeliverRes = new MM7DeliverRes();mm7DeliverRes.setServiceCode(服务代码); /设置ServiceCode，可选mm7DeliverRes.setStatusCode(MMConstants.RequestStatus.SUCCESS);/*设置请求完成状态，必备，方便表明SP已经接收到传送消息。通常设1000。*/mm7DeliverRes.setStatusText(所用状态文本说明); /*设置所用状态文本说明，应限定请求状态，可选*/返回给MM7 API，方便API将MM7DeliverRes返回给MMSC。return(MM7VASPRes)mm7DeliverRes;4.1.2 方法2：Web应用程序中使用方法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或StatusCodeMM7DeliverRes mm7DeliverRes = new MM7DeliverRes();mm7DeliverRes.setServiceCode(服务代码); /设置ServiceCode，可选mm7DeliverRes.setStatusCode(MMConstants.RequestStatus.SUCCESS);/*设置请求完成状态，必备，方便表明SP已经接收到传送消息。通常设1000。*/mm7DeliverRes.setStatusText(所用状态文本说明); /*设置所用状态文本说明，应限定请求状态，可选*/返回给MM7 API，方便API将MM7DeliverRes返回给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为配置文件，其格式以下：0111111111111100000c:vas_log1UTF-8/mm7202.202.202.202!MMSC网关序号910010true102.102.102.102801001010002. 创建MM7消息发送接口：创建发送接口使用是MM7Sender类，其中已经封装了和MMSC连接通讯机制，使用时只要创建它一个带MM7Config参数实例即可。MM7Sender mm7Sender = new MM7Sender(mm7Config);4.2.2创建待发送消息创建待发送消息使用类均是由MM7Message继承得到。关键有MM7SubmitReq、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(服务代码); /设置服务代码，必备submitReq.setServiceCode(业务代码); /设置业务代码，必备submitReq.setSenderAddress(MM始发方地址);设置MM始发方地址（填写SP服务代码，或填写让用户回复SP长号码，长号码组成：SP服务代码业务代码操作码），必备submitReq.setChargedPartyID(“付费方手机号码”); /设置付费方手机号码，必备submitReq.setTo(接收方地址); /设置接收方MM地址submitReq.addTo(单个接收方地址); /增加单个接收方地址submitReq.setCc(抄送方地址); /设置抄送方MM地址submitReq.addCc(单个抄送方地址); /增加单个抄送方地址submitReq.setBcc(密送方地址); /设置密送方MM地址submitReq.addBcc(单个密送方地址); /增加单个密送方地址注：在设置或增加To，Cc和Bcc时，最少需要设置其中一个，这些地址可能存在多个地址或使用指示使用分发表别名。能够标识仅供参考地址。submitReq.setLinkedID(链接标识); /*设置链接标识，标识传送至VASP上一个有效消息对应关系；可选*/submitReq.setMessageClass(MM类别); /*设置MM类别（比如，广告、信息服务和计费），可选，具体有：Auto、Personal、Advertisement、Informational*/submitReq.setTimeStamp(提交MM日期和时间); /*提交MM时间和日期（时间戳）,格式如-02-09T10：21：07，可选*/submitReq.setExpiryDate(指定超时时间); /*设置MM指定超时时间（绝对或相对时间），可选*/submitReq.setEarliestDeliveryTime(最早理想时间); /*设置将MM传送给接收方最早理想时间(绝对或相对时间)，可选*/submitReq.setDeliveryReport(发送汇报请求); /*设置是否需要发送汇报请求（boolean值）,可选*/submitReq.setReadReply(需要读取汇报请求); /*设置经过请求传送一个读取汇报进行确定，可选*/submitReq.setReplyCharging(应答计费请求); /*设置应答计费请求（boolean值），可选*/submitReq.setReplyDeadline(提交应答最迟时间); /*设置在应答计费情况下，向接收方提交应答最迟时间（绝对或相对时间），可选*/submitReq.setReplyChargingSize(应答MM最大大小); /*设置在应答计费情况下，提供给接收方应答MM最大大小，可选*/submitReq.setPriority(消息优先级); /*消息优先级（关键性）（0=最低优先级，1=正常，2=紧急），byte类型值，可选*/submitReq.setSubject(多媒体消息标题); /*设置多媒体消息标题，可选*/submitReq.setAllowAdaptations(VASP是否许可修改内容); /*设置VASP是否许可修改内容（boolean值，默认为真），可选*/submitReq.setChargedParty(VASP所提交MM付费方); /*设置VASP所提交MM付费方，比如，发送方、接收方、发送方和接收方或两方均不付费，可选，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 cancelReq = 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 创建替换多媒体消息（MM7ReplaceReq）1.创建消息对象MM7ReplaceReq replaceReq = new MM7ReplaceReq();2. 设置消息属性replaceReq.setTransactionID(关联标识); /*设置MM7_replace.REQ/MM7_replace.RES正确标识，必备*/replaceReq.setVASPID(SP代码); /*设置SP代码，可选*/replaceReq.setVASID(服务代码); /*设置服务代码，可选*/replaceReq.setMessageID(被目前消息所替换消息标识符); /*被目前消息所替换消息标识符，必备*/replaceReq.setServiceCode(业务代码); /*设置业务代码，可选*/replaceReq.setTimeStamp(提交MM日期和时间); /*设置提交MM时间和日期（时间戳）,格式如-02-09T10：21：07，可选*/replaceReq.setEarliestDeliveryTime(最早理想时间); /*设置将MM传送给接收方最早理想时间(绝对或相对时间)，可选*/replaceReq.setReadReply(需要读取汇报请求); /*设置经过请求传送一个读取汇报进行确定（boolean值，true为需要，false为不需要），可选*/replaceReq.setAllowAdaptations(VASP是否许可修改内容); /*设置VASP是否许可修改内容（boolean值，默认为真），可选*/replaceReq.setContent(多媒体消息内容); /*设置多媒体消息内容，可选，注意当要设置时，一定要设置其ContentType。*/replaceReq.setDistributionIndicator(是否可重新分发); /*设置VASP是否可重新分发MM内容（boolean值，true为能够，false为不能够），可选*/4.2.3 创建消息内容体每个消息内容体就是一个MMContent实例，能够添加多个消息内容体，不过全部消息内容体大小之和不能超出MMSC许可大小（现在最大支持128K）。MMContent content = new MMContent();/*设置附件类型，若不包含SMIL格式文件，则设置类型为MMConstants.ContentType. MULTIPART_MIXED，若包含SMIL格式文件，则设置类型为MMConstants.ContentType. MULTIPART_RELATED*/content.setContentType(MMConstants.ContentType. MULTIPART_MIXED);/*添加类型为Gif附件一 */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);/*添加类型为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 发送多媒体消息调用MM7Sendersend方法发送多媒体消息，返回MM7RSRes类型消息。举例，发送MM7SubmitReq类型消息：MM7RSRes res = mm7Sender.send(submitReq); /其它消息和这类似4.2.5发送MM7SubmitReq消息到移动终端实例package com.cmcc.mm7.vasp.conf;import com.cmcc.mm7.vasp.message.*;import com.cmcc.mm7.vasp.service.MM7Sender;import mon.*;import java.io.*;public class VaspSendTest public static void main(String args) MM7Config mm7Config = new MM7Config(./config/mm7Config.xml);mm7Config. setConnConfigName(./config/ConnConfig.xml);MM7Sender mm7Sender = new MM7Sender(mm7Config);MM7SubmitReq submit = new MM7SubmitReq();submit.setTransactionID(11111111); submit.addTo(1391500); submit.setV