PHP (SMGW)短消息网关客户端开发包使用详细说明(new)

技术文件
技术文件名称：短消息网关客户端开发包使用详细说明技术文件编号：
版本：V3.5
文件质量等级：
共26页
(包括封面)
拟制
审核
会签
标准化
批准
深圳市中兴通讯股份有限公司
目录
1功能说明 (3)
2安装 (3)
3目录结构 (3)
4接口函数功能说明 (4)
4.1 初始化API函数 (4)
4.2 发送和接收函数 (4)
4.2.1发送1 条短信 (4)
4.2.2群发短信 (4)
4.2.3获取群发短信结果 (4)
4.2.4接收短信 (4)
4.2.5设置参数函数 (5)
4.3 查询和测试函数 (5)
4.3.1检查短信网关是否能够提供服务 (5)
4.3.2查询短消息信息 (5)
5函数参数和数据结构说明 (5)
5.1 初始化API函数 (5)
5.2 发送一条短消息 (5)
5.3 群发短消息 (7)
5.4 获取群发短信结果 (8)
5.5 接收短信 (8)
5.6 设置参数函数 (9)
6配置参数说明 (9)
7短信的自动分割功能 (9)
8编译说明 (10)
8.1 UINX平台 (10)
8.2 WINDOWS平台 (10)
9网关客户端开发包支持的平台 (10)
10例子程序说明 (10)
10.1 简单测试程序 (10)
10.2 综合测试程序 (10)
11错误代码 (10)
12ICP如何就V1.3版本协议进行处理的说明 (11)
12.1 交互式订阅、点播流程(动态菜单功能、多次交互功能) (12)
12.1.1数据包格式 (13)
12.2 非交互式服务流程 (16)
12.2.1信息订阅流程 (16)
12.2.2信息点播流程 (17)
12.2.3数据包格式 (17)
12.3 参数定义 (19)
12.3.1操作码参数表 (19)
12.3.2加密方式参数表 (19)
12.3.3订阅标识参数表 (20)
12.3.4询问方式参数表 (20)
12.3.5计费方式参数表 (20)
12.3.6服务代码参数表 (20)
12.3.7数据类型说明 (20)
12.3.8回执格式： (21)
13ICP开发中常遇到的问题 (22)
14关于从PC到点的的点对点短消息相关规范 (23)
15其它说明 (25)
短消息网关客户端开发包使用详细说明
1功能说明
短消息网关客户端开发包的主要功能是：为ICP(SP)应用提供标准的API接口，通过该接口,ICP可以基于SMGP协议和短消息网关SMGW通讯。

该开发包具有以下特点。

[1]与SMGW通讯既支持短连接方式也支持长连接方式；
[2]支持SMGP协议；
[3]参数配置功能；
[4]友好的参数接口。

2安装
[1]把SMGP API 软件包解压到一个目录。

[2]修改../ SmGw_Client_API /config/smgpc.ini ，修改IcpId （ICP 编号）、IcpShareKey （ICP密码，缺省是123456789）、ClientIP （客户主机的IP 地址）和ServerIP （短信网关地址）。

[3]使用../ SmGw_Client_API /Test/ActiveTest测试通讯链路和网关服务器端是否激
活。

[4]使用../ SmGw_Client_API /Test/SendMsg 尝试发送短消息。

[5]使用../ SmGw_Client_API /Test/RecvMsg尝试接收消息。

[6]使用../ SmGw_Client_API /Test/SendBatch尝试群发消息。

3目录结构
4接口函数功能说明
4.1初始化API函数
函数名：InitSMGPAPI();
功能：读取配置文件，完成初始化的工作。

[1]系统资源的初始化：包括线程和线程同步所涉及的系统资源的创建和设置；定时资源的设置；通信消息机制的设置；内存管理的初始化设置，队列管理的设置。

[2]通信参数初始化：包括服务器端IP地址；客户端器端IP地址；通信端口号。

[3]业务参数初始化：包括：短信分割参数；短信最大长度；发送短信自动重试次数；发送请求超时时间等。

[4]ICP参数初始化：ICP编号和密码。

返回：0 成功
1 失败
4.2发送和接收函数
4.2.1发送1 条短信
函数名：SMGPSendSingle()
功能：向短信网关发送1 条短信到1 个话机用户。

短信长度可以大于160 ，API 能够自动分割短信。

在发送过程中，如果因为通信原因导致发送失败，API 能够自动重新发送。

返回：0 成功
1 失败
4.2.2群发短信
函数名：SMGPSendBatch()
功能：向短信网关发送1 条短信到多个手机用户。

短信长度可以大于160 ，API 能够自动分割短信。

此函数使用文件传递短信内容。

在发送过程中如果因为通信原因导致发送失败，API 能够自动重新发送。

返回：0 成功
1 失败
4.2.3获取群发短信结果
函数名：GetSendBatchResp ()
功能：从文件里读取群发的某一个短信的标识、发送结果和发送号码。

返回：0 成功
1 失败
4.2.4接收短信
函数名：SMGPDeliver ()
功能：连接短信网关，等待接收属于本ICP 的短信，需要输入等待的最大延时，如果是0表示永远等待。

返回：0 成功
1 失败
4.2.5设置参数函数
函数名：SMGPSetKey ()
功能：设置新的ICP密码
返回：0 成功
1 失败
4.3查询和测试函数
4.3.1检查短信网关是否能够提供服务
函数名：SMGPActiveTest ()
功能：检查短信网关是否能够提供服务
返回：0 成功
1 失败
4.3.2查询短消息信息
函数名：SMGPQuery ()
功能：根据短消息服务ID号查询短消息信息
函数的原型请参阅文件../ SmGw_Client_API /Include/amgpapi.h。

返回：0 成功
1 失败
5函数参数和数据结构说明
5.1初始化API函数
5.2发送一条短消息
注意：蓝色部分为1.3协议增加。

对于sValidTime和sAtTime两个字段,如果不填,则使用缺省的时间定义(由短信中心实现时设置),否则,其格式为: YYMMDDhhmmsstnnp,其含义如下所示:
YY' 年份的最后2位 (00-99)
MM 月份(01-12)
DD 日 (01-31)
Hh 小时 (00-23)
Mm 分 (00-59)
Ss 秒 (00-59)
T 十分之一秒 (0-9)
Nn 与UTC (Universal Time Constant) 时间超前或落后的差距
(00-48).
‘+’（p）时间超前于UTC time.
‘-’（p）时间落后于 UTC time.
对于千年问题，采用时间窗口的方法来解决，具体方法为YY>90解释为19YY；否则解释为20YY。

5.3群发短消息
注意：蓝色部分为1.3协议增加。

5.4获取群发短信结果
5.5接收短信
5.6设置参数函数
6配置参数说明
7短信的自动分割功能
SMGPSendSingle 和SMGPSendBatch 提供自动分割短信的功能，分割的效果由smgpc.ini 的配置控制。

当参数nMsgFormat 等于0/15 时，API 就提供分割短信功能。

API 扫描
短信的内容，把短信分段，根据每一段的短信内容设置nMsgFormat。

如果某一段短信含有中文，就把那一段短信的发送格式设为15，取PageSpaceGB 为最大长度；如果不含中文，就把那一段短信的发送格式设为0，取PageSpaceAscii 为最大长度。

这样，可以充分利用短信的最大发送长度，减少分割数量。

但是，如果WithPrevPage 或者PageSpaceGB 含有汉字，所有分割短信的发送格式都设为15。

当参数nMsgFormat 等于4 时，API 根据PageSpaceBinary 配置分割短信。

当参数nMsgFormat 等于0 并且长度小于PageSpaceGB，API 扫描短信内容是否含有中文。

如果发现中文，就自动把发送格式变为15。

8编译说明
8.1UINX平台
安装编译程序gcc或者cc。

执行命令“make clean all”.具体使用请参阅Test目录下的例子程序。

注意：SMGP API 需要使用pthread 库，在Solaris 和Linux 平台编译时需
要加入-lpthread，在Free BSD 编译时需要加入-pthread。

8.2WINDOWS平台
安装VC 5.0 或6.0，在编译环境的项目设置中的连接库中增加SmGwAPI.lib：网关客户端开发包和Ws2_32.lib：WINSOCK库函数。

具体使用请参阅Example目录下的例子程序.
9网关客户端开发包支持的平台
Free BSD 3.x, 4.2
Solaris 5.6, 5.7, 5.8(包含x86)
Linux（Redhat 和Slack）
Windows NT/2000
Compaq Alpha Tru64 Unix.
IBM AIX Version 4
10例子程序说明
10.1简单测试程序
发送消息文件：sendmsg.exe
发送消息配置文件：sendmsgc.txt、msg.txt
群发消息文件：SendBatch.exe
群发消息配置文件：sendbatchmsgc.txt、msg.txt、num.txt
接收消息文件：RecvMsg.exe
激活测试文件：ActiveTest.exe
通过观测日志文件smgpapi.log获得测试结果。

10.2综合测试程序
我们还可以提供综合的测试程序TestPrgm.exe。

该程序能够完成基本功能测试、ICP模拟测试、大话务量测试等功能。

11错误代码
12ICP如何就V1.3版本协议进行处理的说明
就V1.3版本规范需要进行修改的地方有：
1．点播、定制的提交格式已经发生了变化。

原来的格式规定由空格作为分隔符号，而目前的格式已经将分隔符号大部分去掉了，只有特殊的几个地方保留着。

对于定长的字段之间均没有了分隔符。

对于点播订阅标志也由原来的字符方式变成了2进制代码方式。

增加了交互式点播、订阅标志。

即：点击查看
2．增加了加密位，是为了以后电子商务使用，目前暂取“不加密”。

格式参见点击查看。

3．下行的点播定制消息其格式是一样的，这样的目的是为了当用户挂机时平台可以方便的将点播信息转换为定制信息发送到用户的定制信箱中。

点击查看下行的点播信息、下行的订阅信息
4．增加了动态交互菜单功能，也叫做多次交互功能，或者交互式订阅、点播功能。

其实现的机制是在终端侧当进入到特定的菜单后，其后续的菜单不是来自固网短信平台的编辑菜单（静态的），而是来自于ICP实时下发的菜单或者信息。

ICP可以发出特定的信息让用户选择菜单、进行多项选择（例如考试题）、或者将用户需要的信息显示到用户的屏
幕上。

在用户作出反映后平台将用户的反映直接发送给ICP来进行解析处理。

例如在固网短信上开展开心词典娱乐项目，首先下发一个题目让用户输入自己的选择，在用户选择后再下发第二个题目。

然后用户作出选择。

当用户答完后给出最终的分数。

其实现的机理参见点击查看。

5．增加了解决点播错位问题的手段：在点播定制中增加了序列号。

一个点播请求发送到ICP 来后，当ICP下发信息时要将这个序列号原封不动地回送给发送者。

6．短消息原来的子信箱号码是放置在消息体中的，目前已经拿出来放置到主被叫号码中了。

如果想实现网上发送短消息，就需要注意这个问题。

7．用户状态报告错误代码修正，按错误类型判断用户是否有效。

例如当一个用户申请了一项定制服务，但是当ICP下发消息后收到的回执是失败的，原因码是004：非法用户，那么ICP要将此用户的定制服务停止或者取消。

下面为V1.3协议的相关部分，供链接点击，也可作为规范查阅：
12.1交互式订阅、点播流程(动态菜单功能、多次交互功能)
CP利用菜单方式，通过IIS，达到控制CPE，和与CPE进行信息交互的作用。

每一级的菜单都用一个业务代码来表示。

CPE通过IIS，告诉CP，在哪一级菜单进行了什么操作。

如果是IIS向CP的第一个交互服务请求，则业务代码为CP预先设置的业务代码，如果无，则业务代码域为空。

12.1.1数据包格式
12.1.1.1CP至IIS的数据包格式
当命令码为0x01,即菜单询问或单项选择询问输入方式，内容域格式如下：
当命令码为0x02,即确认询问输入，内容域格式如下：
当命令码为0x03,即多项选择输入，内容域格式如下：
当命令码为0x04,即非选择性数据输入方式，内容域格式如下：
标志位定义如下：
bit0-bit3:必须输入的字符数（汉字按两个字符数）
0000：不定，对用户输入不要求
1111：必须输满全部字符，（由长度段说明的最大长度）
其他：必须至少输入此处要求的字符数。

如6，表示6个字符bit4: 输入内容显示标志
0:允许显示；
1:不显示，内容以*表示。

Bit5: 输入类型：0:数字；1:字符（汉字归字符类，为两个字符）Bit6-bit7：保留
12.1.1.2IIS至CP的数据包格式
12.2非交互式服务流程12.2.1信息订阅流程
12.2.2信息点播流程
12.2.3数据包格式
12.2.3.1IIS至CP的数据包格式
12.2.3.2CP至IIS的数据包格式
12.2.3.2.1信息订阅
12.2.3.2.2信息点播
12.2.3.2.3常用语下载
12.2.3.2.4铃声下载
当操作码为0x8085：即铃声下载时，消息体格式如下：
当操作码为0x8084：即软件下载时，具体格式由具体厂家自行决定。

12.2.3.2.5话费详单下载
当操作码为0x8087：即话费详单下载时，消息体格式如下：
12.2.3.2.6话费帐单下载
12.3参数定义
12.3.1操作码参数表
表1：操作码参数表
12.3.2加密方式参数表
表2：加密方式参数表
12.3.3订阅标识参数表
表3：订阅标识参数表
12.3.4询问方式参数表
12.3.5计费方式参数表
12.3.6服务代码参数表
12.3.7数据类型说明
表7：数据类型表
12.3.8回执格式：
回执短消息的格式采用SMPP V3.4中的规定，即以“id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD err:E Text:………”表示。

回执短消息的信息包含在短消息消息包的字段short_message中,其格式如下:
13ICP开发中常遇到的问题
1．我的程序怎么收不到平台发过来的点播请求
看是否正确注册到网关，网关上是否配置了这个ICP的用户数据，是否配置了该用户的路由信息。

2．我用测试程序联不到网关，修改了配置后也联不到网关
重启测试程序看看。

3．我为什么回点播消息不能下发，或者是下发为订阅消息
A.是否按照1.3协议规定的点播消息格式下发（注意：对普通的点播消息和动态菜单消息消息格式是不同的，很多ICP都知道在动态菜单交互中间点播订阅类型该填0x03,但最后发送结果的时候他们都喜欢填成点播或订阅类型）
B.程序处理时间太长了，需要优化程序
4．如何退出动态菜单
在动态交互流程中CP->IIS格式中命令码填0x06，其余字段可以不用理会。

5．我的内容怎么不对，到哪去了？
有的用户处理msgcontent的时候采用strcpy的方式，应该采用memcpy方式才行。

在strcpy时，将在第一个’\0’后的都截断了。

6．我收到的消息序列号，怎么我不知道是多少？
只要在响应消息里原封不动地将其填回即可，无需解析。

7．我收到的业务代码有乱码
对业务代码这类定长为CHAR类型的字段而言，’\0’之前为有效的内容。

14关于从PC到点的的点对点短消息相关规范
SMGP协议中的SUBMIT数据包格式：
网关上可以通过业务代码，对PC到点的点对点信息进行统计。

从PC到点的的点对点短消息的发送可以有如下的两种实现方式，这两种实现方式，不包括异地的PC到点的的点对点短消息的发送（如果用户出差在外，仍可以通过登录本地CP的页面，实现此功能）。

1．只有家家易平台用户才能通过PC机向另一用户发送点对点的短消息. 实现步骤是当用户在CP那申请了此业务后,由CP向用户的家家易终端发送密码。

用户需根据电话号码及密码,才能登录CP,完成通过PC向另一用户发送点对点的短消息的功能。

此时，在CP向网关发送的SUBMIT包中，发送方号码为CP代码,计费号码为发送用户的电话号码，实际的发送人用签名的方式在消息体中体现。

此种方式下，收费是由电信负责。

例如：由用户A：58750001，向用户B：68730001，发送一条短消息，内容为:我已到达,ICP 为上海热线:02100001,则ICP递交的数据包格式如下:(ICP需要状态报告)
2．是由CP的注册用户，登录网页，发送点对点短消息。

发送用户号码为ICP代码，实际的发送人用签名的方式在消息体中体现。

此时，在CP向网关发送的SUBMIT包中，发送方号码为CP代码,资费代码为免费，计费号码为空，实际的发送人用签名的方式在消息体中体现。

此种方式下，电信向CP收下行的通信费，其他费用由ICP向注册用户收取。

例如：由用户A：58750001，向用户B：68730001，发送一条短消息，内容为:我已到达,ICP 为上海热线:02100001,则ICP递交的数据包格式如下:(ICP需要状态报告)
15其它说明
本文档是目前的最新版本说明，以后版本如有变化，请使用最新的版本。

本文档和相关的软件开发包的解释权在深圳市中兴通讯股份有限公司重庆研究所。