短讯接口API说明.doc_第1页
短讯接口API说明.doc_第2页
短讯接口API说明.doc_第3页
短讯接口API说明.doc_第4页
短讯接口API说明.doc_第5页
已阅读5页,还剩14页未读 继续免费阅读

下载本文档

版权说明:本文档由用户提供并上传,收益归属内容提供方,若内容存在侵权,请进行举报或认领

文档简介

短讯接口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(人工台、自动台、维测台等)可以直接和短消息中心按照SMPP或内部协议通讯,实现规范规定的有关服务。ESMEs和SMSC之间的通讯直接通过内部或SMPP协议,是十分烦琐,而且有许多工作是公共的,所以在M900 INtess-SMAX II系统中提供了一些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动态连接库必须在系统能够找到的目录下。 【函数原型】BOOL WINAPI IFInitInterface(DWORD dwCodeProtocol, DWORD dwDriverProtocol, LPCTSTR pDriverParam); 【参数说明】dwCodeProtocol 类型:DWORD说明:和短讯中心连接的协议类型取值意义1内部协议(保留)2网关协议(保留)3SMEI协议dwDriverProtocol 类型:DWORD说明:和短讯中心连接的网络协议取值意义1TCP/IP协议2COM协议(保留)3X25协议(保留)PDriverParam类型;LPCTSTR说明:网络协议参数。字符串,参数之间以空格隔开。例如:TCP/IP协议的参数为“IP地址 端口号 超时时间”(如“129.9.123.8 5016 5000”) 【返回值】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.8 7000 5000 ); 【参考函数】IFExitInterface2. IFExitInterface 【函数功能】退出接口,应用程序在退出程序时必须调用此函数。 【预置条件】加载了动态连接库。 【函数原型】BOOL WINAPI IFExitInterface(); 【返回值】FALSE表示失败,TRUE表示成功 【函数说明】此函数用于退出接口时,删除接口,释放某些接口分配的系统资源。此函数只能在应用程序退出系统时调用,调用后接口以不完整,即使再次调用IFInitInterface后,接口也已不可再用,必须重新加载用户程序,重新加载SMEIDLL.DLL,再初始化接口。注意,在退出用户应用程序前,必须调用IFExitInterface函数。否则在Windows 95或者98下,卸载SMEIDLL.DLL时,会出现线程退不干净的现象。在Windows NT下,由于调度机制的完善,即使不调用IFExitInterface,SMEIDLL.DLL也可正常卸载,不会出现线程退不干净的现象。 【参考函数】IFInitInterface();2.2 短讯业务函数1. Login_R 【函数功能】用户向短讯中心注册登录。短讯中心对用户数据进行校验,如果合法,则登记该用户为合法用户,此后用户即可使用其他短讯业务函数。如果此函数调用不成功,则短讯中心不会处理用户其他有关短讯业务的命令。 【预置条件】成功调用IFInitInterface函数。 【函数原型】BOOL WINAPI Login_R(LPCTSTR SystemID, LPCTSTR Password); 【参数说明】SystemID类型:LPCTSTR,最大长度为15个字符意义:在短讯中心注册的接口名。Password类型: LPCTSTR,最大长度为8个字符意义;接口密码。 【返回值】FALSE表示失败, TRUE表示成功。 【函数说明】Login_R函数用于用户接口向短讯中心登录。用户必须在初始化接口,即成功调用IFInitInterface函数后,调用此函数向短讯中心注册。只有成功注册以后,才能跟短讯中心建立正常的协议联系,如果注册不成功,则短讯中心对于接口的其他有关业务的命令是不会处理的。参数SystemID是在SMSC登记的接口名。参数Password是接口的密码。如果SMSC没有该接口,或者密码不正确,或者该接口已经被使用等原因,都会造成登录不成功。如果登录成功后,接口会保存最后一次登录的数据,当链路出现故障后,重新初始化接口后,会自动登录到SMSC。只有调用Logout后,接口才会废弃登录数据。 【调用举例】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不在处理除登录外的其他协议。此外调用此函数后,接口会将上次登录的接口数据,保存在接口中的接口名和密码丢弃。 【参考函数】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 char 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未知,当用户或网络不含关于编码方案的较早信息1国际号码,2国内号码,不能包含地区和退出数字3网络特殊号码4用户号码5字符数字6缩写号码7保留OrgNPI类型:unsigned char意义:源地址编码方案取值意义0未知,当TON=5时,NPI=01ISDN或电话号码编码方案(E164/E163),对于任意实体SC,MSC或MS,都有效2保留3数据编码方案(X121)4电报编码方案5-7保留8国内编码方案9私有编码方案10ERMES编码方案(ETSI DE/PS 3 01-3)11-15保留OrgAddr类型:LPCTSTR 最大长度为20个ASC字符意义:源地址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类型:unsigned char意义:消息索引,保留,设置为0。DCS类型:unsigned char意义:数据编码方案取值意义0缺省编码方案(7位)4英文编码方案(不被手机支持)8UCS2编码方案其他保留PID类型:unsigned char意义:协议类型,缺省为0。Schedule类型:LPCTSTR 长度为19个ASC字符的字符串意义:定时时间注意:时间格式必须为“yyyy/mm/dd hh:mm:ss”。Expire类型:LPCTSTR 长度为19个ASC字符的字符串意义:超时时间注意:时间格式必须为“yyyy/mm/dd hh:mm:ss”。Default_ID类型:unsigned long意义:缺省短消息的信息码注意:国标定义的缺省短消息的个数为100条。UDHI类型:unsigned char意义:用于长短消息,表示UserData是否是结构取值意义0UD是正常字符串1UD是结构UDLen类型:unsigned long意义:表示UserData的长度,UDLen要注意的事项如下,如果对于UDHI设置为1的短消息,则此项表示UserData的字符个数(字符个数和字节个数不同,对于7比特编码格式,字符是7比特的,字节是8比特的。其他编码方式则字符的大小和字节的大小相同)UserData类型;LPCTSTR意义:用户信息,短消息正文。对于正常短消息,该字段的最大长度和编码方式有关,对于7比特编码方式(缺省的编码方式)为160个字符的ASC字符串,如果为8比特编码方式则为140个8比特字节流,如果为UCS2编码方式,则为70个字符的16比特字符串。此外对于UDHI设置为1的短消息,表示此字段已经经过编码,所以不论是什么编码方式,此字段的最大长度为140字节。输出参数:SM_ID类型:unsigned long*意义:返回短消息IDFCS类型:unsigned char*意义:返回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端失败原因。详细说明参见有关协议。如果该函数执行的不成功,函数的返回值中定义了详细的出错原因,具体可参见返回值部分的定义。 【调用举例】unsigned 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, 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。 【预置条件】成功调用IFInitInterface成功调用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类型:unsigned long意义:短消息IDOrgTON类型:unsigned char意义:源地址号码类型OrgNPI类型:unsigned char意义:源地址编码方案OrgAddr类型:LPTSTR 最大长度为20的字符串(不包括0字符)。意义:源地址 输出参数:DestTON类型:unsigned char*意义:返回目标地址号码类型 DestNPI类型:unsigned char*意义:返回目标地址编码方案DestAddr 类型:LPTSTR 返回最大长度为20的字符串(不包括0字符)。 意义:目标地址Final_Data类型:LPTSTR 返回长度为19的字符串(不包括0字符)。 意义:如果短消息生存期已结束,则是最后发送时间 ;如果短消息还处在等待状态,则是查询时间。SM_Status类型:unsigned char*意义:返回短消息的状态取值 意义0等待发送1发送成功2发送失败3上次提交失败,等待再次下发4定时时间未到,等待发送5正在发送6手机不可寻址,等待发送Error_Code类型:unsigned char*意义:返回错误代码,0表示 正确,非0表示 出错。 【返回值】函数返回值定义参见附录。 【调用举例】unsigned long SM_ID = SubmitSm(.);unsigned 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_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 DestAddr);【参数说明】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意义:等待时间,单位毫秒。 【返回值】函数返回值定义参见附录。 【函数说明】该函数用于查询有无下发到接口的短消息。在等待时间内如果有消息,则返回0。如果没有,则返回非0。7. GetDeliverSMEx 【函数功能】读取下发的短讯内容 【预置条件】成功调用IFInitInterface成功调用Login_R 【函数原型】int WINAPI GetDeliverSMEx(ULONG* sm_ID, unsigned char* DestTON, unsigned char* DestNPI, char* DestAddr, unsigned char* OrgTON, unsigned char* OrgNPI, char* OrgAddr, unsigned char* PRI, unsigned char* RP, unsigned char* UDHI, unsigned char* PID, unsigned char* DCS, char* TimeStamp, unsigned long * UDLen, char* UserData); 【参数说明】Sm_ID类型:ULONG*意义:返回短消息的IDDestTON类型:unsigned char*意义:返回目标地址号码类型DestNPI类型:unsigned char*意义;返回目标地址编码方案DestAddr类型:char* 返回最大长度为20的字符串(不包括0字符)。意义:目标地址OrgTON类型:unsigned char*说明:返回源地址号码类型OrgNPI类型:unsigned char*说明:返回源地址编码方案OrgAddr类型:char* 返回最大长度为20的字符串(不包括0字符)。说明:源地址PRI类型:unsigned char*说明:返回优先级RP类型:unsigned char*说明:返回回应路径UDHI类型:unsigned char*说明:返回头结构指示PID类型:unsigned char*说明:返回协议标志DCS类型:unsigned char*说明:返回编码方案TimeStamp类型:char* 返回最大长度为19的字符串(不包括0字符)。说明:提交时间UDLen类型:ULONG*意义:返回短消息的UDLUserData类型:char* 返回最大长度为140字节的字符串(不包括0字符)。说明:正文 【返回值】函数返回值定义参见附录。 【函数说明】该函数用于获得短消息中心下发到接口的Deliver消息 。Deliver消息的各项由参数给出。Deliver消息的回包由接口完成,在调用此函数成功后,接口自动回包。参数DestAddr和OrgAddr是接收返回地址的缓冲区,大小不应小于21字节。参数TimeStamp是接收提交时间的缓冲区,大小不应小于20字节。参数UserData是接收返回正文的缓冲区,大小不应小于141字节。参数DCS中指示的是发送到接口的数据的编码方案。参数UDHI返回UserData是否有头结构,为1表示UserData中的数据是编码后的数据。如果为0表示UserData是解码后的正常的ASC字符串或者多字节字符串或者8比特字符流。这是有DCS决定的。参数UDLen表示UserData的内容的字符长度。附录返回值表达含义0E_SUCCESS成功1E_NOT_INITIALIZEDINTERFACE没有初始化2E_ACK_COMMAND_ERROR回包命令字错误3E_NEWMEMORY_ERROR分配内存错误4E_OTHER_ERROR其他错误5E_SA_BUFF_TOOBIGSEND缓冲区太大6E_SA_POCKET_UNINTEGRATESEND包不完整7E_SA_PROTOCOL_ERROR协议错8E_SA_PROTOCOL_NO_SUPPORT协议不支持该格式9E_SA_CODE_OTHER_ERROR编码其他错误10E_SA_TIMEOUT传送超时11E_SA_NO_ENOUGH_BUFFER接收缓冲区不够大12E_SA_WAITFAILED等待失败13E_SA_SEND_FAILED发送失败14E_SUBMIT_ORGADDR_ERROR源地址错误15E_SUBMIT_DESTADDR_ERROR目的地址错误16E_SUBMIT_SCHEDULE_ERROR参数定时时间错误17E_SUBMIT_EXPIRE_ERROR参数超时时间错误18E_SUBMIT_DCS_ERROR参数DCS错误19E_SUBMIT_DCS_CONVERT_ERROR数据变换错误20E_SUBMIT_UDHI_ERROR参数UDHI错误21E_SUBMIT_UD_ERROR用户数据错误22E_SUBMIT_OVER_MO超过最大提交数23E_SUBMIT_OVER_MT超过最大下发数24E_SUBMIT_INVALID_USER无效用户,或者用户无权25E_SUBMIT_INVALID_DATA_FORMAT无效数据格式26E_SUBMIT_ADDR_ERROR地址错误27E_SUBMIT_CREATE_MESSAGE_ERROR生成短讯错误28E_QUERYSMSTATUS_SM_NOT_EXIST短讯不存在29E_QUERYSMSTATUS_SM_OTHER_ERR查询其他错误30E_QUERYSMSTATUS_ADDR_ERROR地址错误31E_QUERYSMDETAIL_SM_DETAILS_ZERO查询不到此32E_QUERYSMDETAIL_SM_DETAILS_FAIL查询失败33E_QUERYSMDETAIL_CONVERT_ERROR用户数据编码出错34E_QUERYSMDETAIL_LEN_ERRORLEN参数出错35E_QUERYSMDETAIL_SM_ADDR_ERROR地址错误36E_CANCELSM_ACK_STATUS_ERROR回包的STATUS指示出错37E_REPLACESM_

温馨提示

  • 1. 本站所有资源如无特殊说明,都需要本地电脑安装OFFICE2007和PDF阅读器。图纸软件为CAD,CAXA,PROE,UG,SolidWorks等.压缩文件请下载最新的WinRAR软件解压。
  • 2. 本站的文档不包含任何第三方提供的附件图纸等,如果需要附件,请联系上传者。文件的所有权益归上传用户所有。
  • 3. 本站RAR压缩包中若带图纸,网页内容里面会有图纸预览,若没有图纸预览就没有图纸。
  • 4. 未经权益所有人同意不得将文件中的内容挪作商业或盈利用途。
  • 5. 人人文库网仅提供信息存储空间,仅对用户上传内容的表现方式做保护处理,对用户上传分享的文档内容本身不做任何修改或编辑,并不能对任何下载内容负责。
  • 6. 下载文件中如有侵权或不适当内容,请与我们联系,我们立即纠正。
  • 7. 本站不保证下载资源的准确性、安全性和完整性, 同时也不承担用户因使用这些下载资源对自己和他人造成任何形式的伤害或损失。

评论

0/150

提交评论