短消息網(wǎng)關(guān)客戶端開發(fā)包使用詳細(xì)說明

1、技技 術(shù)術(shù) 文文 件件技術(shù)文件名稱：短消息網(wǎng)關(guān)短消息網(wǎng)關(guān)客戶端開發(fā)客戶端開發(fā)包使用詳細(xì)包使用詳細(xì)說明說明 技術(shù)文件編號(hào)： 版 本： 文件質(zhì)量等級(jí)：共 10 頁 擬 制 審 核 會(huì) 簽 標(biāo)準(zhǔn)化 批 準(zhǔn) 深圳市中興深圳市中興通訊股份有通訊股份有限公司限公司 短消息網(wǎng)關(guān)客戶端開發(fā)包使用詳細(xì)說明第 2 頁 共 11 頁目錄目錄1功能說明功能說明.32安裝安裝.33目錄結(jié)構(gòu)目錄結(jié)構(gòu).34接口函數(shù)功接口函數(shù)功能說明能說明.44.1初始化 API 函數(shù).44.2發(fā)送和接收函數(shù).44.2.1發(fā)送1 條短信.44.2.2群發(fā)短信.44.2.3獲取群發(fā)短信結(jié)果.44.2.4接收短信.44.2.5設(shè)置參數(shù)函數(shù).54

2、.3查詢和測(cè)試函數(shù).54.3.1檢查短信網(wǎng)關(guān)是否能夠提供服務(wù).54.3.2查詢短消息信息.55函數(shù)參數(shù)和函數(shù)參數(shù)和數(shù)據(jù)結(jié)構(gòu)說數(shù)據(jù)結(jié)構(gòu)說明明.55.1初始化 API 函數(shù).55.2發(fā)送一條短消息.55.3群發(fā)短消息.65.4獲取群發(fā)短信結(jié)果.75.5接收短信.75.6設(shè)置參數(shù)函數(shù).86配置參數(shù)說配置參數(shù)說明明.87短信的自動(dòng)短信的自動(dòng)分割功能分割功能.98編譯說明編譯說明.98.1UINX 平臺(tái).98.2WINDOWS 平臺(tái).99網(wǎng)關(guān)客戶端網(wǎng)關(guān)客戶端開發(fā)包支持開發(fā)包支持的平臺(tái)的平臺(tái).910例子程序說例子程序說明明.1010.1簡單測(cè)試程序.1010.2綜合測(cè)試程序.1011錯(cuò)誤代碼錯(cuò)誤代碼.10

3、12其它說明其它說明.10 短消息網(wǎng)關(guān)客戶端開發(fā)包使用詳細(xì)說明第 3 頁 共 11 頁短消息網(wǎng)關(guān)短消息網(wǎng)關(guān)客戶端開發(fā)客戶端開發(fā)包使用詳細(xì)包使用詳細(xì)說明說明1 1功能說明功能說明短消息網(wǎng)關(guān)客戶端開發(fā)包的主要功能是：為 ICP(SP)應(yīng)用提供標(biāo)準(zhǔn)的 API接口，通過該接口,ICP 可以基于 SMGP 協(xié)議和短消息網(wǎng)關(guān) SMGW 通訊。該開發(fā)包具有以下特點(diǎn)。1與 SMGW通訊既支持短連接方式也支持長連接方式；2支持 SMGP 協(xié)議；3參數(shù)配置功能；4友好的參數(shù)接口。2 2安裝安裝1把SMGP API 軟件包解壓到一個(gè)目錄。2修改./ SmGw_Client_API /config/smgpc.ini

4、 ，修改IcpId （ICP 編號(hào)）、IcpShareKey （ICP密碼，缺省是123456789）、ClientIP （客戶主機(jī)的IP 地址）和ServerIP （短信網(wǎng)關(guān)地址）。3使用./ SmGw_Client_API /Test/ActiveTest測(cè)試通訊鏈路和網(wǎng)關(guān)服務(wù)器端是否激活。4使用./ SmGw_Client_API /Test/SendMsg 嘗試發(fā)送短消息。5使用./ SmGw_Client_API /Test/RecvMsg 嘗試接收消息。6使用./ SmGw_Client_API /Test/SendBatch 嘗試群發(fā)消息。3 3目錄結(jié)構(gòu)目錄結(jié)構(gòu)目錄名子目錄名文件

5、名功能說明Configsmgpc.ini參數(shù)配置文件LibSmGw_Client_API.lib網(wǎng)關(guān)客戶端開發(fā)包smgpapi.h網(wǎng)關(guān)客戶端開發(fā)包 C 頭文件smgpapi.hpp網(wǎng)關(guān)客戶端開發(fā)包 C+頭文件Includesmgpdef.hSMGP 協(xié)議頭文件ActiveTest.exe鏈路測(cè)試文件SendMsg發(fā)送短消息測(cè)試文件RecvMsg接收短消息測(cè)試文件SendBatch.exe群發(fā)短消息測(cè)試文件sendmsgc.txt發(fā)送短消息缺省配置文件sendbatchmsgc.txt群發(fā)短消息缺省配置文件num.txt群發(fā)短消息目的號(hào)碼配置文件TestMsg.txt群發(fā)短消息短消息內(nèi)容配置文件

6、Sendmsg.c發(fā)送短消息例子 C 源文件Sendmsg.h發(fā)送短消息例子頭文件Recvmsg.c接收短消息例子 C 源文件SmGw_Client_APIExampleRecvmsg.h接收短消息例子頭文件 短消息網(wǎng)關(guān)客戶端開發(fā)包使用詳細(xì)說明第 4 頁 共 11 頁4 4接口函數(shù)功接口函數(shù)功能說明能說明4.1初始化初始化 API 函數(shù)函數(shù)函數(shù)名：函數(shù)名：InitSMGPAPI();功能：功能：讀取配置文件，完成初始化的工作。1系統(tǒng)資源的初始化：包括線程和線程同步所涉及的系統(tǒng)資源的創(chuàng)建和設(shè)置；定時(shí)資源的設(shè)置；通信消息機(jī)制的設(shè)置；內(nèi)存管理的初始化設(shè)置，隊(duì)列管理的設(shè)置。2通信參數(shù)初始化：包括服務(wù)器

7、端 IP 地址；客戶端器端IP 地址；通信端口號(hào)。3業(yè)務(wù)參數(shù)初始化：包括：短信分割參數(shù)；短信最大長度；發(fā)送短信自動(dòng)重試次數(shù)；發(fā)送請(qǐng)求超時(shí)時(shí)間等。4ICP 參數(shù)初始化：ICP 編號(hào)和密碼。返回：返回：0 成功 1 失敗4.2發(fā)送和接收發(fā)送和接收函數(shù)函數(shù)4.2.1發(fā)送發(fā)送 1 條短信條短信函數(shù)名：函數(shù)名：SMGPSendSingle()功能：功能：向短信網(wǎng)關(guān)發(fā)送1 條短信到1 個(gè)話機(jī)用戶。短信長度可以大于160 ，API 能夠自動(dòng)分割短信。在發(fā)送過程中，如果因?yàn)橥ㄐ旁驅(qū)е掳l(fā)送失敗，API 能夠自動(dòng)重新發(fā)送。返回：返回：0 成功 1 失敗4.2.2群發(fā)短信群發(fā)短信函數(shù)名：函數(shù)名：SMGPSendB

8、atch()功能：功能：向短信網(wǎng)關(guān)發(fā)送1 條短信到多個(gè)手機(jī)用戶。短信長度可以大于160 ，API 能夠自動(dòng)分割短信。此函數(shù)使用文件傳遞短信內(nèi)容。在發(fā)送過程中如果因?yàn)橥ㄐ旁驅(qū)е掳l(fā)送失敗，API 能夠自動(dòng)重新發(fā)送。返回：返回：0 成功 1 失敗4.2.3獲取群發(fā)短獲取群發(fā)短信結(jié)果信結(jié)果函數(shù)名：函數(shù)名：GetSendBatchResp ()功能：功能：從文件里讀取群發(fā)的某一個(gè)短信的標(biāo)識(shí)、發(fā)送結(jié)果和發(fā)送號(hào)碼。返回：返回：0 成功 1 失敗4.2.4接收短信接收短信函數(shù)名：函數(shù)名：SMGPDeliver ()功能：功能：連接短信網(wǎng)關(guān)，等待接收屬于本ICP 的短信，需要輸入等待的最大延時(shí)，如果是0表示永

9、遠(yuǎn)等待。返回：返回：0 成功 1 失敗 短消息網(wǎng)關(guān)客戶端開發(fā)包使用詳細(xì)說明第 5 頁 共 11 頁4.2.5設(shè)置參數(shù)函設(shè)置參數(shù)函數(shù)數(shù)函數(shù)名：函數(shù)名：SMGPSetKey ()功能：功能：設(shè)置新的ICP密碼 返回：返回：0 成功 1 失敗4.3查詢和測(cè)試查詢和測(cè)試函數(shù)函數(shù)4.3.1檢查短信網(wǎng)檢查短信網(wǎng)關(guān)是否能夠關(guān)是否能夠提供服務(wù)提供服務(wù)函數(shù)名：函數(shù)名：SMGPActiveTest ()功能：功能：檢查短信網(wǎng)關(guān)是否能夠提供服務(wù)返回：返回：0 成功 1 失敗4.3.2查詢短消息查詢短消息信息信息函數(shù)名：函數(shù)名：SMGPQuery ()功能：功能：根據(jù)短消息服務(wù)ID號(hào)查詢短消息信息函數(shù)的原型請(qǐng)參閱文件

10、./ SmGw_Client_API /Include/amgpapi.h。返回：返回：0 成功 1 失敗5 5函數(shù)參數(shù)和函數(shù)參數(shù)和數(shù)據(jù)結(jié)構(gòu)說數(shù)據(jù)結(jié)構(gòu)說明明5.1初始化初始化 API 函數(shù)函數(shù)參數(shù)名參數(shù)名數(shù)據(jù)類型數(shù)據(jù)類型說明說明sINIFileconst char *初試化函數(shù)配置文件名，缺省值（輸入為空）是當(dāng)前目錄./smgpc.ini或者:./config/smgpc.ini例如：InitSMGPAPI（NULL） ；如果上述目錄沒有配置文件，請(qǐng)輸入完整的路徑名。例如：InitSMGPAPI(“E:SmGw_Client_APIconfig smgpc.ini”)；5.2發(fā)送一條短發(fā)送一條

11、短消息消息參數(shù)名參數(shù)名數(shù)據(jù)類型數(shù)據(jù)類型說明說明nNeedReplyInt是否返回狀態(tài)確認(rèn)報(bào)告 短消息網(wǎng)關(guān)客戶端開發(fā)包使用詳細(xì)說明第 6 頁 共 11 頁（0：不要求；1:要求）NEED_REPORT_YESNEED_REPORT_NOnMsgLevelInt信息級(jí)別（0:最低優(yōu)先級(jí) 1:正常 2:緊急 3:十分緊急）SUBMIT_PRIORITY_LOWESTSUBMIT_PRIORITY_NORMALSUBMIT_PRIORITY_ABOVE_NORMALSUBMIT_PRIORITY_HIGHESTsServiceIDChar(11)業(yè)務(wù)類型nMsgFormatInt信息格式MSG_FOR

12、MAT_ASCIIMSG_FORMAT_WRITE_CARDMSG_FORMAT_BINARYMSG_FORMAT_UCS2MSG_FORMAT_GBMSG_FORMAT_PASSWORDsFeeTypeChar(3)資費(fèi)類別FEE_FREEFEE_BY_ITEMFEE_BY_MONTHFEE_BY_MAXINUMsFeeCodeChar(7)資費(fèi)代碼（以分為單位）sFixedFeeChar(6)固定的費(fèi)用SValidTimeChar(18)存活有效時(shí)間，遵循 SMPP3.3 協(xié)議sAtTimeChar(18)定時(shí)發(fā)送時(shí)間，遵循 SMPP3.3 協(xié)議sChargeTermIDChar(22)計(jì)

13、費(fèi)號(hào)碼sDestTermIDChar(22)接收消息的目的號(hào)碼sReplyPathChar(22)用戶回復(fù)號(hào)碼nMsgLenInt短消息長度sMsgContentChar(x)短消息內(nèi)容sMsgIDChar(11)返回的短消息標(biāo)識(shí)nErrorCodeInt*返回的錯(cuò)誤代碼，請(qǐng)參見錯(cuò)誤代碼表nMsgTypeInt消息類型注意：藍(lán)色部分為注意：藍(lán)色部分為1.3 協(xié)議增加協(xié)議增加。5.3群發(fā)短消息群發(fā)短消息參數(shù)名參數(shù)名數(shù)據(jù)類型數(shù)據(jù)類型說明說明nNeedReplyInt是否返回狀態(tài)確認(rèn)報(bào)告（0：不要求；1:要求）NEED_REPORT_YESNEED_REPORT_NOnMsgLevelInt信息級(jí)別

14、（0:最低優(yōu)先級(jí) 1:正常 2:緊急 3:十分緊急）SUBMIT_PRIORITY_LOWESTSUBMIT_PRIORITY_NORMAL 短消息網(wǎng)關(guān)客戶端開發(fā)包使用詳細(xì)說明第 7 頁 共 11 頁SUBMIT_PRIORITY_ABOVE_NORMALSUBMIT_PRIORITY_HIGHESTsServiceIDChar(11)業(yè)務(wù)類型nMsgFormatInt信息格式MSG_FORMAT_ASCIIMSG_FORMAT_WRITE_CARDMSG_FORMAT_BINARYMSG_FORMAT_UCS2MSG_FORMAT_GBMSG_FORMAT_PASSWORDsFeeTypeC

15、har(3)資費(fèi)類別FEE_FREEFEE_BY_ITEMFEE_BY_MONTHFEE_BY_MAXINUMsFeeCodeChar(7)資費(fèi)代碼（以分為單位）sFixedFeeChar(6)固定的費(fèi)用sValidTimeChar(18)存活有效時(shí)間，遵循 SMPP3.3 協(xié)議sAtTimeChar(18)定時(shí)發(fā)送時(shí)間，遵循 SMPP3.3 協(xié)議sChargeTermIDChar(22)計(jì)費(fèi)號(hào)碼sDestTermIDFi leChar(100)保存接收消息目的號(hào)碼的文件sReplyPathChar(22)用戶回復(fù)號(hào)碼nMsgLenInt短消息長度如果為 0，表示 sMsgFile是文件名，消

16、息內(nèi)容由該文件獲得如果為非 0，表示 sMsgFile是短消息內(nèi)容sMsgFileChar(x)短消息內(nèi)容或者保存短消息內(nèi)容的文件名sMsgIDFileChar(11)保存的短消息標(biāo)識(shí)或者錯(cuò)誤碼的文件nMsgTypeInt消息類型注意：藍(lán)色部分為注意：藍(lán)色部分為1.3 協(xié)議增加協(xié)議增加。5.4獲取群發(fā)短獲取群發(fā)短信結(jié)果信結(jié)果參數(shù)名參數(shù)名數(shù)據(jù)類型數(shù)據(jù)類型說明說明sMsgIDFileChar(100)保存的短消息標(biāo)識(shí)或者錯(cuò)誤碼的文件nPosInt短信位置從0 開始PSendBatchRespSendBatchResp*用于保存結(jié)果的 SendBatchResp結(jié)構(gòu)指針參數(shù)名參數(shù)名數(shù)據(jù)類型數(shù)據(jù)類型說

17、明說明sMsgIDChar(10)短消息標(biāo)識(shí)nErrorCodeInt錯(cuò)誤碼sPhoneNoChar(22)發(fā)送的目的號(hào)碼5.5接收短信接收短信參數(shù)名參數(shù)名數(shù)據(jù)類型數(shù)據(jù)類型說明說明 短消息網(wǎng)關(guān)客戶端開發(fā)包使用詳細(xì)說明第 8 頁 共 11 頁nTimeoutInt輸入等待的最大延時(shí)，如果是 0 表示永遠(yuǎn)等待。單位為秒pDeliverRespDeliverResp*保存短信的DeliverResp 結(jié)構(gòu)指針參數(shù)名參數(shù)名數(shù)據(jù)類型數(shù)據(jù)類型說明說明sMsgIDChar(11)短消息標(biāo)識(shí)nMsgFormatInt信息格式MSG_FORMAT_ASCIIMSG_FORMAT_WRITE_CARDMSG_FO

18、RMAT_BINARYMSG_FORMAT_UCS2MSG_FORMAT_GBMSG_FORMAT_PASSWORDsRecvTimeChar(16)接收時(shí)間sSrcrmIDChar(22)發(fā)送消息的源終端號(hào)碼sDestTermIDChar(22)發(fā)送消息的目的號(hào)碼nIsReplyChar(22)是否為應(yīng)答消息（0:非應(yīng)答消息1:應(yīng)答消息）NEED_REPLY_YESNEED_REPLY_NOnMsgLenInt短消息長度sMsgContentChar(252)短消息內(nèi)容5.6設(shè)置參數(shù)函設(shè)置參數(shù)函數(shù)數(shù)參數(shù)名參數(shù)名數(shù)據(jù)類型數(shù)據(jù)類型說明說明sKeyChar(15)ICP 密碼6 6配置參數(shù)說配置參

19、數(shù)說明明名稱名稱說明IcpIdICP 編號(hào)IcpShareKeyICP 密碼WithPrevPage分割短信前置說明文字WithNextPage分割短信后置說明文字PageSpaceAsciiASCII短信的最大長度PageSpaceGB中文短信的最大長度PageSpaceBinary二進(jìn)制短信的最大長度WithPageIndex分割短信時(shí)是否附件頁號(hào)MaxPage最大分割頁數(shù)ClientIP短信網(wǎng)關(guān)客戶端主機(jī)的IP 地址ServerIP短信網(wǎng)關(guān)服務(wù)端主機(jī)的IP 地址ServerPort短信網(wǎng)關(guān)的端口號(hào) 短消息網(wǎng)關(guān)客戶端開發(fā)包使用詳細(xì)說明第 9 頁 共 11 頁SubmitRetry發(fā)送短消息

20、的自動(dòng)重試次數(shù)RequestTimeout發(fā)送請(qǐng)求的超時(shí)時(shí)間，單位為秒PermimentOrTemp長連接或者短連接方式1:長連接 0:短連接方式LogLevel日志文件等級(jí) 0:正式 1: 調(diào)試LinkTest是否進(jìn)行鏈路檢測(cè)，0:否；1:是ProtocalChng1.0 協(xié)議和 1.3 協(xié)議轉(zhuǎn)換，0：否；1：是SmgpAPISeqNum在同一臺(tái)機(jī)器上客戶端程序的運(yùn)行順序，如果只有一個(gè)程序，該值為 0；如果再運(yùn)行一個(gè)客戶端程序，該值為 1；如果還需要運(yùn)行一個(gè)客戶端程序，該值為2；以此類推，等等。7 7短信的自動(dòng)短信的自動(dòng)分割功能分割功能SMGPSendSingle 和SMGPSendBatc

21、h 提供自動(dòng)分割短信的功能，分割的效果由smgpc.ini 的配置控制。當(dāng)參數(shù)nMsgFormat 等于0/15 時(shí)，API 就提供分割短信功能。API 掃描短信的內(nèi)容，把短信分段，根據(jù)每一段的短信內(nèi)容設(shè)置nMsgFormat。如果某一段短信含有中文，就把那一段短信的發(fā)送格式設(shè)為15，取PageSpaceGB 為最大長度；如果不含中文，就把那一段短信的發(fā)送格式設(shè)為0，取PageSpaceAscii 為最大長度。這樣，可以充分利用短信的最大發(fā)送長度，減少分割數(shù)量。但是，如果WithPrevPage 或者PageSpaceGB 含有漢字，所有分割短信的發(fā)送格式都設(shè)為15。當(dāng)參數(shù)nMsgFormat

22、 等于4 時(shí)，API 根據(jù)PageSpaceBinary 配置分割短信。當(dāng)參數(shù)nMsgFormat 等于0 并且長度小于PageSpaceGB，API 掃描短信內(nèi)容是否含有中文。如果發(fā)現(xiàn)中文，就自動(dòng)把發(fā)送格式變?yōu)?5。8 8編譯說明編譯說明8.1UINX 平平臺(tái)臺(tái)安裝編譯程序gcc或者cc。執(zhí)行命令 “make clean all”makefile文件的請(qǐng)參閱例子程序。 C編譯器包含頭文件smgpapi.h；C+編譯器包含頭文件smgpapi.hpp。注意：SMGP API 需要使用pthread 庫，在Solaris 和Linux 平臺(tái)編譯時(shí)需要加入-lpthread，在Free BSD 編譯時(shí)需要加入-pthread。 8.2WINDOWS 平臺(tái)平臺(tái)安裝VC 5.0 或6.0，在編譯環(huán)境的項(xiàng)目設(shè)置中的連接庫中增加SmGw_Client_API.lib：網(wǎng)關(guān)客戶端開發(fā)包和Ws2_