短讯接口API说明Word文件下载.docx
《短讯接口API说明Word文件下载.docx》由会员分享，可在线阅读，更多相关《短讯接口API说明Word文件下载.docx（27页珍藏版）》请在冰点文库上搜索。
1内部协议（保留）
2网关协议（保留）
3SMEI协议
dwDriverProtocol类型：
和短讯中心连接的网络协议
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
向指定的地址发送短讯。
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类型：
意义：
源地址编码方案
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类型：
目标地址号码类型。
取值同OrgTON。
DestNPI类型：
目标地址编码方案。
取值同OrgNPI。
DestAddr类型：
目标地址
PRI类型：
SM优先级
1优先级别
0缺省级别
RD类型：
保留，设置为0。
RP类型：
回应路径，保留，设置为0。
SRR类型：
状态报告，保留，设置为0。
MR类型：
消息索引，保留，设置为0。
DCS类型：
数据编码方案
0缺省编码方案（7位）
4英文编码方案（不被手机支持）
8UCS2编码方案
其他保留
PID类型：
协议类型，缺省为0。
Schedule类型：
LPCTSTR长度为19个ASC字符的字符串
定时时间
注意：
时间格式必须为“yyyy/mm/ddhh:
mm:
ss”。
Expire类型：
超时时间
Default_ID类型：
unsignedlong
缺省短消息的信息码
国标定义的缺省短消息的个数为100条。
UDHI类型：
用于长短消息，表示UserData是否是结构
0UD是正常字符串
1UD是结构
UDLen类型：
意义：
表示UserData的长度，UDLen要注意的事项如下，如果对于UDHI设置为1的短消息，则此项表示UserData的字符个数（字符个数和字节个数不同，对于7比特编码格式，字符是7比特的，字节是8比特的。
其他编码方式则字符的大小和字节的大小相同）
UserData类型；
用户信息，短消息正文。
对于正常短消息，该字段的最大长度和编码方式有关，对于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:
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类型：
短消息ID
OrgTON类型：
OrgNPI类型：
OrgAddr类型：
LPTSTR最大长度为20的字符串（不包括"
\0"
字符）。
源地址
DestTON类型：
返回目标地址号码类型
DestNPI类型：
返回目标地址编码方案
DestAddr类型：
LPTSTR返回最大长度为20的字符串（不包括"
Final_Data类型：
LPTSTR返回长度为19的字符串（不包括"
如果短消息生存期已结束，则是最后发送时间；
如果短消息还处在等待状态，则是查询时间。
SM_Status类型：
返回短消息的状态
0等待发送
1发送成功
2发送失败
3上次提交失败，等待再次下发
4定时时间未到，等待发送
5正在发送
6手机不可寻址，等待发送
Error_Code类型：
返回错误代码，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）;
error."
5.CancelSMA
删除尚未下发的短讯
intWINAPICancelSMA（charcService_type,unsignedlongSM_ID,unsignedcharOrgTON,unsignedcharOrgNPI,LPCTSTROrgAddr,unsignedcharDestTON,unsignedcharDestNPI,LPCTSTRDestAddr）;
【参数说明】
cService_type类型：
char
保留
意义；
OrgNPI类型：
目标地址号码类型
目标地址编码方案
DestAddr类型：
LPCTSTR最大长度为20的字符串（不包括"
函数返回值定义参见附录。
此函数用于删除尚未发送成功，等待发送的短消息。
如果该短消息已经结束生命期则不能被删除，或者短消息的源地址和目的地址不正确。
6.HasDeliverMessage
检查接口有无下发消息
intWINAPIHasDeliverMessage（DWORDdwTimeOut）；
dwTimeOut类型：
等待时间，
升级会员 