短消息网关客户端开发包使用详细说明

1、技技 术术 文文 件件技术文件名称：短消息网关短消息网关客户端开发客户端开发包使用详细包使用详细说明说明 技术文件编号： 版 本： 文件质量等级：共 10 页 拟 制 审 核 会 签 标准化 批 准 深圳市中兴深圳市中兴通讯股份有通讯股份有限公司限公司 短消息网关客户端开发包使用详细说明第 2 页 共 11 页目录目录1功能说明功能说明.32安装安装.33目录结构目录结构.34接口函数功接口函数功能说明能说明.44.1初始化 API 函数.44.2发送和接收函数.44.2.1发送1 条短信.44.2.2群发短信.44.2.3获取群发短信结果.44.2.4接收短信.44.2.5设置参数函数.54

2、.3查询和测试函数.54.3.1检查短信网关是否能够提供服务.54.3.2查询短消息信息.55函数参数和函数参数和数据结构说数据结构说明明.55.1初始化 API 函数.55.2发送一条短消息.55.3群发短消息.65.4获取群发短信结果.75.5接收短信.75.6设置参数函数.86配置参数说配置参数说明明.87短信的自动短信的自动分割功能分割功能.98编译说明编译说明.98.1UINX 平台.98.2WINDOWS 平台.99网关客户端网关客户端开发包支持开发包支持的平台的平台.910例子程序说例子程序说明明.1010.1简单测试程序.1010.2综合测试程序.1011错误代码错误代码.10

3、12其它说明其它说明.10 短消息网关客户端开发包使用详细说明第 3 页 共 11 页短消息网关短消息网关客户端开发客户端开发包使用详细包使用详细说明说明1 1功能说明功能说明短消息网关客户端开发包的主要功能是：为 ICP(SP)应用提供标准的 API接口，通过该接口,ICP 可以基于 SMGP 协议和短消息网关 SMGW 通讯。该开发包具有以下特点。1与 SMGW通讯既支持短连接方式也支持长连接方式；2支持 SMGP 协议；3参数配置功能；4友好的参数接口。2 2安装安装1把SMGP API 软件包解压到一个目录。2修改./ SmGw_Client_API /config/smgpc.ini

4、 ，修改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 3目录结构目录结构目录名子目录名文件

5、名功能说明Configsmgpc.ini参数配置文件LibSmGw_Client_API.lib网关客户端开发包smgpapi.h网关客户端开发包 C 头文件smgpapi.hpp网关客户端开发包 C+头文件Includesmgpdef.hSMGP 协议头文件ActiveTest.exe链路测试文件SendMsg发送短消息测试文件RecvMsg接收短消息测试文件SendBatch.exe群发短消息测试文件sendmsgc.txt发送短消息缺省配置文件sendbatchmsgc.txt群发短消息缺省配置文件num.txt群发短消息目的号码配置文件TestMsg.txt群发短消息短消息内容配置文件

6、Sendmsg.c发送短消息例子 C 源文件Sendmsg.h发送短消息例子头文件Recvmsg.c接收短消息例子 C 源文件SmGw_Client_APIExampleRecvmsg.h接收短消息例子头文件 短消息网关客户端开发包使用详细说明第 4 页 共 11 页4 4接口函数功接口函数功能说明能说明4.1初始化初始化 API 函数函数函数名：函数名：InitSMGPAPI();功能：功能：读取配置文件，完成初始化的工作。1系统资源的初始化：包括线程和线程同步所涉及的系统资源的创建和设置；定时资源的设置；通信消息机制的设置；内存管理的初始化设置，队列管理的设置。2通信参数初始化：包括服务器

7、端 IP 地址；客户端器端IP 地址；通信端口号。3业务参数初始化：包括：短信分割参数；短信最大长度；发送短信自动重试次数；发送请求超时时间等。4ICP 参数初始化：ICP 编号和密码。返回：返回：0 成功 1 失败4.2发送和接收发送和接收函数函数4.2.1发送发送 1 条短信条短信函数名：函数名：SMGPSendSingle()功能：功能：向短信网关发送1 条短信到1 个话机用户。短信长度可以大于160 ，API 能够自动分割短信。在发送过程中，如果因为通信原因导致发送失败，API 能够自动重新发送。返回：返回：0 成功 1 失败4.2.2群发短信群发短信函数名：函数名：SMGPSendB

8、atch()功能：功能：向短信网关发送1 条短信到多个手机用户。短信长度可以大于160 ，API 能够自动分割短信。此函数使用文件传递短信内容。在发送过程中如果因为通信原因导致发送失败，API 能够自动重新发送。返回：返回：0 成功 1 失败4.2.3获取群发短获取群发短信结果信结果函数名：函数名：GetSendBatchResp ()功能：功能：从文件里读取群发的某一个短信的标识、发送结果和发送号码。返回：返回：0 成功 1 失败4.2.4接收短信接收短信函数名：函数名：SMGPDeliver ()功能：功能：连接短信网关，等待接收属于本ICP 的短信，需要输入等待的最大延时，如果是0表示永

9、远等待。返回：返回：0 成功 1 失败 短消息网关客户端开发包使用详细说明第 5 页 共 11 页4.2.5设置参数函设置参数函数数函数名：函数名：SMGPSetKey ()功能：功能：设置新的ICP密码 返回：返回：0 成功 1 失败4.3查询和测试查询和测试函数函数4.3.1检查短信网检查短信网关是否能够关是否能够提供服务提供服务函数名：函数名：SMGPActiveTest ()功能：功能：检查短信网关是否能够提供服务返回：返回：0 成功 1 失败4.3.2查询短消息查询短消息信息信息函数名：函数名：SMGPQuery ()功能：功能：根据短消息服务ID号查询短消息信息函数的原型请参阅文件

10、./ SmGw_Client_API /Include/amgpapi.h。返回：返回：0 成功 1 失败5 5函数参数和函数参数和数据结构说数据结构说明明5.1初始化初始化 API 函数函数参数名参数名数据类型数据类型说明说明sINIFileconst char *初试化函数配置文件名，缺省值（输入为空）是当前目录./smgpc.ini或者:./config/smgpc.ini例如：InitSMGPAPI（NULL） ；如果上述目录没有配置文件，请输入完整的路径名。例如：InitSMGPAPI(“E:SmGw_Client_APIconfig smgpc.ini”)；5.2发送一条短发送一条

11、短消息消息参数名参数名数据类型数据类型说明说明nNeedReplyInt是否返回状态确认报告 短消息网关客户端开发包使用详细说明第 6 页 共 11 页（0：不要求；1:要求）NEED_REPORT_YESNEED_REPORT_NOnMsgLevelInt信息级别（0:最低优先级 1:正常 2:紧急 3:十分紧急）SUBMIT_PRIORITY_LOWESTSUBMIT_PRIORITY_NORMALSUBMIT_PRIORITY_ABOVE_NORMALSUBMIT_PRIORITY_HIGHESTsServiceIDChar(11)业务类型nMsgFormatInt信息格式MSG_FOR

12、MAT_ASCIIMSG_FORMAT_WRITE_CARDMSG_FORMAT_BINARYMSG_FORMAT_UCS2MSG_FORMAT_GBMSG_FORMAT_PASSWORDsFeeTypeChar(3)资费类别FEE_FREEFEE_BY_ITEMFEE_BY_MONTHFEE_BY_MAXINUMsFeeCodeChar(7)资费代码（以分为单位）sFixedFeeChar(6)固定的费用SValidTimeChar(18)存活有效时间，遵循 SMPP3.3 协议sAtTimeChar(18)定时发送时间，遵循 SMPP3.3 协议sChargeTermIDChar(22)计

13、费号码sDestTermIDChar(22)接收消息的目的号码sReplyPathChar(22)用户回复号码nMsgLenInt短消息长度sMsgContentChar(x)短消息内容sMsgIDChar(11)返回的短消息标识nErrorCodeInt*返回的错误代码，请参见错误代码表nMsgTypeInt消息类型注意：蓝色部分为注意：蓝色部分为1.3 协议增加协议增加。5.3群发短消息群发短消息参数名参数名数据类型数据类型说明说明nNeedReplyInt是否返回状态确认报告（0：不要求；1:要求）NEED_REPORT_YESNEED_REPORT_NOnMsgLevelInt信息级别

14、（0:最低优先级 1:正常 2:紧急 3:十分紧急）SUBMIT_PRIORITY_LOWESTSUBMIT_PRIORITY_NORMAL 短消息网关客户端开发包使用详细说明第 7 页 共 11 页SUBMIT_PRIORITY_ABOVE_NORMALSUBMIT_PRIORITY_HIGHESTsServiceIDChar(11)业务类型nMsgFormatInt信息格式MSG_FORMAT_ASCIIMSG_FORMAT_WRITE_CARDMSG_FORMAT_BINARYMSG_FORMAT_UCS2MSG_FORMAT_GBMSG_FORMAT_PASSWORDsFeeTypeC

15、har(3)资费类别FEE_FREEFEE_BY_ITEMFEE_BY_MONTHFEE_BY_MAXINUMsFeeCodeChar(7)资费代码（以分为单位）sFixedFeeChar(6)固定的费用sValidTimeChar(18)存活有效时间，遵循 SMPP3.3 协议sAtTimeChar(18)定时发送时间，遵循 SMPP3.3 协议sChargeTermIDChar(22)计费号码sDestTermIDFi leChar(100)保存接收消息目的号码的文件sReplyPathChar(22)用户回复号码nMsgLenInt短消息长度如果为 0，表示 sMsgFile是文件名，消

16、息内容由该文件获得如果为非 0，表示 sMsgFile是短消息内容sMsgFileChar(x)短消息内容或者保存短消息内容的文件名sMsgIDFileChar(11)保存的短消息标识或者错误码的文件nMsgTypeInt消息类型注意：蓝色部分为注意：蓝色部分为1.3 协议增加协议增加。5.4获取群发短获取群发短信结果信结果参数名参数名数据类型数据类型说明说明sMsgIDFileChar(100)保存的短消息标识或者错误码的文件nPosInt短信位置从0 开始PSendBatchRespSendBatchResp*用于保存结果的 SendBatchResp结构指针参数名参数名数据类型数据类型说

17、明说明sMsgIDChar(10)短消息标识nErrorCodeInt错误码sPhoneNoChar(22)发送的目的号码5.5接收短信接收短信参数名参数名数据类型数据类型说明说明 短消息网关客户端开发包使用详细说明第 8 页 共 11 页nTimeoutInt输入等待的最大延时，如果是 0 表示永远等待。单位为秒pDeliverRespDeliverResp*保存短信的DeliverResp 结构指针参数名参数名数据类型数据类型说明说明sMsgIDChar(11)短消息标识nMsgFormatInt信息格式MSG_FORMAT_ASCIIMSG_FORMAT_WRITE_CARDMSG_FO

18、RMAT_BINARYMSG_FORMAT_UCS2MSG_FORMAT_GBMSG_FORMAT_PASSWORDsRecvTimeChar(16)接收时间sSrcrmIDChar(22)发送消息的源终端号码sDestTermIDChar(22)发送消息的目的号码nIsReplyChar(22)是否为应答消息（0:非应答消息1:应答消息）NEED_REPLY_YESNEED_REPLY_NOnMsgLenInt短消息长度sMsgContentChar(252)短消息内容5.6设置参数函设置参数函数数参数名参数名数据类型数据类型说明说明sKeyChar(15)ICP 密码6 6配置参数说配置参

19、数说明明名称名称说明IcpIdICP 编号IcpShareKeyICP 密码WithPrevPage分割短信前置说明文字WithNextPage分割短信后置说明文字PageSpaceAsciiASCII短信的最大长度PageSpaceGB中文短信的最大长度PageSpaceBinary二进制短信的最大长度WithPageIndex分割短信时是否附件页号MaxPage最大分割页数ClientIP短信网关客户端主机的IP 地址ServerIP短信网关服务端主机的IP 地址ServerPort短信网关的端口号 短消息网关客户端开发包使用详细说明第 9 页 共 11 页SubmitRetry发送短消息

20、的自动重试次数RequestTimeout发送请求的超时时间，单位为秒PermimentOrTemp长连接或者短连接方式1:长连接 0:短连接方式LogLevel日志文件等级 0:正式 1: 调试LinkTest是否进行链路检测，0:否；1:是ProtocalChng1.0 协议和 1.3 协议转换，0：否；1：是SmgpAPISeqNum在同一台机器上客户端程序的运行顺序，如果只有一个程序，该值为 0；如果再运行一个客户端程序，该值为 1；如果还需要运行一个客户端程序，该值为2；以此类推，等等。7 7短信的自动短信的自动分割功能分割功能SMGPSendSingle 和SMGPSendBatc

21、h 提供自动分割短信的功能，分割的效果由smgpc.ini 的配置控制。当参数nMsgFormat 等于0/15 时，API 就提供分割短信功能。API 扫描短信的内容，把短信分段，根据每一段的短信内容设置nMsgFormat。如果某一段短信含有中文，就把那一段短信的发送格式设为15，取PageSpaceGB 为最大长度；如果不含中文，就把那一段短信的发送格式设为0，取PageSpaceAscii 为最大长度。这样，可以充分利用短信的最大发送长度，减少分割数量。但是，如果WithPrevPage 或者PageSpaceGB 含有汉字，所有分割短信的发送格式都设为15。当参数nMsgFormat

22、 等于4 时，API 根据PageSpaceBinary 配置分割短信。当参数nMsgFormat 等于0 并且长度小于PageSpaceGB，API 扫描短信内容是否含有中文。如果发现中文，就自动把发送格式变为15。8 8编译说明编译说明8.1UINX 平平台台安装编译程序gcc或者cc。执行命令 “make clean all”makefile文件的请参阅例子程序。 C编译器包含头文件smgpapi.h；C+编译器包含头文件smgpapi.hpp。注意：SMGP API 需要使用pthread 库，在Solaris 和Linux 平台编译时需要加入-lpthread，在Free BSD 编译时需要加入-pthread。 8.2WINDOWS 平台平台安装VC 5.0 或6.0，在编译环境的项目设置中的连接库中增加SmGw_Client_API.lib：网关客户端开发包和Ws2_