SP开发ISAG业务手册-电信版

SP 开发 ISAG 业务手册 （电信版） CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 2 页 共 69 页 目 录 一、一、ISAG 平台介绍平台介绍.6 二、接口说明二、接口说明.7 2.1SP 接口概述 .7 2.2SP 接口简介 .7 2.2.1短信接口.7 2.2.2彩信接口.8 2.2.3网页推送接口.8 三、三、SP 接口中变量的说明接口中变量的说明.8 3.1 公共数据类型.8 3.1.1 SimpleReference.8 3.1.2 ChargingInformation .9 3.1.3 ServiceError | ServiceException | PolicyException.9 3.2 上行 SOAPHEADER数据说明.9 3.3 下行 SOAPHEADER数据说明.9 四、四、SP 业务开发业务开发 DEMO.10 4.1DOTNET（.NET）版本.10 4.1.1短信发送.10 模块介绍 .10 界面 .11 设计过程 .11 .1 获取 WSDL 文档.11 .2 修改 WSDL 文档.12 .3 添加 WEB 引用.12 .4 通过引用名实现数据类型的使用和方法调用.12 .5 异常的捕捉.13 .6 具体实现.14 4.1.2短信接收.14 模块介绍 .14 消息接收 .14 消息的显示 .15 .1 消息显示界面.15 .2 具体实现.16 4.1.3彩信发送.16 模块介绍 .16 界面 .16 设计过程 .17 .1 获取 WSDL 文档.17 .2 修改 WSDL 文档.17 .3 添加 WEB 引用.17 .4 使用引用.18 .5 异常的捕捉.18 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 3 页 共 69 页 .6 具体实现.18 SOAP 附件实现.18 4.1.4彩信接收.19 主要代码 .20 具体实现 .21 4.1.5网页推送（WAP PUSH）.21 模块介绍 .21 界面 .21 设计过程 .22 .1 获取 WSDL 文档.22 .2 修改 WSDL 文档.22 .3 添加 WEB 引用.22 .4 使用引用.23 .5 异常的捕捉.23 .6 具体实现.23 4.2GSOAP false,非群发; 默认为 false) 表 3.5 下行 SOAPHeader 注：ISAG 对 SP 的鉴权信息有:：spId、spPassword（注意它的原文信息，顺序和内容） 。 SP 密钥：为 spPassword 值原文的一部分（或 spPassword= SP 密钥，视鉴权方式而定） ，此值需 要预先获得才能给 spPassword 正确赋值。 spId、productId、SP 密钥数据在测试阶段会给出测试数据，正式运行时数据从 ISMP 同步获得。 四、SP 业务开发 DEMO 注：图中数据为 DEMO 开发中使用的临时数据不代表正式业务开发中的数据，数据请向有关方咨询！ 4.1DOTNET（.NET）版本 4.1.1 短信发送 模块介绍 短信发送： 接口：SendSMS CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 11 页 共 69 页 sendSms：应用发送短消息； 短信发送是 SP 发文本消息给 ISAG，ISAG 返回一个标识。 界面 图 4.1 短信发送界面 图 4.1 中“地址”项为接收消息的地址， “消息内容”为文本短消息，结果显示为 ISAG 返回的信息。 右边为可选项信息。鉴权信息为 spId+密钥+temestamp 的 MD5 值，即 spPassword，它的值与 spId+SP 密钥+temestamp 相关。可选信息的项是可以手工修改的。 设计过程 .1 获取 WSDL 文档 短信发送用到的 WSDL 文件有： 图 4.2 sendSms 需要的描述文件 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 12 页 共 69 页 .2 修改 WSDL 文档 详见 7.6.1 节； .3 添加 WEB 引用 首先，在 Microsoft Visual Studio 2005 新建窗体项目； 其次，添加对 ISAG WEB SERVICE 的 WEB 引用，这里可以直接引用 WSDL 文档。.NET 应用 WSDL 文档是创建 WEB SERVICE 的代理类，让客户端使用 WEB SERVICE 的 SOAPHeader、复杂数 据类型、方法等创建他们的实例，给实例的属性赋值，以达到产生 WEB SERVICE 需要的数据格式。 图 4.3 添加 WEB 引用 图 4.4 资源管理器中增加了引用名 .4 通过引用名实现数据类型的使用和方法调用 使用刚才建立的 WEB 引用的引用名称，可获取其中的复杂数据类型、方法和 SOAPHeader 的定义， CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 13 页 共 69 页 在客户端实例化后可以使用。它的操作就像在本地类一样方便，其中 SOAPHeader 的内容的处理有别于 一般复杂类型。SOAPHeader 分为类型和值两部分，先实例类型，再将数据赋给 SOAPHeader 的值 RequestSOAPHeaderValue。 图 4.5 对 SOAPHeader 的数据填充 图 4.6 一般复杂类型的赋值 .5 异常的捕捉 客户端异常包括本身程序执行异常和 SOAP 消息传来的异常，WEB 服务端不处理异常，只把异常通 过 SOAP 消息中的 Fault 部分传递给客户端。 图 4.7 捕捉本地程序执行异常 图 4.8 捕捉 SOAP 消息包含的异常 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 14 页 共 69 页 图 4.9 ISAG 异常消息 图 4.10 客户端 SOAP 异常显示 MessageId 为异常代号，text 为异常信息，%1为 text 中%+序号的标识部分的说明。 .6 具体实现 见附件部分； 4.1.2 短信接收 模块介绍 短信接收： 接口：SmsNotification notifySmsReception：网关将发送到特定地址的短消息告知应用； 消息接收 文本消息的接收是 ISAG 给 SP 发的消息，SP 没有具体返回值。SP 接受消息的实现是在 SP 端建立 一个 WEB SERVICE 服务端，有自己的 URL，ISAG 向此 URL 发送符合格式的消息，WEB SERVICE 将消息存入数据库，然后执行程序显示收到的消息。WEB SERVICE 没有界面，消息的显示是由一个 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 15 页 共 69 页 Windows 窗体取数据库中的数据，进而显示。 图 4.11 消息存储的数据库和异常存储文件 ID 为消息的编号，是以时间编号值类型为“yyyyMMddhhmmss”,如：922。Status 表示消息是否被 阅读过，值为1表示未读，其他值为已读。Error.txt 存储 WEB SERVICE 运行中的异常。 此处使用数据库和文件存储接收来的数据，仅供参考，具体业务中数据处理由业务开发人员根据本 地实际需要操作。 消息的显示 .1 消息显示界面 消息的显示是通过另一个 Windows 窗体实现的，它读取 ACCESS 数据库，显示消息内容，消息的 显示有两种方式，自动读取新消息和全部提取消息。自动读取消息是在时间周期内读取 status 值为1 的消息，将其 ID 显示的消息列表中，用户点击消息所在行，右边的消息框中显示其具体内容。 数据库路径是程序读取的数据源，此设置是消息显示的前奏，点“.”按钮，会出现文件选择的对话 框，选择消息存储的 ACCESS 文件， “确认” ，其路径即显示在文本框中。 消息列表是消息的标识部分，点击其所在行，对应详细消息会在右边“消息内容”中显示，在消息 内容的最上面的四项值为 SOAPHeader 部分数据，下面为 SOAPBody 部分数据。 图 4.12 消息显示界面 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 16 页 共 69 页 .2 具体实现 见附件部分； 4.1.3 彩信发送 模块介绍 彩信发送： 接口：SendMessage sendMessage：应用发送消息给网关； 界面 图 4.13 彩信发送界面 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 17 页 共 69 页 设计过程 .1 获取 WSDL 文档 彩信发送用到的 WSDL 文件有： 图 4.14 彩信发送需 WSDL 文档 .2 修改 WSDL 文档 详见 7.6.2 节； .3 添加 WEB 引用 首先，在 Microsoft Visual Studio 2005 新建窗体项目； 其次，添加对 ISAG WEB SERVICE 的 WEB 引用： 图 4.15 添加对 ISAG 的 WEB 引用 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 18 页 共 69 页 图 4.16 解决方案中增加引用项 .4 使用引用 引用的使用和短信发送类似，请参见短信发送介绍。 .5 异常的捕捉 异常捕捉同短信发送类似，请参见短信发送介绍。 .6 具体实现 具体实现见附件部分。 SOAP 附件实现 在原有短信中增加文件附件即实现彩信的发送，在.NET 中附件的格式为 application/dime，使用微 软组件 WSE2.0 SP3 实现附件与短信的绑定： 1、安装 WSE2.0 SP3 2、增加引用： 图 4.17 对 WSE2.0 的引用（Microsoft.Web.Services2 ） 3、添加命名空间： CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 19 页 共 69 页 图 4.18 增加命名空间的引用 4、添加 WSDL 文档的 WEB 引用后，在此工程项目中就自动下载相关文件，并生成代理类： 图 4.19 WEB 引用生成文件 5、修改代理类的基类： 图 4.20 生成代理类后默认基类 修改默认基类为： 图 4.21 修改后基类 6、增加附件代码： 图 4.22 添加文本附件代码 其他多媒体附件的添加类似，如下： 图 4.23 其他类型文件附件 4.1.4 彩信接收 彩信与短信的不同在于数据的类型，彩信中增加了多媒体文件部分，实现中将文件当做附件传输， 对于文字与文件共存的情况，我们将文字部分当做文本文件依然使用附件传输。 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 20 页 共 69 页 彩信接收： 接口： MessageNotification notifyMessageReception：网关将发送到特定号码的消息告知应用； 主要代码 图 4.24 附件接收部分代码 图 4.25 SOAPHeader 的定义部分 图 4.26 接收到的文件 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 21 页 共 69 页 具体实现 实现与短信的接收类似，可参考开发； 详见附件部分； 4.1.5 网页推送（WAP PUSH） 模块介绍 网页推送： 接口：SendPushMessage sendPushMessage：向指定的用户终端推送一个网页； 界面 图 4.27 网页推送界面 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 22 页 共 69 页 设计过程 .1 获取 WSDL 文档 图 4.28 需要 WSDL 文档 .2 修改 WSDL 文档 详见 7.6.3 节； .3 添加 WEB 引用 图 4.29 添加对 WAP PUSH WEB SERVICE 的引用 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 23 页 共 69 页 图 4.30 在解决方案中增加引用项 .4 使用引用 引用的使用和短信发送类似，请参见短信发送介绍。 .5 异常的捕捉 异常捕捉同短信发送类似，请参见短信发送介绍。 .6 具体实现 具体实现见附件部分。 4.2GSOAP CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 29 页 共 69 页 int m, s; struct soap SMSsoap; soap_init( m = soap_bind( if(m0) soap_print_fault( system(pause); exit(-1); else fprintf(stderr,Socket creat successful:Master socket=%dn,m); cout- Information Show(5:5210) -endl; int AccNum=1; for(;AccNum+) s=soap_accept( if(s0) soap_print_fault( exit(-1); cout24) if(soap_serve( soap_end( soap_done( system(pause); return 0; 此编码是绑定 IP 和 Port，并循环接收 Client 的请求消息。 3编码被调用方法 详见附件程序源码； 此编码为具体方法的实现部分，至此一个简单的 WEB 服务创建完毕。 接收显示 接收 ISAG 发来的短信消息，控制台如下显示： CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 30 页 共 69 页 图 4.44 接收短信并显示信息 至此可以确认我们的 WEB 服务运行成功。 4.2.3 彩信发送 获取 WSDL 文档 图 4.45 彩信发送需 WSDL 文档 原电信 WSDL 文档需修改，详见 7.6.2 节； 生成可用文件 把获取到的 WSDL 文档部署在一个可用的 WEB 服务器上（详细操作见 7.3 节） ，供生成可用文件。 http:/localhost/ctcc_mm_send_service_2_2.wsdl 为在本地部署的短信发送需 WSDL 文档 URL。 wsdl2h -s -o SendMessageClient.h http:/localhost/mm/ctcc_mm_send_service_2_2.wsdl /C+文件 soapcpp2 -C ./SendMessageClient.h 这两个命令即可生成我们需要的文件。详细操作参见 7.4 节。 文件复制到项目目录下 将 soapcpp2 生成的文件添加到 VC 创建的工程目录下，短信需要的文件如图 1.4 所示： CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 31 页 共 69 页 图 4.46 SendMessage 需文件 同时，我们还需要另外两个文件，stdsoap2.cpp 和 stdsoap2.h，将他们一同复制到我们的工程目录 下（这两个文件的获取参见 7.5.3 节） 。 编译设置 其他类似短信操作，请参见短信； 回应显示 图 4.47 显示彩信标识 当控制台能够显示这样的正确标识时，就表示彩信发送已成功。 4.2.4 彩信接收 彩信接收类似短信，具体到我们的 ISAG 彩信附件分为 DIME 格式和 MIME 格式，接收时需要选择 接收。DIME 和 MIME 是 ISAG 都支持的附件格式，SP 做业务开发时根据开发环境选择任何一种实现。 获取 WSDL 文档 图 4.48 彩信接收需 WSDL 文档 原电信文档需要修改，详见 7.6.5 节； 生成文件 使用 GSOAP 工具根据 WSDL 文档生成我们需要的文件： wsdl2h -s -o MmNotification.h http:/localhost/MmNotify/ctcc_mm_notification_service_2_2.wsdl CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 32 页 共 69 页 soapcpp2 -L ./MmNotification.h 图 4.49 彩信*.h 文件 图 4.50 *.h 生成的文件 复制文件到新建控制台空工程目录下，设置 soapC.cpp、soapServer.cpp、stdsoap2.cpp 编译属性。 编码设计 参考短信接收实现部分； 附件接收 附件接收在此显示附件的信息，保存附件设置文件存储即可，主要代码为： DIME 格式： int Attnum=1; for (soap_multipart:iterator attachment=MMsoap-dime.begin(); attachment!=MMsoap-dime.end(); attachment+) cout*DIME attachment:Attnumendl; coutMemory=(void*)(*attachment).ptrendl; coutSize=(*attachment).sizeendl; coutType=(*attachment).type?(*attachment).type:null)endl; coutID=(*attachment).id?(*attachment).id:null) mime.end();attachment+) if(Attnum=0);/第一个附件为 SOAP 头和体部分，去除！ else CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 33 页 共 69 页 cout *MIME attachment:Attnumendl; cout Memory= (void*)(*attachment).ptr endl; cout Size=(*attachment).sizeendl; cout ncoding=(*attachment).encodingendl; cout Type=(*attachment).type?(*attachment).type:null)endl; cout ID=(*attachment).id?(*attachment).id:null)endl; cout Location=(*attachment).location?(*attachment).location:null)endl; cout Description=(*attachment).description?(*attachment).description:null)endl; Attnum+; MIME 与 DIME 不同的是，MIME 将 SOAP 消息头和体部分也当做附件计算，在接收时我们只要从 它第二个附件保存即可。具体实现见附件部分的程序源码； 接收显示 MIME 格式彩信： CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 34 页 共 69 页 图 4.51 MIME 格式 SOAP 消息显示 DIME 格式彩信： 图 4.52 DIME 格式 SOAP 消息显示 得到如图显示就表示我们的彩信接收 WEB SERVICE 服务端创建成功。 4.2.5 网页推送（WAP PUSH） 获取 WSDL 文档 图 4.53 WAP 需用 WSDL 文档 原电信 WSDL 文档需修改，详见 7.6.3 节； 生成可用文件 把获取到的 WSDL 文档部署在一个可用的 WEB 服务器上（详细操作见 7.3 节） ，供生成可用文件。 CINtel 专业从事通信网络增值产品领域、做一个优秀的专业通信网络增值产品供应商 第 35 页 共 69 页 http:/localhost/wap/ctcc_wap_push_send_service_1_0.wsdl 为在本地部署的 WAP 需 WSDL 文档 URL。 使用命令： wsdl2h -s -o WapClient.h http:/localhost/wap/ctcc_wap_push_send_service_1_0.wsdl /C+代码 soapcpp2 -C ./WapClient.h 这两个命令即可生成我们需要的文件。详细操作参见 7.4 节。 文件复制到项目目录下 将 soapcpp2 生成