短讯接口API说明.docx
- 文档编号:4561754
- 上传时间:2023-05-07
- 格式:DOCX
- 页数:27
- 大小:31.49KB
短讯接口API说明.docx
《短讯接口API说明.docx》由会员分享,可在线阅读,更多相关《短讯接口API说明.docx(27页珍藏版)》请在冰点文库上搜索。
短讯接口API说明
短讯接口API说明
第一章概述
短消息中心(SMC)和手机(MS)之间的联系,通过PLMN网,按照有关协议进行联系。
而扩展短消息实体(ESME)和短消息中心之间的联系,ETSI规范中另有相关规定,GSM03.39SMPP协议等。
ESME和SMSC之间通讯协议一般是TCPIP协议,上层协议可以是SMPP或者其他扩展协议。
华为公司的M900INtess-SMAXII系统提供的SMPP协议,对GSM03.39SMPP协议中的某些局限进行功能上的扩展,支持SMPP协议定义的所有功能。
另外M900INtess-SMAXII还提供了一套内部协议。
扩展短消息实体ESMEs(人工台、自动台、维测台等)可以直接和短消息中心按照SMPP或内部协议通讯,实现规范规定的有关服务。
ESMEs和SMSC之间的通讯直接通过内部或SMPP协议,是十分烦琐,而且有许多工作是公共的,所以在M900INtess-SMAXII系统中提供了一些API函数,供扩展短消息实体直接使用,而不用ESMEs处理低层的TCPIP通信,和SMSC的握手等工作。
通过这些API函数,将SMPP协议或内部协议以API函数的形式提供给ESMEs使用。
ESME,用户接口(SMEIDLL),SMSC之间的关系图如下:
通过该接口可以用SMPP协议的格式和其他支持SMPP协议的SMSC进行通讯。
用户接口具有的功能有:
1.低层链路出现故障时,重连链路,提示上层。
2.和SMSC的定时握手。
3.提供实现SMPP和内部协议中定义的相关协议的API函数。
第二章函数说明
短讯接口API可分为以下几类:
(1)初始化与退出函数
(2)短讯业务函数
2.1初始化与退出函数
1.IFInitInterface
【函数功能】
初始化接口,和短讯中心建立连接,应用程序必须首先调用本函数。
【预置条件】
smeidll.dll动态连接库必须在系统能够找到的目录下。
【函数原型】
BOOLWINAPIIFInitInterface(DWORDdwCodeProtocol,DWORDdwDriverProtocol,LPCTSTRpDriverParam);
【参数说明】
dwCodeProtocol类型:
DWORD
说明:
和短讯中心连接的协议类型
取值意义
1内部协议(保留)
2网关协议(保留)
3SMEI协议
dwDriverProtocol类型:
DWORD
说明:
和短讯中心连接的网络协议
取值意义
1TCP/IP协议
2COM协议(保留)
3X25协议(保留)
PDriverParam类型;LPCTSTR
说明:
网络协议参数。
字符串,参数之间以空格隔开。
例如:
TCP/IP协议的参数为“IP地址端口号超时时间”
(如“129.9.123.850165000”)
【返回值】
FALSE表示失败,TRUE表示成功。
【函数说明】
IFInitInterface用于初始化用户接口,定义接口的协议和使用的网络协议。
使用该接口时,必须首先调用IFInitInterface,然后才能调用其他函数。
当低层链路出现故障后,如果用户没有注册出错处理函数,接口会调用缺省的出错处理函数,杀掉现在的接口,重新连接,建立新接口。
如果用户注册了出错处理函数,接口调用用户的回调函数,此时,接口已破坏,用户必须再次调用此函数,重新初始化接口,然后才能成功调用其他函数。
此函数在调用时,会杀掉当前的接口,不管当前接口是否出错。
如果当前接口已经登录到SMSC,则重新初始化后,会自动调用Login函数,以上次登录的数据自动登录,当调用Logout函数后,上次登录的数据才会丢弃,无效。
dwCodeProtocol定义接口的编码协议,即ESME和SMSC之间的接口协议,取值有内部协议、SMPP协议、网关协议等。
其中网关协议是网关和SMSC之间的协议,目前接口不提供。
dwDriverProtocol定义网络通讯协议,其中COM协议,X25协议,此版本保留,尚未提供。
pDriverParam定义网络协议的连接参数,对于不同的网络协议,参数不同。
如果选择的协议是TCP/IP协议,则此参数应是按SMSC的IP地址,dwCodeProtocol定义的协议的端口号,连接超时时间顺序的字符串。
其中端口号根据协议、厂家的不同有不同的值,
例如:
华为的短消息中心,SMEI协议的端口号是5016。
【调用举例】
IFInitInterface(1,1,"129.9.123.870005000");
【参考函数】
IFExitInterface
2.IFExitInterface
【函数功能】
退出接口,应用程序在退出程序时必须调用此函数。
【预置条件】
加载了动态连接库。
【函数原型】
BOOLWINAPIIFExitInterface();
【返回值】
FALSE表示失败,TRUE表示成功
【函数说明】
此函数用于退出接口时,删除接口,释放某些接口分配的系统资源。
此函数只能在应用程序退出系统时调用,调用后接口以不完整,即使再次调用IFInitInterface后,接口也已不可再用,必须重新加载用户程序,重新加载SMEIDLL.DLL,再初始化接口。
注意,在退出用户应用程序前,必须调用IFExitInterface函数。
否则在Windows95或者98下,卸载SMEIDLL.DLL时,会出现线程退不干净的现象。
在WindowsNT下,由于调度机制的完善,即使不调用IFExitInterface,SMEIDLL.DLL也可正常卸载,不会出现线程退不干净的现象。
【参考函数】
IFInitInterface();
2.2短讯业务函数
1.Login_R
【函数功能】
用户向短讯中心注册登录。
短讯中心对用户数据进行校验,如果合法,则登记该用户为合法用户,此后用户即可使用其他短讯业务函数。
如果此函数调用不成功,则短讯中心不会处理用户其他有关短讯业务的命令。
【预置条件】
成功调用IFInitInterface函数。
【函数原型】
BOOLWINAPILogin_R(LPCTSTRSystemID,LPCTSTRPassword);
【参数说明】
SystemID类型:
LPCTSTR,最大长度为15个字符
意义:
在短讯中心注册的接口名。
Password类型:
LPCTSTR,最大长度为8个字符
意义;接口密码。
【返回值】
FALSE表示失败,TRUE表示成功。
【函数说明】
Login_R函数用于用户接口向短讯中心登录。
用户必须在初始化接口,即成功调用IFInitInterface函数后,调用此函数向短讯中心注册。
只有成功注册以后,才能跟短讯中心建立正常的协议联系,如果注册不成功,则短讯中心对于接口的其他有关业务的命令是不会处理的。
参数SystemID是在SMSC登记的接口名。
参数Password是接口的密码。
如果SMSC没有该接口,或者密码不正确,或者该接口已经被使用等原因,都会造成登录不成功。
如果登录成功后,接口会保存最后一次登录的数据,当链路出现故障后,重新初始化接口后,会自动登录到SMSC。
只有调用Logout后,接口才会废弃登录数据。
【调用举例】
If(IFInitInterface(1,1,"129.9.123.870005000"))
Login_R("newid","password");
【参考函数】
Logout
2.Logout
【函数功能】
用户向短讯中心注销接口。
【预置条件】
成功调用IFInitInterface。
成功调用Login_R。
【函数原型】
BOOLWINAPILogout();
【返回值】
FALSE表示失败,TRUE表示失败。
【函数说明】
此函数用于向SMSC注销接口。
注销后,SMSC不在处理除登录外的其他协议。
此外调用此函数后,接口会将上次登录的接口数据,保存在接口中的接口名和密码丢弃。
【参考函数】
Login_R
3.SubmitA
【函数功能】
向指定的地址发送短讯。
【预置条件】
成功调用IFInitInterface。
成功调用Login_R。
【函数原型】
intWINAPISubmitA(unsignedcharOrgTON,unsignedcharOrgNPI,LPCTSTROrgAddr,unsignedcharDestTON,unsignedcharDestNPI,LPCTSTRDestAddr,unsignedcharPRI,unsignedcharRD,unsignedcharRP,unsignedcharSRR,unsignedcharMR,unsignedcharDCS,unsignedcharPID,LPCTSTRSchedule,LPCTSTRExpire,unsignedlongDefault_ID,unsignedcharUDHI,unsignedlongUDLen,LPCTSTRUserData,unsignedlong*SM_ID,unsignedchar*FCS);
【参数说明】
输入参数:
OrgTON类型:
unsignedchar
说明:
源地址号码类型
取值意义
0未知,当用户或网络不含关于编码方案的较早信息
1国际号码,
2国内号码,不能包含地区和退出数字
3网络特殊号码
4用户号码
5字符数字
6缩写号码
7保留
OrgNPI类型:
unsignedchar
意义:
源地址编码方案
取值意义
0未知,当TON=5时,NPI=0
1ISDN或电话号码编码方案(E164/E163),对于任意实体SC,MSC或MS,都有效
2保留
3数据编码方案(X121)
4电报编码方案
5-7保留
8国内编码方案
9私有编码方案
10ERMES编码方案(ETSIDE/PS301-3)
11-15保留
OrgAddr类型:
LPCTSTR最大长度为20个ASC字符
意义:
源地址
DestTON类型:
unsignedchar
意义:
目标地址号码类型。
取值同OrgTON。
DestNPI类型:
unsignedchar
意义:
目标地址编码方案。
取值同OrgNPI。
DestAddr类型:
LPCTSTR最大长度为20个ASC字符
意义:
目标地址
PRI类型:
unsignedchar
意义:
SM优先级
取值意义
1优先级别
0缺省级别
RD类型:
unsignedchar
意义:
保留,设置为0。
RP类型:
unsignedchar
意义:
回应路径,保留,设置为0。
SRR类型:
unsignedchar
意义:
状态报告,保留,设置为0。
MR类型:
unsignedchar
意义:
消息索引,保留,设置为0。
DCS类型:
unsignedchar
意义:
数据编码方案
取值意义
0缺省编码方案(7位)
4英文编码方案(不被手机支持)
8UCS2编码方案
其他保留
PID类型:
unsignedchar
意义:
协议类型,缺省为0。
Schedule类型:
LPCTSTR长度为19个ASC字符的字符串
意义:
定时时间
注意:
时间格式必须为“yyyy/mm/ddhh:
mm:
ss”。
Expire类型:
LPCTSTR长度为19个ASC字符的字符串
意义:
超时时间
注意:
时间格式必须为“yyyy/mm/ddhh:
mm:
ss”。
Default_ID类型:
unsignedlong
意义:
缺省短消息的信息码
注意:
国标定义的缺省短消息的个数为100条。
UDHI类型:
unsignedchar
意义:
用于长短消息,表示UserData是否是结构
取值意义
0UD是正常字符串
1UD是结构
UDLen类型:
unsignedlong
意义:
表示UserData的长度,UDLen要注意的事项如下,如果对于UDHI设置为1的短消息,则此项表示UserData的字符个数(字符个数和字节个数不同,对于7比特编码格式,字符是7比特的,字节是8比特的。
其他编码方式则字符的大小和字节的大小相同)
UserData类型;LPCTSTR
意义:
用户信息,短消息正文。
对于正常短消息,该字段的最大长度和编码方式有关,对于7比特编码方式(缺省的编码方式)为160个字符的ASC字符串,如果为8比特编码方式则为140个8比特字节流,如果为UCS2编码方式,则为70个字符的16比特字符串。
此外对于UDHI设置为1的短消息,表示此字段已经经过编码,所以不论是什么编码方式,此字段的最大长度为140字节。
输出参数:
SM_ID类型:
unsignedlong*
意义:
返回短消息ID
FCS类型:
unsignedchar*
意义:
返回SC端失败原因
【返回值】
函数返回值定义参见附录。
【函数说明】
此函数封装了SUBMIT_SM协议,实现ESME向SMSC提交短消息。
将SUBMIT_SM协议的各项以参数的形式提供。
手机的地址由参数TON(OrgTON或DestTON),参数NPI(OrgNPI或DestNPI)和参数Addr(OrgAddr或DestAddr)确定。
如果地址是手机的号码,则NPI必须取1。
当NPI取1后,TON可取相应的值,对于国际编码,即手机号码加了“86”,NPI可取1;对于国内编码,不加“86”,NPI应取2。
对于参数编码方案DCS,建议短消息内容为英文ASC码,可取0。
对于中文短消息,DCS必须取8,表示UNICODE,否则会出现乱码。
参数Schedule用于定时短消息,即指定短消息发送的时间,当时间到达指定的时间后,SMSC才会下发。
参数Expire用于指定该提交短消息的生存期,即超时时间。
生存期是指当某条短消息在SMSC中存在的时间,当生存期结束后,短消息会被写入数据库中。
生存期结束有多种原因,例如:
短消息下发成功;短消息一直未下发成功,但超时时间已到;下发时遇永久性失败等。
SMSC的缺省时间是48小时,这个时间可设置。
用户也可以通过这个参数设置某个短消息的生存期,单位是小时。
参数Default_ID是缺省短消息的代码。
国标定义的缺省短消息的个数是100条。
对于不同的SMSC,缺省短消息的意义可能不同。
如果Default_ID为非零,则参数UDHI,UDLen,UserData被忽略。
参数UDHI表示参数UserData是否有头结构。
有头结构表示UserData字段是经过编码的内容;缺省情况下,此项应设成0。
参数UDLen表示UserData的长度,表示UserData的字符长度。
参数UserData是需要发送的短消息的内容,根据DCS和UDHI的设置不同可以是ASC字符串,多字节字符串,二进制字符流。
参数SM_ID返回成功提交短消息后,这条短消息的ID。
通过这个ID,可对这条短消息进行其他操作。
参数FCS返回SC端失败原因。
详细说明参见有关协议。
如果该函数执行的不成功,函数的返回值中定义了详细的出错原因,具体可参见返回值部分的定义。
【调用举例】
unsignedcharPRI=0,DCS=8,RD=0,RP=0,SRR=0,MR=0,PID=0;
unsignedlongdefault_id=0;
unsignedcharUDHI=0;
CstringUserData="你好,我已到达。
";
unsignedlongUDLen=UserData.GetLength();
unsignedlongSM_ID;
unsignedcharFCS;
intiRet=SubmitA(2,1,"1392700001",2,1,"1392700002",PRI,RD,RP,SRR,MR,DCS,PID,"1998/01/0108:
00:
00","1998/01/0120:
30:
00",default_id,0,UDLen,(LPCTSTR)UserData,&SM_ID,&FCS);
if(iRet!
=0)
AfxMessageBox("短讯发送失败");
4.QuerySMStatusA
【函数功能】
此函数用于查询一条短消息的状态和除短消息内容之外的其他参数。
查询是通过短消息ID,短消息ID是SMSC返回的短消息的一个句柄。
SubmitSM函数返回提交短消息的ID,通过函数QuerySMS也可以查到短消息ID。
【预置条件】
成功调用IFInitInterface
成功调用Login_R
【函数原型】
intWINAPIQuerySMStatusA(unsignedlongSM_ID,unsignedcharOrgTON,unsignedcharOrgNPI,LPCTSTROrgAddr,unsignedchar*DestTON,unsignedchar*DestNPI,LPTSTRDestAddr,LPTSTRFinal_date,unsignedchar*SM_Status,unsignedchar*Error_Code);
【参数说明】
输入参数:
SM_ID类型:
unsignedlong
意义:
短消息ID
OrgTON类型:
unsignedchar
意义:
源地址号码类型
OrgNPI类型:
unsignedchar
意义:
源地址编码方案
OrgAddr类型:
LPTSTR最大长度为20的字符串(不包括"\0"字符)。
意义:
源地址
输出参数:
DestTON类型:
unsignedchar*
意义:
返回目标地址号码类型
DestNPI类型:
unsignedchar*
意义:
返回目标地址编码方案
DestAddr类型:
LPTSTR返回最大长度为20的字符串(不包括"\0"字符)。
意义:
目标地址
Final_Data类型:
LPTSTR返回长度为19的字符串(不包括"\0"字符)。
意义:
如果短消息生存期已结束,则是最后发送时间;如果短消息还处在等待状态,则是查询时间。
SM_Status类型:
unsignedchar*
意义:
返回短消息的状态
取值意义
0等待发送
1发送成功
2发送失败
3上次提交失败,等待再次下发
4定时时间未到,等待发送
5正在发送
6手机不可寻址,等待发送
Error_Code类型:
unsignedchar*
意义:
返回错误代码,0表示正确,非0表示出错。
【返回值】
函数返回值定义参见附录。
【调用举例】
unsignedlongSM_ID=SubmitSm(......);
unsignedcharOrgTON,OrgNPI;
charOrgAddr[30];
unsignedcharDestTON,DestNPI;
charDestAddr[30];
charFinal_date[30];
unsignedcharSM_Status;
unsignedcharError_Code;
intiRet;
iRet=QuerySMStatus(SM_ID,&OrgTON,&OrgNPI,(LPCTSTR)OrgAddr,&DestTON,&DestNPI,(LPCTSTR)DestAddr,(LPCTSTR)Final_date,&SM_Status,&Error_Code);
if(iRet!
=0)
AfxMessageBox("error.");
5.CancelSMA
【函数功能】
删除尚未下发的短讯
【预置条件】
成功调用IFInitInterface
成功调用Login_R
【函数原型】
intWINAPICancelSMA(charcService_type,unsignedlongSM_ID,unsignedcharOrgTON,unsignedcharOrgNPI,LPCTSTROrgAddr,unsignedcharDestTON,unsignedcharDestNPI,LPCTSTRDestAddr);
【参数说明】
cService_type类型:
char
意义:
保留
SM_ID类型:
unsignedlong
意义;短消息ID
OrgTON类型:
unsignedchar
意义:
源地址号码类型
OrgNPI类型:
unsignedchar
意义:
源地址编码方案
OrgAddr类型:
LPTSTR最大长度为20的字符串(不包括"\0"字符)。
意义:
源地址
DestTON类型:
unsignedchar
意义:
目标地址号码类型
DestNPI类型:
unsignedchar
意义:
目标地址编码方案
DestAddr类型:
LPCTSTR最大长度为20的字符串(不包括"\0"字符)。
意义:
目标地址
【返回值】
函数返回值定义参见附录。
【函数说明】
此函数用于删除尚未发送成功,等待发送的短消息。
如果该短消息已经结束生命期则不能被删除,或者短消息的源地址和目的地址不正确。
6.HasDeliverMessage
【函数功能】
检查接口有无下发消息
【预置条件】
成功调用IFInitInterface
成功调用Login_R
【函数原型】
intWINAPIHasDeliverMessage(DWORDdwTimeOut);
【参数说明】
dwTimeOut类型:
DWORD
意义:
等待时间,
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 短讯 接口 API 说明