PHP SMGW短消息网关客户端开发包使用详细说明new.docx
- 文档编号:12714770
- 上传时间:2023-04-21
- 格式:DOCX
- 页数:44
- 大小:130.70KB
PHP SMGW短消息网关客户端开发包使用详细说明new.docx
《PHP SMGW短消息网关客户端开发包使用详细说明new.docx》由会员分享,可在线阅读,更多相关《PHP SMGW短消息网关客户端开发包使用详细说明new.docx(44页珍藏版)》请在冰豆网上搜索。
PHPSMGW短消息网关客户端开发包使用详细说明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.1UINX平台10
8.2WINDOWS平台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]把SMGPAPI软件包解压到一个目录。
[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目录结构
目录名
子目录名
文件名
功能说明
SmGw_Client_API
Config
smgpc.ini
参数配置文件
Lib
SmGwAPI.lib
网关客户端开发包
Include
smgpapi.h
网关客户端开发包C头文件
smgpdef.h
SMGP协议头文件
Test(
unix平台)
ActiveTest.exe
链路测试文件
SendMsg
发送短消息测试文件
RecvMsg
接收短消息测试文件
SendBatch.exe
群发短消息测试文件
sendmsgc.txt
发送短消息缺省配置文件
sendbatchmsgc.txt
群发短消息缺省配置文件
num.txt
群发短消息目的号码配置文件
Msg.txt
短消息内容配置文件
Example(
win32平台)
sendmsg.c
发送短消息例子C源文件
recvmsg.c
接收短消息例子C源文件
sendrecv.c
接收发送短消息多线程例子C源文件
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函数
参数名
数据类型
说明
SINIFile
constchar*
初试化函数配置文件名,
缺省值(输入为空)是当前目录
../smgpc.ini
或者:
../config/smgpc.ini
例如:
InitSMGPAPI(NULL);
如果上述目录没有配置文件,请输入完整的路径名。
例如:
InitSMGPAPI(“E:
\SmGw_Client_API\config\smgpc.ini”);
5.2发送一条短消息
参数名
数据类型
说明
nNeedReply
Int
是否返回状态确认报告
(0:
不要求;1:
要求)
NEED_REPORT_YES
NEED_REPORT_NO
nMsgLevel
Int
信息级别
(0:
最低优先级1:
正常2:
紧急3:
十分紧急)
SUBMIT_PRIORITY_LOWEST
SUBMIT_PRIORITY_NORMAL
SUBMIT_PRIORITY_ABOVE_NORMAL
SUBMIT_PRIORITY_HIGHEST
sServiceID
Char(11)
业务类型,就是业务代码,比如TQYB等
nMsgFormat
Int
信息格式(一般填MSG_FORMAT_GB).
MSG_FORMAT_ASCII
MSG_FORMAT_WRITE_CARD
MSG_FORMAT_BINARY
MSG_FORMAT_UCS2
MSG_FORMAT_GB
MSG_FORMAT_PASSWORD
sFeeType
Char(3)
资费类别
FEE_FREE
FEE_BY_ITEM
FEE_BY_MONTH
FEE_BY_MAXINUM
sFeeCode
Char(7)
资费代码(以分为单位),对于资费类别为按条收费(FEE_BY_ITEM),表示该条短消息的价格
sFixedFee
Char(6)
固定的费用,对于资费类别为包月收费(FEE_BY_MONTH),表示包月费用
sValidTime
Char(18)
存活有效时间,遵循SMPP3.3协议,可以不填.
sAtTime
Char(18)
定时发送时间,遵循SMPP3.3协议,可以不填.
sChargeTermID
Char(22)
计费号码(一般填目的号码sDestTermID,不能为空,否则无法对用户计费.特殊情况填要计费的用户号码。
例如用户通过web方式发送pc到点的短消息,此处就要填写发起方在本网站登记的用户号码。
具体参见附件的关于pc到点短消息的实现方案。
)
sDestTermID
Char(22)
接收消息的目的号码
sReplyPath
Char(22)
用户回复号码(一般填ICP自身的号码,格式为118+ICPID)
nMsgLen
Int
短消息长度
sMsgContent
Char(x)
短消息内容
sMsgID
Char(11)
返回的短消息标识
nErrorCode
Int*
返回的错误代码,请参见错误代码表
nMsgType
Int
消息类型(1:
取消订阅,2:
订阅请求,3:
点播,4:
订阅,5:
交互式操作,6:
查询,其他保留)
注意:
蓝色部分为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(UniversalTimeConstant)时间超前或落后的差距(00-48).
‘+’(p)
时间超前于UTCtime.
‘-’(p)
时间落后于UTCtime.
对于千年问题,采用时间窗口的方法来解决,具体方法为YY>90解释为19YY;否则解释为20YY。
5.3群发短消息
参数名
数据类型
说明
nNeedReply
Int
是否返回状态确认报告
(0:
不要求;1:
要求)
NEED_REPORT_YES
NEED_REPORT_NO
nMsgLevel
Int
信息级别
(0:
最低优先级1:
正常2:
紧急3:
十分紧急)
SUBMIT_PRIORITY_LOWEST
SUBMIT_PRIORITY_NORMAL
SUBMIT_PRIORITY_ABOVE_NORMAL
SUBMIT_PRIORITY_HIGHEST
sServiceID
Char(11)
业务类型
nMsgFormat
Int
信息格式
MSG_FORMAT_ASCII
MSG_FORMAT_WRITE_CARD
MSG_FORMAT_BINARY
MSG_FORMAT_UCS2
MSG_FORMAT_GB
MSG_FORMAT_PASSWORD
sFeeType
Char(3)
资费类别
FEE_FREE
FEE_BY_ITEM
FEE_BY_MONTH
FEE_BY_MAXINUM
sFeeCode
Char(7)
资费代码(以分为单位)
sFixedFee
Char(6)
固定的费用
sValidTime
Char(18)
存活有效时间,遵循SMPP3.3协议
sAtTime
Char(18)
定时发送时间,遵循SMPP3.3协议
sChargeTermID
Char(22)
计费号码
sDestTermIDFile
Char(100)
保存接收消息目的号码的文件
sReplyPath
Char(22)
用户回复号码
nMsgLen
Int
短消息长度
如果为0,表示sMsgFile是文件名,消息内容由该文件获得
如果为非0,表示sMsgFile是短消息内容
sMsgFile
Char(x)
短消息内容或者保存短消息内容的文件名
sMsgIDFile
Char(11)
保存的短消息标识或者错误码的文件
nMsgType
Int
消息类型
注意:
蓝色部分为1.3协议增加。
5.4获取群发短信结果
参数名
数据类型
说明
sMsgIDFile
Char(100)
保存的短消息标识或者错误码的文件
nPos
Int
短信位置从0开始
pSendBatchResp
SendBatchResp*
用于保存结果的SendBatchResp结构指针
参数名
数据类型
说明
sMsgID
Char(10)
短消息标识
nErrorCode
Int
错误码
sPhoneNo
Char(22)
发送的目的号码
5.5接收短信
参数名
数据类型
说明
nTimeout
Int
输入等待的最大延时,如果是0表示永远等待。
单位为秒
pDeliverResp
DeliverResp*
保存短信的DeliverResp结构指针
参数名
数据类型
说明
sMsgID
Char(11)
短消息标识
nIsReport
Int
是否状态报告
nMsgFormat
Int
信息格式
MSG_FORMAT_ASCII
MSG_FORMAT_WRITE_CARD
MSG_FORMAT_BINARY
MSG_FORMAT_UCS2
MSG_FORMAT_GB
MSG_FORMAT_PASSWORD
sRecvTime
Char(16)
接收时间((格式:
yyyymmddhhmiss,例如20010301200000)
sSrcrmID
Char(22)
发送消息的源终端号码
sDestTermID
Char(22)
发送消息的目的号码
nMsgLen
Int
短消息长度
sMsgContent
Char(252)
短消息内容
5.6设置参数函数
参数名
数据类型
说明
sKey
Char(15)
ICP密码
6配置参数说明
名称
说明
IcpId
ICP编号
IcpShareKey
ICP密码
WithPrevPage
分割短信前置说明文字
WithNextPage
分割短信后置说明文字
PageSpaceAscii
ASCII短信的最大长度
PageSpaceGB
中文短信的最大长度
PageSpaceBinary
二进制短信的最大长度
WithPageIndex
分割短信时是否附件页号
MaxPage
最大分割页数
ClientIP
短信网关客户端主机的IP地址
ServerIP
短信网关服务端主机的IP地址
ServerPort
短信网关的端口号
SubmitRetry
发送短消息的自动重试次数
RequestTimeout
发送请求的超时时间,单位为秒
LogLevel
日志文件等级0:
正式1:
调试
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。
执行命令“makecleanall”.具体使用请参阅Test目录下的例子程序。
注意:
SMGPAPI需要使用pthread库,在Solaris和Linux平台编译时需
要加入-lpthread,在FreeBSD编译时需要加入-pthread。
8.2WINDOWS平台
安装VC5.0或6.0,在编译环境的项目设置中的连接库中增加SmGwAPI.lib:
网关客户端开发包和Ws2_32.lib:
WINSOCK库函数。
具体使用请参阅Example目录下的例子程序.
9网关客户端开发包支持的平台
FreeBSD3.x,4.2
Solaris5.6,5.7,5.8(包含x86)
Linux(Redhat和Slack)
WindowsNT/2000
CompaqAlphaTru64Unix.
IBMAIXVersion4
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错误代码
错误代码
意义说明
0
成功
1
非法数据包
2
登录失败
3
非法消息格式
4
非法消息长度
5
非法资费代码
7
非法业务ID
8
系统忙
10
非法短信发送号码
11
非法短信格式
12
非法资费类型
13
非法有效时间
14
非法定时发送时间
15
非法计费号码
16
非法目标号码
17
非法目标号码文件
18
非法消息文件
20
连接网关出错
21
非法鉴权信息
23
发送消息队列满
25
非法命令ID
26
非法序列号
29
非法版本号
30
非法消息类型
31
非法发送优先级
35
非法时间类型
38
非法查询类型
39
非法路由
40
非法固定费
46
非法源号码
99
系统错误
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的数据包格式
字段
长度(字节)
类型
描述
操作码
2
Integer
用以描述不同的操作类型。
这里为0x8081
长度
1
Integer
从消息序列号开始一直到内容的结尾的总长
消息序列号
4
Integer
用于唯一标识一条消息。
本域应和IIS至CP的数据包的消息序列号相一致。
加密方式
1
Integer
对内容域进行加密的方式。
具体值参见12.3.2
业务代码
10
OctetString
表示本级菜单的业务类型。
询问方式
1
Integer
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- PHP SMGW短消息网关客户端开发包使用详细说明new SMGW 短消息 网关 客户端 开发 使用 详细 说明 new