移动代理服务器MAS彩信API1.0开发手册
移动代理服务器MAS 彩信接口开发手册
V1.0
深圳市嘉讯软件有限公司
二○○七年五月
目录
1 引言 (1)
1.1 编写目的 (1)
1.2 背景说明 (1)
1.3 术语定义 (1)
2 概述 (3)
2.1 接口功能 (3)
2.2 接口组成 (4)
2.3 彩信收发机制 (4)
2.3.1 MT彩信与其回执、回复的对应 (4)
2.3.2 MO彩信的分流 (5)
3 接口介绍 (6)
3.1 接口管理模块 (6)
3.1.1 主页面 (6)
3.1.2 新建页面 (7)
3.1.3 编辑页面 (8)
3.1.4 队列管理页面 (9)
3.2 数据库接口 (9)
3.2.1 发送队列表 (10)
3.2.2 接收队列表 (11)
3.2.3 回执队列表 (11)
3.3 Java API (12)
3.3.1 类APIClient (13)
3.3.2 类MOItem (16)
3.3.3 类RPTItem (17)
4 使用指导 (18)
4.1 开发步骤 (18)
4.2 调试方法 (18)
4.3 运行设置与监控 (19)
5 附录 (21)
5.1 附录一：回执编码列表 (21)
1引言
1.1 编写目的
移动代理服务器MAS提供了强大的彩信接入机制。本手册用于指导客户利用移动代理服务器MAS提供的彩信接口进行其他需要彩信功能的新系统开发或原有系统的彩信功能扩展。
本手册的阅读对象为需要采用移动代理服务器MAS的彩信接口完成客户开发的设计人员与编码人员。
1.2 背景说明
本手册适用于产品“移动代理服务器MAS”。
1.3 术语定义
移动代理服务器
MAS：全称为“移动代理服务器MAS”，属深圳嘉讯公司开发的一套产品，简称MAS。
MT彩信：通过彩信接口发往手机终端的彩信，也指从MAS的某一功能直接发往手机终端的彩信。
MO彩信：从手机终端发往MAS的彩信，这些彩信根据特定的规则有的直接转交到MAS的某一具体功能，有的转交到某一
彩信接口的接收队列。
彩信回执：对于MT彩信，手机终端收到后会返回彩信回执给MAS。
通过发送队列发送出去的所有MT彩信随后都会在回执
队列中收到对应的回执。回执包含MT彩信是否成功提交
到特定手机终端的信息。
彩信回复：对于MT彩信，手机终端收到后可以使用彩信回复功能回复一条彩信，对于通过发送队列发送的MT彩信，其回复
彩信随后都可以从接收队列中获得
接口编码：某套彩信接口的唯一标识，在创建接口时设置，随后不允许修改。
彩信子号：每套彩信接口都拥有一个特定数字，这个特定数字由彩信收发机制所使用，其具体作用请参照章节2.3.1
2概述
移动代理服务器MAS不仅为各种类型的集团客户直接提供了丰富的彩信业务应用功能，而且提供强大的彩信接入机制。
此机制允许客户再接入任何其他系统以开发此系统的彩信应用功能，从而使拥有移动代理服务器MAS的客户相当于拥有了一个属于自己的“袖珍型彩信行业网关”
2.1 接口功能
移动代理服务器MAS的彩信接入机制所提供的功能是很强大的：
支持MT彩信的发送、MO彩信的接收。
所发送的MT彩信文件可以达到100K(视手机和移动网络限制而不同)。
支持MT彩信的回执确认。
支持MT彩信的回复会话。
支持通过分配给接口的彩信子号来接收MO彩信。
所有接口的收发彩信都有话单记录
可以出丰富的接口彩信话单报表。
提供接入的多种语言开发包。
提供不受任何具体开发语言约束的数据库接入。
提供开发用的调试环境。
提供彩信收发的监控功能。
2.2 接口组成
移动代理服务器MAS的彩信接口包括如下部分：
组成部分功能说明
用于彩信接口的创建、设置、监控；用于开发时的接口管理模块
辅助调试。
各种语言包用于各种语言的API调用。
用于其他系统直接通过访问数据库来进行彩信的收数据库接口
发。
2.3 彩信收发机制
2.3.1MT彩信与其回执、回复的对应
外部系统利用移动代理服务器MAS的彩信接口进行MT彩信的发送时，可以为每条MT彩信提供指定一个彩信编号，那么随后这条彩信的回执与回复就会带上同样的彩信编号。这样外部系统通过发送MT彩信时所用的彩信编号就可以辨识出随后针对这条彩信的回执、回复。
彩信编号可以是1到99999999之间的任何一个整数。如果外部系统需要随后能辨识出每条MT彩信的回执、回复的功能，那么外部系统必须确保在一定的时间段内所发送的每条MT彩信都有唯一的彩信编号。
对于某些MT彩信，外部系统可能不需要辨识其回执、回复。对于这
类彩信，在发送时都可以指定其彩信编号为0。
2.3.2MO彩信的分流
移动代理服务器MAS可以支持几十套彩信接口，那么移动代理服务器MAS怎样确保手机用户主动发起的MO彩信能准确的达到某套彩信接口呢？这有如下两种方法：
彩信子号分流。在创建1套彩信接口时，MAS会要求用户为此接口分配一个彩信子号，随后MO彩信就可以通过彩信子号的辨识而到达此接口。举例如下：
假设发往MAS所用的目的号码为076114044，而某一套彩信接口所分配的彩信子号为5，则手机用户若要发送彩信到此接口，只要发往目的号码07611404405则可。
3接口介绍
3.1 接口管理模块
登录MAS后，只要用户权限允许，用户可以在系统管理菜单下访问“接口管理”模块。利用此功能模块，可以对接口进行图形化创建、维护、设置、监控、或进行客户开发的调试辅助。
如果用户无法访问“系统管理—〉接口管理－〉彩信接口”，应联系MAS的系统管理员授权。
3.1.1主页面
彩信接口的主页面如下：
主页面主要包括4个按钮与一个列表。所创建的每个接口在列表上有1条记录，通过此列表可以查阅每个接口的基本信息。
列表上方各按钮功能如下：
新建：用于创建一套新的彩信接口，
编辑：用于编辑已存在彩信接口的某些属性
删除：删除一套已存在的彩信接口。
队列管理：可以查阅正在发送队列、接收队列、回执队列中排队的彩信记录，同时用于清除一些非法的彩信记录。配合暂停功能（调试状态），
可用于外系统彩信接入开发中的调试。
3.1.2新建页面
通过主页面的“新建”按钮创建接口时，就会弹出如下新建页面：
通过如上页面就可以创建一个接口。如上页面的各输入元素如下：
接口编码：接口的编码标识符，任意英文字母及数字组成，不能重复。 接口名称：接口的描述性名称，便于开发用户记忆方便。
接口类型：包括DB类型、API类型，前者提供DB接口，后者提供开发语言的开发包。DB接口：表示开发用户可以通过任何途径（JDBC,ODBC，其它API等）连接上MAS的数据库，即可进行彩信的收发。
彩信子码：
登录用户：对应DB接口建立数据库连接的用户名，或API接口init函数的loginName参数。
登录密码：对应DB接口建立数据库连接的用户密码，或API接口init 函数的loginPWD参数。
接口状态：包括运行状态、调试状态两种类型。当在接口连接开发中时，应设置接口为调试状态，这时候队列管理页面可作为调试时的模拟网关，此时彩信接口是还没有接入真实的彩信网关的。当开发完投入运行时，应设置接口为运行状态，这样彩信接口就接入了真实的彩信网关。
3.1.3编辑页面
通过主页面的“编辑”按钮编辑某接口时，就会弹出如下编辑页面：
通过如上页面就可以修改一个接口。如上页面的各输入元素如下：
接口名称：修改接口的描述性名称。
彩信子码：修改彩信子码。
登录用户：登录名不能修改。
登录密码：修改登录密码。
接口状态：切换接口的状态。当在接口连接开发中时，应设置接口为调试状态，这时候队列管理页面可作为调试时的模拟网关，此时彩信接口是还没有接入真实的彩信网关的。当开发完投入运行时，应设置接口为运行状态，这样彩信接口就接入了真实的彩信网关。
3.1.4队列管理页面
通过主页面的“队列管理”按钮，就可以进入如下队列管理页面：
发送队列：利用此页面可查看或清除尚在发送队列表的某些记录。
接收队列：利用此页面可查看或清除尚在接收队列表的某些记录。
回执队列：利用此页面可查看或清除尚在回执队列表的某些记录。
在调试状态时，如上Tab子页都提供了“删除”“添加”按钮，这样利用其添加、删除记录的功能，就可以模拟彩信网关接收上行的MT彩信，并下行MO彩信、MT彩信回执。
在运行状态时，如上Tab子页不会出现“删除”“添加”按钮。用户仅能通过队列管理页面查看当前3个队列的排队情况。
3.2 数据库接口
DB接口存在于一个库名为mas的MySQL库内，MySQL数据库的版本为4.0.20，用户可通过JDBC，ODBC，DAO等任何MySQL可支持的方式访问。建立数据库连接时，所用的IP地址应为MAS的IP地址，登录名、登录密码为接口创建时的接口登录名、接口登录密码。
DB接口由如下3个表组成，API MT队列表用于发送彩信，API MO
队列表用于接收彩信，API RPT队列表用于接收回执。
3.2.1发送队列表
此表用于发送彩信，表名为api_mms_mt_
字段别名 字段名 数据类型 是否空值说明
序列号 auto_sn unsigned int NOT NULL主键，为自增量
彩信SRCID src_id varchar(21) NOT NULL
发送方号码，即目的手机上显示的号码，用于对应
回复。如果不需要回复，则此值写入空串。
彩信ID smil_id text NOT NULL
唯一ID，用于确认唯一手机号码。
如果need_rpt的值为1，此值也必须填入，如果
neet_rpt的值0，则此值可以写入空串。
手机号码集 mobiles text NOT NULL
用英文逗号或中文逗号隔开的手机号码集，手机号
码最大不能超过1000个。
彩信标题 subject varchar(100) NOT NULL
彩信标题，最大长度为100字节。
彩信文件 files text NOT NULL
彩信内容所组成的文件，各个文件名之间以逗号作
为分隔符。文件名为相对路径，相对FTP的根目录
下/mms_
是否需要回
执 need_rpt tinyint(1) NOT NULL
需要回执填1，否则填0，default 0
提交时间 submit_time datetime NOT NULL
提交发送的时间，字符串的格式为：yyyy-MM-dd
HH:mm:ss
外部系统可对此表进行SELECT、INSERT操作。外部系统通过插入1
条记录来进行一次MT彩信发送。
3.2.2接收队列表
此表用于接收彩信，表名为api_mms_mo_
字段别名 字段名 数据类型 是否空值说明
序列号 auto_sn unsigned int NOT NULL主键，为自增量
彩信SRCID src_id varchar(21) NOT NULL用户发送彩信的目的地址。
手机号码 mobile text NOT NULL
用户提交的手机号码
彩信标题 subject varchar(100)NOT NULL
彩信标题，最大长度为100字节。
彩信文件 files text NOT NULL
彩信内容所组成的文件，各个文件名之间以逗号作
为分隔符。文件名为相对路径，相对FTP的根目录
下/mms_
接收时间 receive_time datetime NOT NULL
收到此MO彩信的的时间，字符串的格式为：
yyyy-MM-dd HH:mm:ss
外部系统可对此表进行SELECT、DELETE操作。外部系统通过SELECT操作来取出所有已收到的MO彩信，取出后的记录通过DELETE操作来删除掉。
3.2.3回执队列表
此表用于接收回执，表名为api_mms_rpt_
字段别名 字段名 数据类型 是否空值说明 序列号 auto_sn unsigned int NOT NULL主键，为自增量
彩信ID smil_id text NOT NULL
唯一ID，用于确认唯一手机号码。
当发送彩信need_rpt的值为1 ，才有相应的此条记
录，对应发送时的smil_id
手机号码 mobile text NOT NULL
手机号码
回执号 rpt_result int NOT NULL
回执返回的结果代码
回执描述 rpt_detail varchar(100)NULL
回执的详细描述
回执时间 rpt_time datetime NOT NULL彩信网关返回回执的时间
外部系统可对此表进行SELECT、DELETE操作。外部系统通过SELECT操作来取出所有已返回的彩信回执，取出后的记录通过DELETE操作来删除掉。
3.3 Java API
JA V A开发包的文件名为MmsApi.jar，是基于JDK1.4.2开发的，可在发布光盘中找到。如下类图，开发包包括APIClient、MOItem、RPTItem等3个类，3个类的包路径都为：com.jasson.mas.mmsapi。
3.3.1类APIClient
彩信发送、彩信接收、回执接收类。
属性
public final static int MMSAPI_SUCC = 0; // 操作成功
public final static int MMSAPI_CONN_ERR = -1; // 连接数据库出错
public final static int MMSAPI_CONN_CLOSE_ERR = -2; // 数据库关闭失败public final static int MMSAPI_INS_ERR = -3; // 数据库插入错误
public final static int MMSAPI_DEL_ERR = -4; // 数据库删除错误
public final static int MMSAPI_QUERY_ERR = -5; // 数据库查询错误
public final static int MMSAPI_DATA_ERR = -6; // 参数错误
public final static int MMSAPI_API_ERR = -7; // API标识非法
public final static int MMSAPI_DATA_TOOLONG = -8; // 消息内容太长public final static int MMSAPI_INIT_ERR = -9; // 没有初始化或初始化失败public final static int MMSAPI_FTP_CONN_ERR = -10;//FTP连接错误
public final static int MMSAPI_FTP_CLOSE_ERR = -11;//FTP关闭错误public final static int MMSAPI_FTP_LOGIN_ERR = -12;//FTP登陆错误public final static int MMSAPI_FTP_DIR_ERR = -13;//FTP目录错误
public final static int MMSAPI_FTP_GET_ERR = -14;//FTP下载错误
public final static int MMSAPI_FTP_PUT_ERR = -15;//FTP上传错误
public final static int MMSAPI_FILE_NOT_FOUND = -16;//文件不存在
方法
3.3.1.1 init(masIP , loginName, loginPwd, dbName, apiCode)
原型：public int init (String masIP , String loginName, String loginPwd, String dbName, String apiCode)
参数：
MAS的IP地址
masIP
接口登录名
loginName
接口登录密码
loginPwd
接口数据库名称，默认情况下为“mas”
dbName
接口编码
apiCode
返回值： Int. 0=成功，其它返回错误，详见附录。
3.3.1.2 sendMms() 发送彩信
原型：public int sendMms(String srcID, string smilID, String mobiles, String subject , String files,boolean needRpt)
参数：
srcID 源地址，手机上显示的号码，用于对应回复。如果不需要回复，
则此值写入空串
smilID 唯一ID，用于确认唯一手机号码。
如果need_rpt的值为1，此值也必须填入，如果neet_rpt的值0，
则此值可以写入空串。
mobiles 彩信发送的目的手机号码集，多个手机号码之间用分号分隔，
手机号码最大不能超过1000个
subject 彩信标题，最大长度为100字节
files 彩信的相关文件名系列，多个文件之间用分号分隔。文件名为
文件的绝对路径。
needRpt 是否需要回执，true：需要，否则不需要。
返回值：Int. 0=成功，其它返回错误，详见附录。
3.3.1.3 sendMms() 群发彩信
原型：public int sendMms(String srcID, string smilID, String[] mobileArr, String subject , String files,boolean needRpt)
参数：
srcID 源地址，手机上显示的号码，用于对应回复。如果不需要回复，
则此值写入空串
smilID 唯一ID，用于确认唯一手机号码。如果neetRpt的值false，则
此值可以写入空串。
mobileArr 彩信发送的目的手机号码数组，手机号码个数不能超过1000
个
subject 彩信标题，最大长度为100字节
files 彩信的相关文件名系列，多个文件之间用分号分隔。文件名为
文件的绝对路径。
needRpt 是否需要回执，true：需要，否则不需要。
返回值：Int. 0=成功，其它返回错误，详见附录。
3.3.1.4 receiveMms()
接收所有已收到的MO彩信。
原型：public MOItem[] receiveMms ()
参数：
无。
返回值：MOItem[]。所接收的彩信的数组。null表示接收失败，
数组长度为0表示无彩信。
3.3.1.5 receiveRPT()
接收所有已返回的彩信回执。如果彩信接口不支持回执，就返回null。
原型：public RPTItem[] receiveRpt()
参数：
无。
返回值：RPTItem[]。所接收的回执的数组。null表示接收失败，
数组长度为0表示无回执。
3.3.1.6 release()
本方法用于断开到MAS的连接，同时释放相关资源。
原型：public void release()
参数：
无。
返回值：无。
3.3.2类MOItem
保存一条MO彩信的数据类。
属性
属性属性说明Public String mobile 发送彩信的手机号码
Public long srcId MO彩信的SRCID
Public String subject 彩信标题
Public String files 彩信文件
Public String receiveTime MO接收时间
方法
无。
3.3.3类RPTItem
保存一条彩信回执的数据类。
属性
属性属性说明Public String mobile 发送彩信的手机号码
Public long smilId MT彩信的彩信ID
Public int rptResult 回执编码
Public String rptDetail 回执描述
Public String rptTime 回执时间
方法
无。
4使用指导
4.1 开发步骤
对于使用MAS的用户，利用MAS彩信接口进行其它软件的开发与使用，大体分为如下步骤：
接口创建：登录MAS的接口管理模块，进入彩信接口页面，根据
需要创建一个合适的彩信接口
开发：根据将使用的开发语言选择对应语言的接口语言包进行
开发。如果没有对应的语言包，就使用DB接口。如果
使用DB接口，则在第1步创建彩信接口时要创建DB
类型的接口。
调试与测试：编码过程中或编码完成后，利用接口管理模块的队列管
理作为一个彩信模拟终端进行调试与测试。
运行：在开发完成后，把对应接口设置为运行态，就可以上线
运行所开发的软件。
4.2 调试方法
当利用MAS提供的彩信接口进行软件开发时，直接使用手机进行彩信
- 各大热门安卓系统手机移动及联通sim卡上网及彩信设置参数详解
- 中国移动指令
- 中国移动手机网络设置
- 中国移动全网集团短彩信业务管理办法(doc 26页)
- 中国移动彩信手机报配彩信制作及图片格式说明200906
- 彩信以及彩信收发的基本原理
- 中国移动MMS规范
- 移动数据-APN设置
- Android手机中国移动彩信APN设置教程
- 中国移动彩信设置
- 中国移动彩信业务介绍
- 中国移动全网集团短彩信业务管理办法
- 各大运营商 网络接入点设置
- 中国移动 中国联通 手机上网设置
- 中国移动网络部彩信业务介绍.
- 中国移动接入点设置教程(Android手机版)
- 各大运营商 网络接入点设置
- 中国移动短彩信业务知识梳理
- 中国移动积分换话费、换短信、换彩信、换流量包的办法
- 中国移动彩信设置