中国移动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.概述 5
2.概念 5
2.1企业代码 5
2.2服务代码 6
2.3业务代码 6
2.3.1上行业务业务代码规范 6
2.3.2下行业务业务代码规范 8
2.4操作指令码 10
2.5下行业务 11
2.6上行业务 11
2.7递送汇报 11
3.安装方法 11
3.1 MM7 API使用 11
3.2配置文件设置 11
4.开发方法 13
4.1 VASP接收传送请求（上行业务） 13
4.1.1 方法1：一般应用程序中使用方法 13
4.1.2 方法2：Web应用程序中使用方法 14
4.2发送多媒体消息过程（下行业务） 15
4.2.1准备 15
4.2.2创建待发送消息 16
4.2.2.1 创建提交增值业务多媒体消息（MM7SubmitReq） 16
4.2.2.2 创建取消多媒体消息（MM7CancelReq） 18
4.2.2.3 创建替换多媒体消息（MM7ReplaceReq） 18
4.2.3 创建消息内容体 19
4.2.4 发送多媒体消息 20
4.2.5发送MM7SubmitReq消息到移动终端实例 20
4.3 VASP接收传送消息和发送提交消息实例 21
4.4 VASP接收状态汇报（上行业务） 24
4.4.1方法1：一般应用程序中使用方法 24
4.4.2方法2：Web应用程序中使用方法 25
4.5 VASP接收读后回复汇报（上行业务） 26
4.5.1方法1：一般应用程序中使用方法 26
4.5.2方法2：Web应用程序中使用方法 27
4.6 发送取消消息（下行业务） 27
4.7 发送替换消息（下行业务） 28
5.开发过程中需用部分Status解释 29
5.1 相关VASP接收到消息后设置返回响应（Res）状态码及状态汇报解释 29
5.2 相关VASP收到DeliverReq中MMStatus解释 30
5.3 相关VASP收到ReadReplyReq中ReadStatus解释 30
6.获取MM7 API版本信息方法 30
7. MM7 API返回StatusCode说明 30

1.概述
该文档说明了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企业代码为8XY001－8XY999。（现在短信全网业务企业代码为9XY001－9XY500，WAP全网业务企业代码为9XY501－9XY999。）彩信地方业务SP企业代码由各地方移动企业根据业务许可次序依次分配制订，“XY”具体分配情况见相关表格。
2.2服务代码
服务代码是：用户使用彩信发送、上传等上行类业务时，需要输入接收方号码；或SP在依据用户点播请求在向用户发送、下载等下行类业务时，用户终端中显示发送方号码。服务代码数据需要在MMSC上进行配置，用于路由查找和状态汇报返回。服务代码以数字表示。
全国业务服务代码长度统一为4位，即“1000”－“9999”；当地业务服务代码长度统一为5位，即“01000”－“09999”。
以下号码或号段暂不分配：
13XX（XX＝00-99）、20XX（XX＝01－99）、168X（X＝0-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自行编排。
第2～3位：由彩信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：包月点播
第5～6位：由彩信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情况进行修改。

sp:MM7Config xmlns:vasp="">
1
zxme
zxme

c:\vas_log
1
100
120
200e>
UTF-8
1
/mm7
192.120.231.180
true
192.120.231.228
80
50
10000
5
7Config>

部分地方需要进行修改，下面一一说明：
1
表示VASP作为服务端接收消息时是否进行鉴权或进行什么样鉴权，0表示不鉴权，1表示进行基础鉴权，2表示进行摘要鉴权。
zxme
zxme
表示彩信中心对VASP进行鉴权时用户名和密码，同时也是VASP对接入彩信中心进行鉴权时用户名和密码，是双向，要VASP和MMSC双方进行约定。
c:\vas_log
表示日志存放路径，在Windows操作系统下和Linux下是不一样，要注意进行修改。
1
表示MMSC网关序号，需要从MMSC处得到。
/mm7
192.120.231.180
分别表示MMSC网关URL地址和IP（或主机名），也需要MMSC处得到。这里也能够填成ip:port。比如：192.120.231.180:8080,不填端口号使用默认端口号80。
192.120.231.228
80
表示当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)
{
//初始化VASP
MM7Config mm7Config = new MM7Config(“./config/mm7Config.xml”);
//设置ConnConfig.xml文件路径
mm7Config.setConnConfigName(“/config/ConnConfig.xml”); //必备
//结构MyReceiver
MyReciever 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或StatusCode
MM7DeliverRes 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 MM7RecieveServlet
{
public MM7VASPRes doDeliver(MM7DeliverReq request)
{
System.out.println(“收到手机”+request.getSender()
+“提交消息，标题为：”+request.getSubject());
System.out.println("MMSC标识符为："+request. GetMMSRelayServerID()) ;
//SP需要进行部分处理，比如构建MM7DeliverRes消息，设置ServiceCode或StatusCode
MM7DeliverRes 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为配置文件，其格式以下：

0
<设置用户名, 必需为被授权用户（4位）-->
1111

11111111

100000

c:\vas_log

1

UTF-8

/mm7

202.202.202.202
910010

true

102.102.102.102

80

100

10

1000

2. 创建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