短讯接口API说明.docx

短讯接口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

意义：

等待时间，