江苏电信企信通_API接口说明(C#).docx

江苏电信企信通客户端API接口说明文档（C#）（V1.0）联创亚信科技(南京)有限公司2012年11月 江苏电信企信通API接口说明文档文档修改记录文档版本修改人修改时间修改内容V1.0陈萍2012-11-9新建目 录1概述41.1阅读对象41.2项目背景42环境准备42.1开发环境42.2使用该包说明42.3定义类43API接口定义53.1接口说明53.2接口描述54代码示例55常见问题56其他61 概述1.1 阅读对象本文档为DLL组件（FullTunnelControl.dll）的使用说明文档，为系统设计人员或程序开发人员应用该开发包进行二次开发而编写，主要服务对象为与该项目有关的项目管理人员、系统设计人员和系统开发人员。1.2 项目背景2 环境准备2.1 开发环境操作系统：不限。2.2 使用该包说明1) 使用组件需要先注册组件, 例如regsvr32 D:codesmsg_com_pFullTunnelControl.dll 2) 运行环境中，字符集编码为GBK。3) 使用该组件时需要在代码里添加下面几条语句即可在头文件中加入下列语句(路径根据具体进行修改)#import .FullTunnelControlFullTunnelControl.tlb#pragma comment(lib,.FullTunnelControl.lib)using namespace FULLTUNNELCONTROLLib;4) 使用该包提供的用户接口（类）进行开发。2.3 定义类3 API接口定义3.1 接口说明本组件包括以下几个应用接口，分别如下：接口名称类型功能描述StartAndManageConnect_User函数客户端建立连接接口函数StartRecv函数客户端接收报文信息的接口函数SendBusinessPkg函数客户端发送报文信息的接口函数（仅限普通用户）SendBusinessPkg_New函数客户端发送报文信息的接口函数（添加主接入号）SendBusinessPkgByParam函数客户端可以用于所有用户类型的客户端发送报文的接口函数CloseConnect函数客户端关闭连接的接口函数3.2 接口描述3.2.1 StartAndManageConnect_User接口 功能描述：调用 StartAndManageConnect_User(name, pwd, ip, port)函数;用于建立连接并发送认证包。(参见SendTest程序中CSendTestDlg:OnConnect()方法) ,如果认证成功后，会创建守护进程（即发送心跳包），维持连接不断开。 接口参数描述：StartAndManageConnect_User(name, pwd, ip, port)参数数据类型描述约定nameStringAPI用户名pwdStringAPI用户密码ipStringAPI公网接连IP地址01portIntAPI访问端口号900 用法示例 接口函数返回值0: S_OK连接认证成功 创建守护线程成功1: S_FALSE连接认证成功 创建守护线程失败102SEND_PAR_USER_ERROE-参数错误:没有输入用户名103SEND_PAR_CODE_ERROE-参数错误:没有输入用户密码104SEND_PAR_DESTCODE_ERROE-参数错误:没有输入目的号码 /105SEND_PAR_IP_ERROE-参数错误:输入的服务器地址不正确106SEND_PAR_PORT_ERROE-参数错误:输入的服务器端口不正确107SEND_PAR_CONTEXT_ERROE-参数错误:没有输入发送内容 /108SEND_PAR_SENDTYPE_ERROE-参数错误:输入发送类型不正确 /201SEND_WSAStartup_ERROE-windows启动socket错误202SEND_socket_ERROE-WINDOWS的socket()错误203SEND_gethostbyname_ERROE-域名解析错误204SEND_setsockopt_ERROE-设置选项错误205SEND_connect_ERROE-建立连接connect()错误206SEND_send_ERROE-发送send()错误,可能是由于连接失效207SEND_SOCKET_ERROR-发送send()返回SOCKET错误208SEND_recv_ERROR-接受recv()错误209SEND_TYPE_AUTH_REPLY_ERROR-认证请求的响应类型错误,响应类型不符合协议301服务器返回结果:-服务器系统错误 302服务器返回结果:-登录用户名错误303服务器返回结果:-登录密码错误304服务器返回结果:-连接数超过限制305服务器返回结果:-每秒发送条目数超过限制306服务器返回结果:-发送的目的号码受限制307服务器返回结果:-网络错误308服务器返回结果:-每月发送条目数超过限制309服务器返回结果:-客户端关闭连接310服务器返回结果:-短信网关关闭连接311服务器返回结果:-超时退出312服务器返回结果:-连接数据库错误313服务器返回结果:-连接短信网关错误314服务器返回结果:-非法内容315服务器返回结果:-非法时间316服务器返回结果:-服务器未定义317服务器返回结果:-服务器未定义318服务器返回结果:-服务器未定义319服务器返回结果:-服务器未定义320服务器返回结果:-服务器未定义3.2.2 StartRecv _User接口 功能描述：当认证通过后即可调用StartRecv_User(VARIANT callback)函数;此函数用户创建接收线程(用于接收认证响应包，业务响应包，回执包，上行短信包). (参见SendTest程序中CSendTestDlg:OnStartthread()方法)此处参数callback.pvRecord特殊。参数必须为void CallBackProc(BSTR BS_flag,BSTR BS_svalue1,BSTR BS_svalue2,BSTR BS_svalue3,BSTR BS_svalue4,BSTR BS_svalue5, BSTR BS_svalue6,BSTR BS_svalue7 ,BSTR BS_svalue8)从而用作回调函数。用户在CallBackProc中根据flag的值相应的取不同的字段从而可以分别得到业务响应包，回执包，上行短信包。 接口参数描述：StartRecv_User(VARIANT callback)其中callback为CallBackProc(BSTR BS_flag,BSTR BS_svalue1,BSTR BS_svalue2,BSTR BS_svalue3,BSTR BS_svalue4,BSTR BS_svalue5, BSTR BS_svalue6,BSTR BS_svalue7 ,BSTR BS_svalue8)作为回调函数参数数据类型描述约定BS_flagString标识包类型当flag=2 时，此时为认证响应包；当flag = 4时，此时为业务响应包；当flag = 5时，此时为上行短信包；当flag = 7时 此时为回执包BS_svalue1String包序号BS_svalue2Stringflag=4时，BS_ svalue2为业务响应包的MsgId;flag=5时，BS_svalue2为上行短信包的发送号码;flag=7时，BS_ svalue2为回执包的MsgId;BS_svalue3Stringflag=4时，BS_ svalue3为status，即业务响应包的状态值;flag=5时，BS_ svalue3为上行包接收号码flag=7时，BS_ svalue3为回执包里接收号码BS_svalue4Stringflag=5时，BS_ svalue4为上行包接收时间flag=7时，BS_ svalue4为回执包里发送号码BS_svalue5Stringflag=5时，BS_ svalue5为上行包短信内容flag=7时，BS_ svalue5为回执包里提交时间BS_svalue6Stringflag=7时，BS_ svalue6为回执包里下发时间BS_svalue7Stringflag=7时，BS_ svalue7为回执包里短信状态BS_svalue8Stringflag=7时，BS_ svalue8为回执包里错误代码 用法示例 接口函数返回值0:S_OK创建接收线程成功1: S_FALSE创建接收线程失败 响应包里的状态值状态码描述0成功1系统错误2帐号错误3密码错误4连接数超过限制5秒发送条目数限制6发送目的号码限制7网络原因8月发送条目数限制9客户端关闭连接10gw关闭连接11超时退出12连接数据库错误13连接网关错误14非法内容15非法时间16非法ip17向用户信息列表中加入用户失败18从数据库初始化用户信息失败19接入号码错误20验证网信账号失败21天翼号码错误22指定号码不在号码池 回执包中的状态值000 成功 DELIVRD001 用户不能通信 EXPIRED002 用户忙 EXPIRED003 终端无此部件号 UNDELIV004 非法用户 UNDELIV005 用户在黑名单内 UNDELIV006 系统错误 UNDELIV007 用户内存满 EXPIRED008 非信息终端 UNDELIV009 数据错误 UNDELIV010 数据丢失 UNDELIV999 未知错误 UNKNOWN3.2.3 SendBusinessPkg接口 功能描述：调用SendBusinessPkg函数;用于发送短信(参见SendTest程序中CSendTestDlg:OnSendmsg()方法) 接口参数描述：SendBusinessPkg(control_type,name,pwd,sc,dc,ip,port,content,sendtype,comid,NeedReceipt, VARIANT *pvSeqID,)参数数据类型描述约定control_typeString此时填send，表示发送短信nameString用户名pwdString用户密码scString发送号码dcString目的号码ipStringAPI公网接连IP地址01portStringAPI访问端口号9005contentString短信内容sendtypeString发送类型Sendtype=0，默认用用户信息表中的主号码作为发送号码Sendtype=1，默认用用户信息表中的号码池中随机取一个作为发送号码Sendtype=1，默认用自带的发送号码作为发送号码comidString企业IDNeedReceiptString标识是否需要回执0代表不需要回执，1代表需要回执pvSeqIDVARIANT用于返回包序号 用法示例 接口函数返回值1:SEND_OK发送成功102SEND_PAR_USER_ERROE-参数错误:没有输入用户名103SEND_PAR_CODE_ERROE-参数错误:没有输入用户密码104SEND_PAR_DESTCODE_ERROE-参数错误:没有输入目的号码105SEND_PAR_IP_ERROE-参数错误:输入的服务器地址不正确106SEND_PAR_PORT_ERROE-参数错误:输入的服务器端口不正确107SEND_PAR_CONTEXT_ERROE-参数错误:没有输入发送内容108SEND_PAR_SENDTYPE_ERROE-参数错误:输入发送类型不正确201SEND_WSAStartup_ERROE-windows启动socket错误202SEND_socket_ERROE-WINDOWS的socket()错误203SEND_gethostbyname_ERROE-域名解析错误204SEND_setsockopt_ERROE-设置选项错误205SEND_connect_ERROE-建立连接connect()错误206SEND_send_ERROE-发送send()错误,可能是由于连接失效207SEND_SOCKET_ERROR-发送send()返回SOCKET错误208SEND_recv_ERROR-接受recv()错误209SEND_TYPE_AUTH_REPLY_ERROR-认证请求的响应类型错误,响应类型不符合协议210SEND_NO_CONNECT-用于表示发送业务包时无连接3.2.1 SendBusinessPkg _New接口 功能描述：调用SendBusinessPkg_New 函数;用于发送短信(参见SendTest程序中CSendTestDlg:OnSendmsg()方法) 接口参数描述：SendBusinessPkg_New(control_type,name,pwd,sc,dc,ip,port,content,sendtype,comid,NeedReceipt, BSTR mainAccessNum, VARIANT *pvSeqID,)参数数据类型描述约定control_typeString此时填send，表示发送短信nameString用户名pwdString用户密码scString发送号码dcString目的号码ipStringAPI公网接连IP地址01portStringAPI访问端口号9005contentString短信内容sendtypeString发送类型Sendtype=0，默认用用户信息表中的主号码作为发送号码Sendtype=1，默认用用户信息表中的号码池中随机取一个作为发送号码Sendtype=1，默认用自带的发送号码作为发送号码comidString企业IDNeedReceiptString标识是否需要回执0代表不需要回执，1代表需要回执mainAccessNumString住接入号用于可替代其他用户类型用于查找计费号码和企业IDpvSeqIDVARIANT用于返回包序号 接口函数返回值1:SEND_OK发送成功102SEND_PAR_USER_ERROE-参数错误:没有输入用户名103SEND_PAR_CODE_ERROE-参数错误:没有输入用户密码104SEND_PAR_DESTCODE_ERROE-参数错误:没有输入目的号码105SEND_PAR_IP_ERROE-参数错误:输入的服务器地址不正确106SEND_PAR_PORT_ERROE-参数错误:输入的服务器端口不正确107SEND_PAR_CONTEXT_ERROE-参数错误:没有输入发送内容108SEND_PAR_SENDTYPE_ERROE-参数错误:输入发送类型不正确201SEND_WSAStartup_ERROE-windows启动socket错误202SEND_socket_ERROE-WINDOWS的socket()错误203SEND_gethostbyname_ERROE-域名解析错误204SEND_setsockopt_ERROE-设置选项错误205SEND_connect_ERROE-建立连接connect()错误206SEND_send_ERROE-发送send()错误,可能是由于连接失效207SEND_SOCKET_ERROR-发送send()返回SOCKET错误208SEND_recv_ERROR-接受recv()错误209SEND_TYPE_AUTH_REPLY_ERROR-认证请求的响应类型错误,响应类型不符合协议210SEND_NO_CONNECT-用于表示发送业务包时无连接3.2.2 SendBusinessPkgByParam接口 功能描述：调用SendBusinessPkgByParam函数;用于发送短信可用于所有用户类型 接口参数描述：STDMETHODIMP CFullTunnelServiceControl:SendBusinessPkgByParam(BSTR control_type,BSTR paramList,BSTR paramListLen,VARIANT* pvSeqID,VARIANT *pvRE)参数数据类型描述约定control_typeString此时填send，表示发送短信paramListString4位的参数类型值1位的参数内容格式 S是string，I是int型，LSHI long型8位的参数值长度TLV格式的参数值，从而获取值paramListLenStringparamList的长度pvSeqIDVARIANT用于返回包序号 接口函数返回值1:SEND_OK发送成功102SEND_PAR_USER_ERROE-参数错误:没有输入用户名103SEND_PAR_CODE_ERROE-参数错误:没有输入用户密码104SEND_PAR_DESTCODE_ERROE-参数错误:没有输入目的号码105SEND_PAR_IP_ERROE-参数错误:输入的服务器地址不正确106SEND_PAR_PORT_ERROE-参数错误:输入的服务器端口不正确107SEND_PAR_CONTEXT_ERROE-参数错误:没有输入发送内容108SEND_PAR_SENDTYPE_ERROE-参数错误:输入发送类型不正确201SEND_WSAStartup_ERROE-windows启动socket错误202SEND_socket_ERROE-WINDOWS的socket()错误203SEND_gethostbyname_ERROE-域名解析错误204SEND_setsockopt_ERROE-设置选项错误205SEND_connect_ERROE-建立连接connect()错误206SEND_send_ERROE-发送send()错误,可能是由于连接失效207SEND_SOCKET_ERROR-发送send()返回SOCKET错误208SEND_recv_ERROR-接受recv()错误209SEND_TYPE_AUTH_REPLY_ERROR-认证请求的响应类型错误,响应类型不符合协议210SEND_NO_CONNECT-用于表示发送业务包时无连接3.2.3 CloseConnect接口 功能描述：当用户不在需要发送或接收数据时调CloseConnect();断开连接。参见CSendTestDlg:OnDisconnect()。 接口参数描述：CloseConnect() 用法示例 接口函数返回值0:S_OK 关闭连接成功1: S_FALSE关闭连接失败2: 连接已关闭4 代码示例4.1 流程说明第一步 首先调用StartAndManageConnect_User接口，发送认证请求包，建立用户的连接。第二步 如果第一步返回的认证响应包的状态值是true证明认证成功，则到第三步，否则返回第一步重新认证。第三步 调用发送函数 SendBusinessPkg接口用于发送短信或者StartRecv _User接口接口用于接收回执，上行短信和响应第四步 不用时可以调用CloseConnect接口关闭socket连接4.2 代码4.2.1 登录接口调用示例： private void button1_Click(object sender, EventArgs e) /string strControl_type = connect; string strName = username.Text;/ string strPwd = password.Text; string strServerip = ip.Text;/43 string strServerport = port.Text; /9005 object hr = ctr1.StartAndManageConnect_User(ref strName, ref strPwd, ref strServerip, ref strServerport); switch(Int32.Parse(hr.ToString() case 0: /其他返回值参见COM调用错误编号一.调用StartAndManageConnect_User 返回值 case 1: textBox1.AppendText(连接认证成功n); break; case 205: textBox1.AppendText(与服务器连接失败n); break; case 302: textBox1.AppendText(登陆用户名错误n); break; case 303: textBox1.AppendText(登陆密码错误n); break; case 304: textBox1.AppendText(连接数超过限制n); break; default: textBox1.AppendText(连接认证失败： + hr.ToString() + n); break; 4.2.2 发送短信示例：private void button2_Click(object sender, EventArgs e) try Thread thread = new Thread(new ThreadStart(SendFromDbThread); thread.Start(); catch (Exception ee) textBox1.AppendText(创建发送线程失败n); private void SendFromDbThread() string strControl_type = send; string strName = username.Text; /用户名 string strPwd = password.Text; /密码 string strServerip = ip.Text;/43 string strServerport = port.Text; string strSendtype = sendtype.Text; string strSourcecode = sendnum.Text; /必须得填不需要填发送号码的填 string strDestcode = recvnum.Text; /发送的号码 string strContent = content.Text; string strComid = comid.Text; /必须得填没有的话也必须填 string strNeedreceipt = needreport.Text; string seqID; /FullTunnelServiceControl ctr1 = new FullTunnelServiceControl(); object oOut = null; object hr = ctr1.SendBusinessPkg(ref strControl_type, ref strName, ref strPwd, ref strSourcecode, ref strDestcode, ref strServerip, ref strServerport, ref strContent, ref strSendtype, ref strComid, ref strNeedreceipt,out seqID); if (hr.ToString() = 1) /MessageBox.Show(seqID.ToString(); /MessageBox.Show(发送业务包成功); appendStringCtrl(发送短信成功SequenceID: + seqID.ToString() + n); else if (hr.ToString() = 210) textBox1.AppendText(发送短信时无连接n); else /textBox1.Text = 发送业务包失败+hr.ToString(); /MessageBox.Show(发送业务包fail); appendStringCtrl(发送短信失败n); static CallBack ca = new CallBack(Form1.CallBackProc); /得到函数指针 uint pCallBack = (uint)(Marshal.GetFunctionPointerForDelegate(ca).ToInt32(); private void button3_Click(object sender, EventArgs e) /FullTunnelServiceControl ctr1 = new FullTunnelServiceControl(); object hr = ctr1.StartRecv_User(pCallBack); if (hr.ToString() = 0) textBox1.AppendText(创建接收线程成功n); else textBox1.AppendText(创建接收线程失败n); 4.2.3 接收线程接受报文示例public static void CallBackProc(String BS_flag, String svalue1, String svalue2, String svalue3, String svalue4, String svalue5, String svalue6, String svalue7, String svalue8) /MessageBox.Show(进入回调函数里面); String msgtemp = ; if ( BS_flag.CompareTo(4) = 0 ) msgtemp += 业务响应包 SequenceID:+ svalue1+ MessID:+svalue2+ STATUS:+svalue3; /MessageBox.Show(msgtemp,业务响应包); appendStringCtrl(msgtemp); else if (BS_flag.CompareTo(5) = 0) msgtemp += 上行短信包 SequenceID: + svalue1 + 发送号码: + svalue2 + 接收号码: + svalue3+ 接收时间: + svalue4 + 短信内