浙江某地产OpenMAS移动代理服务器软件产品基础组件接口设计文档.docx

中国移动浙江公司

OpenMAS移动代理服务器软件产品
基础组件接口设计文档v1.0

2010.06

目录
1. 概述 2
1.1. 文档概述 2
1.2. 引用标准 2
2. OpenMAS业务简介 3
2.1. OpenMAS业务定义 3
2.2. OpenMAS业务特征 3
3. 接口说明 4
3.1. 短消息接口 4
3.1.1. 业务功能 4
3.1.2. 流程说明 4
3.1.3. 数据类型定义 6
3.1.4. 短信发送(SendSMS)接口 7
3.1.5. 短信接收(GetSms)接口 8
3.2. 彩信接口 10
3.2.1. 业务功能 10
3.2.2. 流程说明 10
3.2.3. 彩信表示规范 11
3.2.4. 数据类型定义 13
3.2.5. 彩信发送(SendMMS)接口 14
3.2.6. 彩信接收(GetReceivedMms)接口 16

1. 概述
1.1. 文档概述
本文档描述了OpenMAS组件与SI/EC平台交互的接口，包括短信、彩信、。
1.2. 引用标准
[1]中国移动通信集团公司 《省BOSS与业务管理平台（业务平台）接口规范（暂行）》（V1.1.0）
[2]中国移动通信集团公司 《全网行业应用业务规范》
[3]中国移动通信集团公司 《中国移动一级BOSS系统接口规范-全网行业应用-SMS业务单行本-IAGW-M部分2.0.0》
[4]中国移动通信集团公司《中国移动一级BOSS系统接口规范V1.4.5》
[5]中国移动通信集团公司《省行业网关开发全网行业应用总体技术要求－报批稿》
[6]中国移动通信集团公司《省BOSS与省行业网关接口规范1.1.2》

2. OpenMAS业务简介
2.1. OpenMAS业务定义
OpenMAS，即Open Mobile Agent Server，其将行业客户的各类应用与移动通信业务应用集成结合，实现SMS（Short Message Service）、USSD（Unstructured Supplementary Service Data）、MMS（Multimedia Messaging Service）、WAP（Wireless Application Protocol）、KJava（Kilo JAVA）等方面的移动数据应用，是沟通集团客户IT应用环境与移动网络之间的桥梁，为集团客户提供面向移动网络的统一的界面和接口，并可衍生出结合移动终端和其它移动应用的新的应用系统，丰富集团客户应用；对集成集团客户已有系统，OPENMAS系统可以简化开发流程、缩短开发周期，可以快速在已有应用系统中集成移动化功能，也可以根据OPENMAS系统开发针对性的移动应用。
2.2. OpenMAS业务特征
与OPENMAS服务器所具备的特殊地位对应，可以将OPENMAS服务器的应用分为三个层次。
ü 作为集团客户应用系统的统一移动接入手段：为集团客户应用系统提供包括短信、彩信、USSD、WAP、WEB、定位等在内的统一通信能力。功能的侧重点是提供通信能力的支持。在这个层次，MAS作为统一移动接入能力提供者，不参与业务的核心逻辑；
ü 实现集团客户应用的移动化：将集团客户IT系统的应用环境扩展到移动网络，从而实现移动化的集团客户应用。此时，移动化成为集团客户应用系统必备的功能需求，MAS服务器也成为集团客户应用系统不可或缺的部分。为了实现移动化的需求，集团客户应用系统不需要进行大的改动，在MAS服务器上需对集团客户应用系统的功能进行必要的扩充，MAS服务器成为集团客户应用系统的延伸。
ü 提供新业务：在MAS服务器上运行一个或多个应用模块。MAS服务器提供的应用相对独立，或是由于移动网络环境而衍生出的新的业务系统，这些应用也属于集团客户应用系统的范畴，并与其它集团客户应用系统共同使用MAS服务器所提供的接入和移动化支撑功能。
3. 接口说明
3.1. 短消息WebService接口
3.1.1. 业务功能
集团客户应用系统通过此接口实现短信的收发和状态查询。集团客户应用系统调用SendMessage接口发送短信，OpenMAS接收请求进行发送。在提交短信发送请求之后， OpenMAS根据集团客户预先注册的插件主动通知短信发送状态。
3.1.2. 短信发送接口
3.1.2.1. 流程说明

发送接口描述：
· 集团客户应用系统在OpenMAS基础组件上注册（并登记状态报告的接收URL），并在OpenMAS基础组件上生成账号；
· 集团客户应用系统调用OpenMAS基础组件的sendMessage接口，发起短信发送的操作；
· OpenMAS接收到短信，然后将短信发送到短信网关；
· OpenMAS接收短信网关的状态报告（结果回执）；
· OpenMAS根据注册的URL，调用基础组件的NotifySmsDeliveryReport方法（带上回执的结果参数）。
· 集团客户应用系统获取到具体的状态报告信息。
3.1.2.2. 调用方式
接口
接口定义
发起方
落地方
说明
发送短信
SendMessage
应用系统
OpenMAS

通知发送状态
NotifySmsDeliveryStatus
OpenMAS
应用系统
应用系统必须提前注册对应插件
3.1.2.3. 发送方法(SendMessage)
发起方：应用系统
落地方：OpenMas平台
string SendMessage(string ApplicationID, string Password, string[] DestinationAddresses,
string Message);
string SendMessage(string ApplicationID, string Password,
string[] DestinationAddresses, string Message string ExtendCode);
备注：消息内容Message为UTF-8编码。
请求参数定义
1、 ApplicationID：应用程序ID（类型：string）
2、 Password：应用程序发送短信密码，用来防止有人恶意模仿应用程序发送短信（类型：string）
3、 DestinationAddresses：短信接收方号码，可同时发多人（类型：string数组）
4、 ExtendCode：由该应用填写的应用内部扩展号码。（类型：string）
5、 Message：短信内容（类型：string）
返回值定义
6、 返回此次发送信息的唯一标识符，用于用户查询发送状态。(类型：string)
3.1.2.4. 状态报告方法 (NotifySmsDeliveryReport)
发起方：OpenMas平台
落地方：应用系统
限制条件：应用系统必须注册指定插件
void NotifySmsDeliveryReport(DeliveryReport deliveryReport);
请求参数定义
deliveryReport：短信发送状态，与发送请求数组一一对应（类型：DeliveryReport）
1、 DeliveryStatus：发送状态（DeliveryStatus），枚举类型
0
Delivered
发送成功。
1
WaitingForDelivery
等待发送。
2
WaitingForDeliveryStatus
已发送,等待状态报告。
3
DeliveryFailed
发送失败。
2、 ReceivedAddress：接收方地址（string）
3、 StatusCode：状态码，如果发送失败可确定错误原因（string）
4、 SendAddress：发送地址
5、 MessageId：发送标识
返回值定义
3、无返回值
3.1.3. 短信接收接口
3.1.3.1. 流程说明
·
· 接收短信流程说明：
· 由应用系统提前在OpenMAS基础组件注册插件，并登记用于接收短信的URL；
· 然后OpenMAS基础组件从短信网关接收短信信息；
· OpenMAS组件根据插件注册时登记的URL信息，调用URL对应的NotifySMS方法；
· 集团客户应用系统收到OpenMAS的调用，获取上行短信唯一标识的MessageID；
· 集团客户应用系统调用OpenMAS组件方法（GetMessage），获取上行短信的详细内容。
3.1.3.2. 调用方式
接口
接口定义
发起方
落地方
说明
上行短信通知
NotifySms
OpenMAS
应用系统
应用系统必须提前注册对应插件
接收短信
GetMessage
应用系统
OpenMAS

3.1.3.3. 上行短信通知方法(NotifySms)
发起方：OpenMas平台
落地方：应用系统
void NotifySms(string MessageID);
请求参数定义
1、MessageID：上行短信唯一标识，用来获取信息（类型：string）
返回值定义
2、无返回值
3.1.3.4. 接收短信方法(GetMessage)
发起方：应用系统
落地方：OpenMas平台
SmsMessage GetMessage(string MessageID);
请求参数定义
1、 MessageID：上行短信唯一标识（类型：string）
返回值定义
返回指定应用程序的上行短信。（类型：SmsMessage数组）,类型说明如下：
1、 Message：短信正文（string）
2、 ReceivedAddress：接收方地址（string）
3、 SendAddress：发送方地址（string）
3.2. 短信数据库接口
集团客户应用系统与OpenMAS基础组件的数据库可接口，只支持SQL SERVER 2005，同时数据库部署在OpenMAS基础组件侧。
3.2.1. 业务功能
集团客户应用系统通过此接口实现短信的收发和状态查询。集团客户应用系统提交待发送短信到数据库，OpenMAS从数据库中获取待发短信并进行发送。在提交短信发送请求之后， OpenMAS回写状态报告到短信发送结果表。
3.2.2. 短信发送接口
3.2.2.1. 业务流程

流程说明:
· 应用系统提交待发送短信到中间数据库；
· OpenMAS基础组件定期从中间数据库中获取待发送短信；
· OpenMAS基础组件发送短信；
· OpenMAS基础组件获取短信的状态报告；
· OpenMAS基础组件提交状态报告到中间数据库；
· 应用系统定期从数据库获取状态报告。
3.2.2.2. 表结构说明
短信待发送表：
COM_SmsSent_+扩展号，如：COM_SmsSent_1
字段名
数据类型
长度
必填
描述
备注
ID
Int
-
是
主键
自动生成
MessageID
String
50
是
短信编号
必须为唯一值，建议使用GUID
ApplicationID
String
40
是
应用程序编号
OpenMAS基础组件上注册的账号
MessageContent
String
1000
否
发送的短信内容

SendAddress
String
40
是
基础接入号

ExtendCode
String
40
否
接入号扩展码

DestinationAddress
String
40
是
短信接收手机

SendTime
DateTime
-
否
短信创建时间
默认取当前时间
注：短信待发送表中的数据被发送后，OpenMAS基础组件将自动删除。

短信状态报告表：
COM_SmsReport_+扩展码，如：COM_SmsReport_1
字段名
数据类型
长度
必填
描述
备注
ID
Int
-
是
主键
标识字段，自动递增
ApplicationID
String
40
是
应用程序编号

MessageID
String
50
是
短信编号
必须为唯一值
SendAddress
String
40
否
基础接入号

ExtendCode
String
40
否
接入号扩展码

DestinationAddress
String
40
是
短信接收手机

SendStatus
Int
-
否
短信提交结果
0：成功，其他值为失败
GatawayStatus
String
20
否
短信发送结果
网关返回错误(DELIVRD表示成功)
CreateTime
DateTime
-
是
状态报告返回时间

注：应用程序务必删除已读取的状态报告，以免表数据越来越大影响性能。
另外，如果OpenMAS从短信网关未获取到状态报告，则短信状态报告表中将没有数据。
3.2.3. 短信接收接口
3.2.3.1. 业务流程

流程说明:
· OpenMAS基础组件从行业网关获取上行短信；
· OpenMAS基础组件将上行短信提交到中间数据库；
· 应用系统定期从中间数据库获取上行短信。
3.2.3.2. 表结构说明
短信上行表
COM_SmsIn_+扩展码，如：COM_SmsIn_1
字段名
数据类型
长度
必填
描述
备注
ID
Int
-
是
主键
标识字段，自动递增
MessageID
String
50
是
短信编号
必须为唯一值
ApplicationID
String
40
是
应用程序编号

MessageContent
String
1000
否
上行的短信内容

SendAddress
String
40
是
上行手机号码

DestinationAddress
String
40
是
基础接入号

ExtendCode
String
40
否
接入号扩展码

CreateTime
DateTime
-
否
上行时间

注：应用程序务必删除已读取的上行短信，以免表数据越来越大影响性能。
3.3. 彩信WebService接口
3.3.1. 业务功能
集团客户应用系统通过此接口实现彩信的收发和状态查询。集团客户应用系统调用SendMessage接口发送彩信，OpenMAS接收请求进行发送。在提交彩信发送请求之后，集团客户应用系统可以主动请求查询彩信发送状态，或者由OpenMAS根据集团客户预先注册的插件主动通知彩信发送状态。
3.3.2. 彩信表示规范
彩信可包含文字、图片和铃声，所以采用XML格式来表示一条彩信。规范如下：
元素
属性
说明
<masmms>
-
根元素
<content>
contentType
contentid
contentLocation
charset
消息体,出现多次,并且在content中没有出现smil文件,则按顺序显示,如果有smil文件,则按照smil控制显示
属性包括:
ContentType:mime内容类型
Contentid:smil正文中的内容id,如果没有smil,则可自行定义.
ContentLocation:媒体对象的文件名
Charset: 编码格式,可选

Content-Type支持格式：
TEXT : text/plain
XML: text/xml
SMIL: application/smil
AMR: audio/amr
MIDI: audio/midi
GIF :image/gif
JPEG: image/jpeg
WBMP: image/vnd.wap.wbmp
PNG: image/png
Xml示例：
<?xml version="1.0" encoding="utf-8"?>
<masmms>
<content
contentType="image/gif"
charset="" contentId="1.gif"
contentLocation="1.gif">
R0lGODlhgACAAPf/…….. hDjEijV1ELSAAOw==
</content>
<content
contentType="text/plain"
charset=""
contentId="1.txt"
contentLocation="1.txt">
uafPsreissY=
</content>
<content
contentType="application/smil"
charset=""
contentId="2.smil"
contentLocation="2.smil">
PHNtaWw+PGhlYWQ+PGxhe…………………eT48L3NtaWw+
</content>
</masmms>
说明：如果Content中没有SMILl类型文件，文本中文字、图片和音频的显示顺序按照Content在xml中的先后顺序，如果有，则按照SMIL来控制显示。

3.3.3. 彩信发送接口
3.3.3.1. 流程说明
·
· 发送流程说明：
· 发集团客户应用系统在OpenMAS基础组件上注册（并登记状态报告的接收URL），并在OpenMAS基础组件上生成账号；
· 集团客户应用系统调用OpenMAS基础组件的sendMessage接口，发起彩信发送的操作；
· OpenMAS接收到彩信，然后将彩信发送到彩信网关；
· OpenMAS接收彩信网关的状态报告（结果回执）；
· OpenMAS根据注册的URL，调用基础组件的NotifyMmsDeliveryReport方法（带上回执的结果参数）。
· 集团客户应用系统获取到具体的状态报告信息。
3.3.3.2. 调用方式
接口
接口定义
发起方
落地方
说明
发送彩信
SendMessage
应用系统
OpenMAS

通知发送状态
NotifyMmsDeliveryReport
OpenMAS
应用系统
应用系统必须提前注册对应插件

3.3.3.3. 发送方法(SendMessage)
发起方：应用系统
落地方：OpenMas平台
string SendMessage(string ApplicationID, string Password,string[] DestinationAddresses,
string Subject, string Content);
string SendMessage(string ApplicationID, string Password,string[] DestinationAddresses,
string Subject, string Content, string ExtendCode);
string SendMessage(string ApplicationID, string Password,string[] DestinationAddresses,
string Subject, string Content, string ExtendCode, Priority Priority);
请求参数定义
1、 ApplicationID：应用程序ID（string）
2、 Password：应用程序发送彩信密码，用来防止有人恶意发送彩信（类型：string）
3、 DestinationAddresses：彩信接收方号码，可同时发多人（string数组）
4、 ExtendCode：由该应用填写的应用内部扩展号码。
5、 Subject：主题（string）
6、 Priority：优先级（Priority）
值
名称
描述
0
Default
缺省消息优先级
1
Low
低的消息优先级
2
Normal
正常的消息优先级
3
High
高的消息优先级
7、 Content：彩信内容--彩信的xml表示参见3.2.3彩信表示规范。（string）
返回值定义
7、返回此次发送信息的唯一标识符，用于用户查询发送状态。类型：string
3.3.3.4. 彩信发送状态通知接口（NotifyDeliveryStatus）
发起方：OpenMas平台
落地方：应用系统
限制条件：应用系统必须注册指定插件
void NotifyMmsDeliveryReport(DeliveryReport DeliveryReport);
请求参数定义
1、 deliveryReport：彩信发送状态（见彩信发送状态表）
DeliveryStatus：发送状态（DeliveryStatus），枚举类型
0
Delivered
发送成功。
1
WaitingForDelivery
等待发送。
2
WaitingForDeliveryStatus
已发送,等待状态报告。
3
DeliveryFailed
发送失败。
ReceivedAddress：接收方地址（string）
StatusCode：状态码，如果发送失败可确定错误原因（string）
SendAddress：发送地址
MessageId：发送标识
返回值定义
3、无返回值
3.3.4. 彩信接收接口
3.3.4.1. 流程说明
·
· 接收短信流程说明：
· 由应用系统提前在OpenMAS基础组件注册插件，并登记用于接收彩信的URL；
· 然后OpenMAS基础组件从彩信网关接收短信信息；
· OpenMAS组件根据插件注册时登记的URL信息，调用URL对应的NotifyMMS方法；
· 集团客户应用系统收到OpenMAS的调用，获取上行彩信唯一标识的MessageID；
· 集团客户应用系统调用OpenMAS组件方法（GetMessage），获取上行彩信的详细内容。
3.3.4.2. 调用方式
接口
接口定义
发起方
落地方
说明
上行彩信通知
NotifyMms
OpenMAS
应用系统
应用系统必须提前注册对应插件
接收彩信
GetMessage
应用系统
OpenMAS

3.3.4.3. 上行彩信通知方法(NotifyMms)
发起方：OpenMas平台
落地方：应用系统
void NotifyMms (string MessageID);
请求参数定义
1、MessageID：上行短信唯一表示符，用来获取上行短信（类型：string）
返回值定义
无返回值
3.3.4.4. 接收彩信方法(GetMessage)
发起方：应用系统
落地方：OpenMas平台
MmsMessage GetMessage(string MessageID);
MmsMessage[] GetMessage(string ApplicationID, string Password);
请求参数定义
1、 ApplicationID：应用程序ID（类型：string）
2、 MessageID ：短信上行唯一标识（类型：string）
3、 Password：应用程序发送彩信密码，用来防止有人恶意获取上行彩信（类型：string）
返回值定义
返回指定应用程序的上行彩信。（类型：MmsMessage数组）, MmsMessage说明:
1、Subject：主题（string）
2、ReceivedAddress：接收方地址（string）
3、SendAddress：发送方地址（string）
4、Content：与消息一起接收到的数据—为彩信的xml表示参见4.2.3彩信。（string）
5、Priority：优先级。(Priority)
6、ReceivedTime：彩信接收时间。（DateTime）