短信猫二次开发DLL接口说明-new.doc

短信猫二次开发包DLL接口说明版本说明：3.91版可以修改原来版本在某些情况下没有删除信息的错误，修改接收函数，当用户没有读取信息的情况下，不删除SIM卡上的信息。3.90版可以设置发送短信的有效期fnSetValPeriod;可以识别多条拆分的短信，在短信末尾添加: (第n条，共m条)标识;对没有被取走的短信，不会从SIM卡中删除掉，避免信息丢失。3.89版增加来电号码接收功能和自动挂断功能（fnSetPortRingLimit）3.88版修改了兼容性的问题3.86版修改了3.85版接收重复信息和报告的错误3.85版增加了 WaveCom模块短信猫状态报告的支持3.83版增加了拨号功能参见后面的 （第七节 拨号说明）3.81版添加fnSetNationMode 函数，可以设置成国际模式，发送港、澳等号码3.79版更正到达时间，修改USB口猫电脑兼容性问题.3.78版延长信息到达的有效期.3.76版支持模块版8口猫，修改状态报告没有接收号码的错误3.75版支持Windows下Java接口3.73版修改了纯西文接收时，有时末尾出现符号的问题。3.72版修改了信息状态报告返回的错误。3.71版修改了特殊字符的支持、增强了稳定性、修改了信息状态报告返回的错误。3.70版添加新函数,增加线程发送模式. fnSetThreadMode3.69版修正了fnSetDelayTime函数的调用错误3.68版支持最大256个端口，修正了fnWapPushCvt函数的返回错误3.66版支持到达报告功能，支持带电换卡功能，修改对某些信息长度判断错误的问题。3.65版修改了有些电脑检测不到短信猫的问题3.63版添加了两个函数fnSetDelayTime 和 fnWapPushCvt3.62版支持64个发送端口3.61版支持工业级短信猫，需要将类型设置成单口3.58版修改了对8口猫的支持错误, 支持纯西文发送到160个字节.3.56版加强了发送信息的稳定性.3.55版增加发送PUSH短信的功能，在fnSendMsg函数中添加了发送类型参数，读取返回信息函数也作了响应的修改。目录 1、 概述2、 编程说明3、 API函数列表4、 Java接口说明5、 错误代码6、 例子说明一、 概述短信猫DLL接口提供API级的函数调用接口，接口完全底层调用，没有任何界面，适合于广大自主品牌的开发用户。函数接口简单，尽需几个简单的函数调用，就可以实现信息的发送和接收功能。调用结构图如下：用户程序VC,VB,Delphi,PB,CBuilder等DLL接口MonDem.DLL梦网短信猫2口、4口、8口目前MonDem.DLL只支持Windows平台。短信猫通过串行口（COM）和计算机相连，或者通过USB虚拟的串行口和计算机相连，我们这里编程都是对串行口进行的，有关串行口的信息可以在计算机系统属性中的设备列表中了解。与短信猫同时提供了一个加密狗，它负责实现加密功能，我们也为用户提供了加密狗的接口（详见后面函数列表），方便用户实现软件的加密工作。本文适合MonDem.DLL 版本3.55。二、 编程说明用户使用MonDem.DLL编程的基本流程如下：a) 加载MonDem.DLL并定位函数，方法要视具体的编程语言而定。b) 调用fnSetModemType函数，设置相应的短信猫类型c) 执行初始化函数fnInitModem,可以指定打开某个端口，或者指定端口编号为-1，表示打开所有可能打开的端口。d) 调用fnSendMsg函数进行信息提交，同样可以指定用某个端口发送，或者-1表示用所有可能的端口进行发送。e) 以查询方式调用fnReadMsgEx接收信息（可在定时器里调用），本函数也可以指定单独端口或所有端口。本函数可以接收SIM卡接收到的信息，也可以接收由fnSendMsg发送信息的发送结果。具体请看函数说明部分。f) 退出程序前调用fnCloseModem关闭端口。注：在发送之前可先用fnGetStatus函数得到端口状态，状态编号大于等于8，表示该端口设备连接正常，可以发送。三、 API函数列表1. 通讯部分l 短信猫类型设置long fnSetModemType(long ComNo,long modemType)参数: nComNo 0255 代表COM编号，modemType 短信猫类型0 - 1口短信猫，1 - 2口短信猫，2 - 4口短信猫，3 - 8短信猫口返回: 0 - 成功， -1类型错XXX -错误代码，参见代码表l 获取当前短信猫类型设置long fnGetModemType(long ComNo)参数: nComNo 0255 代表COM编号。返回 ：短信猫类型0 - 1口短信猫，1 - 2口短信猫，2 - 4口短信猫，3 - 8短信猫口XXX -错误代码，参见代码表l 初始化函数long fnInitModem (long nPortNo)参数: nPortNo 0255 代表端口号码， -1 表示所有端口返回: 0 - 成功XXX -错误代码，参见代码表l 提交发送函数long fnSendMsg (long nPortNo, char * szHeader, char * szMsg)参数: nPortNo 0255 代表端口号码，-1表示所有可能端口szHeader 目标手机号码+序列号+已发送次数+发送者ID+发送类型+报告类型 (共六项)例如： 138123456789,1,0,1388888888,0,1其中目标手机号码是毕添项目，其他可添可不添其中手机号码和序列号之间用逗号隔开，序列号由用户自己定义，用于唯一标识这条短信，当MonDem.DLL返回状态时，同时返回该序列号，这样便于用户区分是哪一条短信的返回状态。参见fnReadMsgEx。另外：序列号只是为了用户便于识别返回状态使用的，它不影响发送过程。已发次数代表该条短信已经发送的次数，在返回函数里，该次数将被累加1并返回。序列号为字符型，最长支持20位。发送者ID是一个11位的字符串，方便用户记录发送者帐号信息发送类型：0-普通信息，1-PUSH信息报告类型: 0-无信息达到报告，1-有信息达到报告szMsg 发送信息内容（当信息类型是PUSH信息时，填写16进制的字符串，如：C5B894231AE6F8，该字符串的格式内容由用户自己定义。） (应该在70个字符以内,包含标点符号,1个汉字算1个字符) 例如: 恭喜发财,测试成功! 长度为10 返回: 0255 提交成功,返回发送端口号，当用-1发送时返回为0 -1 - 发送缓冲区满 XXX -错误代码，参见代码表说明:提交成功并不代表发送成功，发送结果信息用fnReadMsgEx来读取 发送缓冲区中最多容纳500条记录,超过500提交失败,函数返回-1l 查询接收函数 long fnReadMsgEx (long nPortNo,char * szHeader,char * szReadMsg) 参数: nPortNo 0255 代表端口号码， -1 表示所有端口szHeader 包含: 信息类型，端口号，接收时间，手机号码,序列号,已发次数，提交端口，发送者ID，发送类型，发送序号十部分例如：0,5,2004-05-28 12:30:52,1382523xxxx,001,1,0, 1382523xxxx,0,105信息类别的说明: 0- 接收信息，1- 发送成功信息2- 发送失败3- 发送超时14- 发送超时25- 取消发送6- 信息到达报告7- 拨号结束8- 拨号超时9- 拨号成功10- 来电号码端口号码 5 代表第5个端口接收时间 2004-05-28 12:30:52手机号码: 1382523xxxx序列号:发送结果与提交信息时的序列号相同,接收信息为0已发次数:提交时传递的已发次数+1提交端口:仅在非接收信息中有效，代表用户调用fnSendMsg函数时指定的端口号码发送者ID:与fnSendMsg中的发送者ID对应，方便用户记录管理，当接收信息时，此项与手机号码相同。 发送类型：与fnSendMsg中的发送类型对应 发送序号: 对于发送成功的返回和信息报告有效，1255信息报告与发送成功的信息相对应。比如：发送成功返回 60，那么信息报告也返回60 通过手机号，时间和发送序号来确定发送记录与信息报告的关系。 szReadMsg 接收信息内容 返回: 0 - 接收成功 -1 - 无信息 XXX -错误代码，参见代码表注意：接收缓冲区中最多保留500条记录,多余部分将被丢弃,所以请您编程时一定要注意及时读取,以免信息丢失l 关闭函数long fnCloseModem (long nPortNo)参数: nPortNo 0255 代表端口号码， -1 表示所有端口返回: 0 - 成功XXX -错误代码，参见代码表l 得到软件最大支持端口号long fnGetPortMax()返回: 最大支持端口数目(0,1,2,3,4,8 等)l 取端口状态函数long fnGetStatus (long nPortNo)参数: nPortNo 0255 代表端口号码， -1 表示所有端口返回: 端口状态，大于等于8表示设备连接正常，可以接收和发送。 状态小于8，表示测试状态。小于等于1，可能连线没有接好或者电源 没有打开，注意复位短信猫。 -1 端口号指定错误或者是端口未打开l 取发送缓冲区条数long fnGetSndCount (long nPortNo)参数: nPortNo 0255 代表端口号码， -1 表示所有端口返回:发送缓冲区信息条数。 -1 端口号指定错误l 取接收缓冲区条数long fnGetRecCount (long nPortNo)参数: nPortNo 0255 代表端口号码， -1 表示所有端口返回:发送缓冲区信息条数。 -1 端口号指定错误l 清除发送缓冲区long fnClrSndBuf (long nPortNo)参数: nPortNo 0255 代表端口号码， -1 表示所有端口返回: 0-成功。 -1 端口号指定错误l 清除接收缓冲区long fnClrRecBuf (long nPortNo)参数: nPortNo 0255 代表端口号码， -1 表示所有端口返回: 0-成功。 -1 端口号指定错误l 设置接收功能long fnSetReceive (long nType)参数: nType, 0-关闭接收信息功能,1-开启接收信息功能返回: 0-成功。 -1错误注意: 缺省情况下,接收功能是开启的(但是需要软件狗的支持) 另外，关闭接收功能，如果短信卡中存储了太多的短信，而不读取， 可能会影响到信息的发送。所以建立不要使用此关闭功能。l 取消发送功能long fnCancelSend (long nCount)对用fnSendMsg函数提交到发送队列还没有发送出去的信息，可以选择取消发送，取消的信息会保存到接收队列，可以用fnReadMsgEx函数得到，被取消后得到的信息类别为5。参数: nCount, 想要取消发送的信息条数，取消的顺序是先进先出，但是正在发送的信息不能取消，0-表示取消所有发送队列。返回: 0-成功。 -1错误l 设置发送延时功能long fnSetDelayTime(long PortNo,long DelayTime)fnSetDelayTime函数用来设置每个端口发送延时, 当某个端口发送完一条信息后,将按照设置的 DelayTime 进行延时，单位是毫秒。参数:PortNo 端口号码，DelayTime 延时毫秒数。返回: 0-成功。 -1错误l 得到WapPush编码long fnWapPushCvt(char * szTitle,char *szUrl,char * szOutStr)对指定标题和URL进行编码，生成16进制编码字符串。改结果可以直接被fnSendMsg函数使用作为WapPush信息发送参数: szTitle 标题信息，szUrl wap网址,szOutStr 用来接收编码信息 ，调用前请确认为szOutStr准备足够的空间用来接收数据，建议使用500字节以上。返回: 0-成功。l 设置启用线程模式long fnSetThreadMode(long nMode)fnSetThreadMode函数用来设置DLL启用线程模式执行，不受消息限制的执行，可以适合以服务方式执行的程序的调用。参数: nMode 1 开启线程模式注意:一定在所有的fnInitModem函数调用之前调用这个才有效，否则可能造成程序混乱。返回: 0-成功。l 设置国际模式long fnSetNationalMode(long nMode)fnSetNationalMode函数用来设置采用国际模式发送。DLL缺省情况下为非国际模式。参数: nMode 1 开启国际模式，此时发送号码前需要加国别吗，如： 香港加：852 （如852912345678） 国内加：86 （如8613612345678） nMode 0 关闭国际模式（缺省）注意:一定在的fnSendmsg函数调用之前调用这个才有效，否则DLL采用缺省的模式(0-国内)发送。 在0模式下，才可以发送端口号码。返回: 0-成功。l 设置自动挂断功能long fnSetPortRingLimit(long PortNo,long nLimit)通过设置振铃限制次数，自动挂断来电。参数：PortNo 0255 代表端口号码， -1 表示所有端口nLimit 限制振铃次数，当来电达到设置的次数以后，系统自动挂断来电，如果设置为0(缺省设置)，则系统不会主动挂断来电。返回: 0-成功。 -1端口号错误l 设置短信发送有效期int fnSetValPeriod (int nPeriod)本函数用来设置短信发送的有效期限。参数: nPeriod：0 255， 缺省为255 0143 - nPeriod*5 分种，范围 5分钟到12小时 144167 - 12小时+(nPeriod-143)*30分钟 168196 - (nPeriod-167)*1天 197255 - (nPeriod-196)*1周 2. 加密部分（这部分功能只对早期使用加密狗的用户）l 检测软件狗存在long fnDogCheck ()返回: 0-成功。其他-错误，请检测软件狗，并装好驱动程序。l 读狗序列号long fnDogSerial ()返回:非0-序列号。0-错误，请检测软件狗，并装好驱动程序。l 读取软件狗信息long fnDogRead (long bufLen,char * szBuf)参数：bufLen- 接收缓冲区的长度。最大值为65 szBuf- 接收缓冲区返回: 0-成功。读取到的信息放在szBuf中其他-错误，请检测软件狗，并装好驱动程序。fnDogRead会在szBuf的末尾加结束符0，所以如果需要读取n位长度，则要准备n+1位长度的缓冲区，同时bufLen也要设成n+1 l 写软件狗信息long fnDogWrite (long bufLen,char * szBuf)参数：bufLen- (szBuf中写入数据的长度。最大值为64) 此项未用。 szBuf- 存放要写入的信息，注意这里的信息是16进制字符形式的如：1234567890ABCDEFszBuf中信息的最大长度为64返回: 0-成功。将szBuf中的信息成功写入软件狗中其他-错误，请检测软件狗，并装好驱动程序。四、 Java接口说明本动态库为Windows系统提供Java接口函数如下public native int SetModemType(int ComNo,int ModemType);public native int GetModemType(int ComNo);public native int InitModem (int PortNo);public native int SendMsg (int PortNo, String strHeader, String strMsg);public native StringReadMsgEx (int PortNo);public native int CloseModem (int PortNo);public native int GetPortMax();public native int GetStatus (int PortNo);public native int GetSndCount (int PortNo);public native int GetRecCount (int PortNo);public native int ClrSndBuf (int PortNo);public native int ClrRecBuf (int PortNo);public native int SetReceive (int Type);public native int CancelSend (int Count);public native int SetDelayTime(int PortNo,int DelayTime);public native StringWapPushCvt(String strTitle,String strUrl);public native int SetThreadMode(int Mode);public native int SetNationalMode(int Mode);public nati