1、短讯接口API说明短讯接口API说明第一章 概 述短消息中心（SMC）和手机（MS）之间的联系，通过PLMN网，按照有关协议进行联系。而扩展短消息实体（ESME）和短消息中心之间的联系，ETSI规范中另有相关规定，GSM 03.39 SMPP协议等。ESME和SMSC之间通讯协议一般是TCPIP协议，上层协议可以是SMPP或者其他扩展协议。华为公司的M900 INtess-SMAX II系统提供的SMPP协议，对GSM 03.39 SMPP协议中的某些局限进行功能上的扩展，支持SMPP协议定义的所有功能。另外M900 INtess-SMAX II还提供了一套内部协议。扩展短消息实体ESMEs（
2、人工台、自动台、维测台等）可以直接和短消息中心按照SMPP或内部协议通讯，实现规范规定的有关服务。ESMEs和SMSC之间的通讯直接通过内部或SMPP协议，是十分烦琐，而且有许多工作是公共的，所以在M900 INtess-SMAX II系统中提供了一些API函数，供扩展短消息实体直接使用，而不用ESMEs处理低层的TCPIP通信，和SMSC的握手等工作。通过这些API函数，将SMPP协议或内部协议以API函数的形式提供给ESMEs使用。ESME，用户接口（SMEIDLL），SMSC之间的关系图如下：通过该接口可以用SMPP协议的格式和其他支持SMPP协议的SMSC进行通讯。用户接口具有的功能有
3、：1. 低层链路出现故障时，重连链路，提示上层。2. 和SMSC的定时握手。3. 提供实现SMPP和内部协议中定义的相关协议的API函数。第二章 函数说明短讯接口API可分为以下几类：（1）初始化与退出函数（2）短讯业务函数2.1 初始化与退出函数1. IFInitInterface 【函数功能】初始化接口，和短讯中心建立连接，应用程序必须首先调用本函数。 【预置条件】smeidll.dll动态连接库必须在系统能够找到的目录下。 【函数原型】BOOL WINAPI IFInitInterface(DWORD dwCodeProtocol, DWORD dwDriverProtocol, LPC
4、TSTR pDriverParam); 【参数说明】 dwCodeProtocol 类型：DWORD 说明：和短讯中心连接的协议类型 取值 意义 1 内部协议（保留） 2 网关协议（保留） 3 SMEI协议 dwDriverProtocol 类型：DWORD 说明：和短讯中心连接的网络协议 取值 意义 1 TCP/IP协议 2 COM协议（保留） 3 X25协议（保留） PDriverParam 类型；LPCTSTR 说明：网络协议参数。字符串，参数之间以空格隔开。 例如：TCP/IP协议的参数为“IP地址 端口号 超时时间” （如“129.9.123.8 5016 5000”） 【返回值】
5、FALSE表示失败，TRUE表示成功。 【函数说明】 IFInitInterface用于初始化用户接口，定义接口的协议和使用的网络协议。使用该接口时，必须首先调用IFInitInterface，然后才能调用其他函数。 当低层链路出现故障后，如果用户没有注册出错处理函数，接口会调用缺省的出错处理函数，杀掉现在的接口，重新连接，建立新接口。 如果用户注册了出错处理函数，接口调用用户的回调函数，此时，接口已破坏，用户必须再次调用此函数，重新初始化接口，然后才能成功调用其他函数。 此函数在调用时，会杀掉当前的接口，不管当前接口是否出错。如果当前接口已经登录到SMSC，则重新初始化后，会自动调用Logi
6、n函数，以上次登录的数据自动登录，当调用Logout函数后，上次登录的数据才会丢弃，无效。 dwCodeProtocol定义接口的编码协议，即ESME和SMSC之间的接口协议，取值有内部协议、SMPP协议、网关协议等。其中网关协议是网关和SMSC之间的协议，目前接口不提供。 dwDriverProtocol定义网络通讯协议，其中COM协议，X25协议，此版本保留，尚未提供。 pDriverParam定义网络协议的连接参数，对于不同的网络协议，参数不同。如果选择的协议是TCP/IP协议，则此参数应是按SMSC的IP地址，dwCodeProtocol定义的协议的端口号，连接超时时间顺序的字符串。其
7、中端口号根据协议、厂家的不同有不同的值，例如： 华为的短消息中心，SMEI协议的端口号是5016。 【调用举例】IFInitInterface(1, 1, 129.9.123.8 7000 5000 ); 【参考函数】 IFExitInterface2. IFExitInterface 【函数功能】退出接口，应用程序在退出程序时必须调用此函数。 【预置条件】加载了动态连接库。 【函数原型】BOOL WINAPI IFExitInterface(); 【返回值】FALSE表示失败，TRUE表示成功 【函数说明】 此函数用于退出接口时，删除接口，释放某些接口分配的系统资源。此函数只能在应用程序退出
8、系统时调用，调用后接口以不完整，即使再次调用IFInitInterface后，接口也已不可再用，必须重新加载用户程序，重新加载SMEIDLL.DLL，再初始化接口。 注意，在退出用户应用程序前，必须调用IFExitInterface函数。否则在Windows 95或者98下，卸载SMEIDLL.DLL时，会出现线程退不干净的现象。在Windows NT下，由于调度机制的完善，即使不调用IFExitInterface，SMEIDLL.DLL也可正常卸载，不会出现线程退不干净的现象。 【参考函数】IFInitInterface();2.2 短讯业务函数1. Login_R 【函数功能】用户向短讯中
9、心注册登录。短讯中心对用户数据进行校验，如果合法，则登记该用户为合法用户，此后用户即可使用其他短讯业务函数。如果此函数调用不成功，则短讯中心不会处理用户其他有关短讯业务的命令。 【预置条件】成功调用IFInitInterface函数。 【函数原型】BOOL WINAPI Login_R(LPCTSTR SystemID, LPCTSTR Password); 【参数说明】 SystemID 类型：LPCTSTR，最大长度为15个字符 意义：在短讯中心注册的接口名。 Password 类型： LPCTSTR，最大长度为8个字符 意义；接口密码。 【返回值】 FALSE表示失败， TRUE表示成功
10、。 【函数说明】 Login_R函数用于用户接口向短讯中心登录。用户必须在初始化接口，即成功调用IFInitInterface函数后，调用此函数向短讯中心注册。只有成功注册以后，才能跟短讯中心建立正常的协议联系，如果注册不成功，则短讯中心对于接口的其他有关业务的命令是不会处理的。 参数SystemID是在SMSC登记的接口名。参数Password是接口的密码。如果SMSC没有该接口，或者密码不正确，或者该接口已经被使用等原因，都会造成登录不成功。 如果登录成功后，接口会保存最后一次登录的数据，当链路出现故障后，重新初始化接口后，会自动登录到SMSC。只有调用Logout后，接口才会废弃登录数据
11、。 【调用举例】If (IFInitInterface(1, 1, 129.9.123.8 7000 5000) Login_R(newid, password); 【参考函数】Logout2. Logout 【函数功能】用户向短讯中心注销接口。 【预置条件】成功调用IFInitInterface。成功调用Login_R。 【函数原型】BOOL WINAPI Logout()； 【返回值】 FALSE表示失败， TRUE表示失败。 【函数说明】 此函数用于向SMSC注销接口。注销后，SMSC不在处理除登录外的其他协议。此外调用此函数后，接口会将上次登录的接口数据，保存在接口中的接口名和密码丢弃
12、。 【参考函数】Login_R3. SubmitA 【函数功能】向指定的地址发送短讯。 【预置条件】成功调用IFInitInterface。成功调用Login_R。 【函数原型】int WINAPI SubmitA(unsigned char OrgTON, unsigned char OrgNPI, LPCTSTR OrgAddr, unsigned char DestTON, unsigned char DestNPI, LPCTSTR DestAddr, unsigned char PRI, unsigned char RD, unsigned char RP, unsigned cha
13、r SRR, unsigned char MR, unsigned char DCS, unsigned char PID, LPCTSTR Schedule, LPCTSTR Expire, unsigned long Default_ID, unsigned char UDHI, unsigned long UDLen, LPCTSTR UserData, unsigned long* SM_ID, unsigned char* FCS); 【参数说明】输入参数：OrgTON 类型：unsigned char 说明：源地址号码类型 取值 意义 0 未知，当用户或网络不含关于编码方案的较早信
14、息 1 国际号码， 2 国内号码，不能包含地区和退出数字 3 网络特殊号码 4 用户号码 5 字符数字 6 缩写号码 7 保留OrgNPI 类型：unsigned char 意义：源地址编码方案 取值 意义 0 未知，当TON=5时，NPI=0 1 ISDN或电话号码编码方案（E164/E163）， 对于任意实体SC，MSC或MS，都有效 2 保留 3 数据编码方案（X121） 4 电报编码方案 5-7 保留 8 国内编码方案 9 私有编码方案 10 ERMES编码方案（ETSI DE/PS 3 01-3） 11-15 保留OrgAddr 类型：LPCTSTR 最大长度为20个ASC字符 意义
15、：源地址DestTON 类型：unsigned char 意义：目标地址号码类型。取值同OrgTON。DestNPI 类型：unsigned char 意义：目标地址编码方案。取值同OrgNPI。DestAddr 类型：LPCTSTR 最大长度为20个ASC字符 意义：目标地址PRI 类型：unsigned char 意义：SM优先级 取值 意义 1 优先级别 0 缺省级别RD 类型：unsigned char 意义：保留，设置为0。RP 类型：unsigned char 意义：回应路径，保留，设置为0。SRR 类型：unsigned char 意义：状态报告，保留，设置为0。MR 类型：un
16、signed char 意义：消息索引，保留，设置为0。DCS 类型：unsigned char 意义：数据编码方案 取值 意义 0 缺省编码方案(7位) 4 英文编码方案(不被手机支持) 8 UCS2编码方案 其他 保留PID 类型：unsigned char 意义：协议类型，缺省为0。Schedule 类型：LPCTSTR 长度为19个ASC字符的字符串 意义：定时时间 注意：时间格式必须为“yyyy/mm/dd hh:mm:ss”。Expire 类型：LPCTSTR 长度为19个ASC字符的字符串 意义：超时时间 注意：时间格式必须为“yyyy/mm/dd hh:mm:ss”。Defau
17、lt_ID 类型：unsigned long 意义：缺省短消息的信息码 注意：国标定义的缺省短消息的个数为100条。UDHI 类型：unsigned char 意义：用于长短消息，表示UserData是否是结构 取值 意义 0 UD是正常字符串 1 UD是结构UDLen 类型：unsigned long意义：表示UserData的长度，UDLen要注意的事项如下，如果对于UDHI设置为1的短消息，则此项表示UserData的字符个数（字符个数和字节个数不同，对于7比特编码格式，字符是7比特的，字节是8比特的。其他编码方式则字符的大小和字节的大小相同）UserData 类型；LPCTSTR意义：
18、用户信息，短消息正文。对于正常短消息，该字段的最大长度和编码方式有关，对于7比特编码方式（缺省的编码方式）为160个字符的ASC字符串，如果为8比特编码方式则为140个8比特字节流，如果为UCS2编码方式，则为70个字符的16比特字符串。此外对于UDHI设置为1的短消息，表示此字段已经经过编码，所以不论是什么编码方式，此字段的最大长度为140字节。输出参数：SM_ID 类型：unsigned long* 意义：返回短消息IDFCS 类型：unsigned char* 意义：返回SC端失败原因 【返回值】 函数返回值定义参见附录。 【函数说明】 此函数封装了SUBMIT_SM协议，实现ESME向
19、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用于定时短消息，即指定短消息发送的时间，当时间到达指
20、定的时间后，SMSC才会下发。 参数Expire用于指定该提交短消息的生存期，即超时时间。生存期是指当某条短消息在SMSC中存在的时间，当生存期结束后，短消息会被写入数据库中。生存期结束有多种原因，例如：短消息下发成功；短消息一直未下发成功，但超时时间已到；下发时遇永久性失败等。SMSC的缺省时间是48小时，这个时间可设置。用户也可以通过这个参数设置某个短消息的生存期，单位是小时。 参数Default_ID是缺省短消息的代码。国标定义的缺省短消息的个数是100条。对于不同的SMSC，缺省短消息的意义可能不同。如果Default_ID为非零，则参数UDHI，UDLen，UserData被忽略。
21、参数UDHI表示参数UserData是否有头结构。有头结构表示UserData字段是经过编码的内容；缺省情况下，此项应设成0。 参数UDLen表示UserData的长度，表示UserData的字符长度。 参数UserData是需要发送的短消息的内容，根据DCS和UDHI的设置不同可以是ASC字符串，多字节字符串，二进制字符流。 参数SM_ID返回成功提交短消息后，这条短消息的ID。通过这个ID，可对这条短消息进行其他操作。 参数FCS返回SC端失败原因。详细说明参见有关协议。 如果该函数执行的不成功，函数的返回值中定义了详细的出错原因，具体可参见返回值部分的定义。 【调用举例】 unsigne
22、d char PRI = 0, DCS = 8, RD = 0, RP = 0, SRR = 0, MR = 0, PID = 0; unsigned long default_id = 0; unsigned char UDHI = 0; Cstring UserData = 你好，我已到达。;unsigned long UDLen = UserData.GetLength(); unsigned long SM_ID; unsigned char FCS;int iRet = SubmitA(2, 1, 1392700001, 2, 1, 1392700002, PRI, RD, RP,
23、SRR, MR, DCS, PID, 1998/01/01 08:00:00, 1998/01/01 20:30:00, default_id, 0, UDLen, (LPCTSTR)UserData, &SM_ID, &FCS);if (iRet != 0) AfxMessageBox(短讯发送失败);4. QuerySMStatusA 【函数功能】 此函数用于查询一条短消息的状态和除短消息内容之外的其他参数。查询是通过短消息ID，短消息ID是SMSC返回的短消息的一个句柄。SubmitSM函数返回提交短消息的ID，通过函数QuerySMS也可以查到短消息ID。 【预置条件】成功调用IFIn
24、itInterface成功调用Login_R 【函数原型】int WINAPI QuerySMStatusA(unsigned long SM_ID, unsigned char OrgTON, unsigned char OrgNPI, LPCTSTR OrgAddr, unsigned char* DestTON, unsigned char* DestNPI, LPTSTR DestAddr, LPTSTR Final_date, unsigned char* SM_Status, unsigned char* Error_Code); 【参数说明】输入参数： SM_ID 类型：unsi
25、gned long 意义：短消息ID OrgTON 类型：unsigned char 意义：源地址号码类型 OrgNPI 类型：unsigned char 意义：源地址编码方案 OrgAddr 类型：LPTSTR 最大长度为20的字符串（不包括0字符）。 意义：源地址 输出参数： DestTON 类型：unsigned char* 意义：返回目标地址号码类型 DestNPI 类型：unsigned char* 意义：返回目标地址编码方案 DestAddr 类型：LPTSTR 返回最大长度为20的字符串（不包括0字符）。 意义：目标地址 Final_Data 类型：LPTSTR 返回长度为19的
26、字符串（不包括0字符）。 意义：如果短消息生存期已结束，则是最后发送时间 ；如果短消 息还处在等待状态，则是查询时间。 SM_Status 类型：unsigned char* 意义：返回短消息的状态 取值 意义 0 等待发送 1 发送成功 2 发送失败 3 上次提交失败，等待再次下发 4 定时时间未到，等待发送 5 正在发送 6 手机不可寻址，等待发送 Error_Code 类型：unsigned char* 意义：返回错误代码，0表示 正确，非0表示 出错。 【返回值】 函数返回值定义参见附录。 【调用举例】unsigned long SM_ID = SubmitSm(.);unsigned
27、 char OrgTON, OrgNPI;char OrgAddr30;unsigned char DestTON, DestNPI;char DestAddr30;char Final_date30;unsigned char SM_Status;unsigned char Error_Code;int iRet;iRet = QuerySMStatus(SM_ID, &OrgTON, &OrgNPI, (LPCTSTR)OrgAddr, &DestTON, &DestNPI,(LPCTSTR)DestAddr, (LPCTSTR)Final_date, &SM_Status, &Error
28、_Code);if (iRet != 0) AfxMessageBox(error.);5. CancelSMA 【函数功能】删除尚未下发的短讯 【预置条件】成功调用IFInitInterface成功调用Login_R 【函数原型】int WINAPI CancelSMA(char cService_type, unsigned long SM_ID, unsigned char OrgTON, unsigned char OrgNPI, LPCTSTR OrgAddr, unsigned char DestTON, unsigned char DestNPI, LPCTSTR DestAdd
29、r);【参数说明】cService_type 类型：char 意义：保留SM_ID 类型：unsigned long 意义；短消息IDOrgTON 类型：unsigned char 意义：源地址号码类型OrgNPI 类型：unsigned char 意义：源地址编码方案OrgAddr 类型：LPTSTR 最大长度为20的字符串（不包括0字符）。 意义：源地址 DestTON 类型：unsigned char 意义：目标地址号码类型DestNPI 类型：unsigned char 意义：目标地址编码方案DestAddr 类型：LPCTSTR 最大长度为20的字符串（不包括0字符）。 意义：目标地址 【返回值】函数返回值定义参见附录。 【函数说明】此函数用于删除尚未发送成功，等待发送的短消息。如果该短消息已经结束生命期则不能被删除，或者短消息的源地址和目的地址不正确。6. HasDeliverMessage 【函数功能】检查接口有无下发消息 【预置条件】成功调用IFInitInterface成功调用Login_R 【函数原型】int WINAPI HasDeliverMessage(DWORD dwTimeOut)； 【参数说明】dwTimeOut 类型：DWORD 意义：等待时间，
