江苏电信企信通客户端 API接口说明文档（C#）
（V1.0）
联创亚信科技(南京)有限公司
2012年11月
江苏电信企信通API接口说明文档
文档修改记录 文档版本 V1.0
修改人 陈萍 修改时间 2012-11-9 修改内容 新建 第2页 共19页
江苏电信企信通API接口说明文档
目 录
1 概述 ......................................................................................................................... 4
1.1 1.2
阅读对象 ...................................................................................................... 4 项目背景 ...................................................................................................... 4
2 环境准备 ................................................................................................................. 4
2.1 2.2 2.3
开发环境 ...................................................................................................... 4 使用该包说明 .............................................................................................. 4 定义类 .......................................................................................................... 4
3 API接口定义 ......................................................................................................... 5
3.1 3.2
接口说明 ...................................................................................................... 5 接口描述 ...................................................................................................... 5
4 代码示例 ............................................................................................................... 14 5 常见问题 ............................................................................................................... 18 6 其他 ....................................................................................................................... 19
第3页 共19页
江苏电信企信通API接口说明文档
概述
1.1 阅读对象
本文档为DLL组件（FullTunnelControl.dll）的使用说明文档，为系统设计人员或程序开发人员应用该开发包进行二次开发而编写，主要服务对象为与该项目有关的项目 管理人员、系统设计人员和系统开发人员。
1.2 项目背景
环境准备
2.1 开发环境
操作系统：不限。
2.2 使用该包说明
1)
使用组件需要先注册组件, D:\\codes\\msg_com_p\\FullTunnelControl.dll
2) 运行环境中，字符集编码为GBK。
3) 使用该组件时需要在代码里添加下面几条语句即可
在头文件中加入下列语句(路径根据具体进行修改) #import \#pragma comment(lib,%using namespace FULLTUNNELCONTROLLib; 4) 使用该包提供的用户接口（类）进行开发。
2.3 定义类
第4页 共19页
例
如
regsvr32
江苏电信企信通API接口说明文档
API接口定义
3.1 接口说明
本组件包括以下几个应用接口，分别如下： 接口名称 StartAndManageConnect_User StartRecv SendBusinessPkg 类型 函数 函数 函数 功能描述 客户端建立连接接口函数 客户端接收报文信息的接口函数 客户端发送报文信息的接口函数（仅限普通用户） SendBusinessPkg_New 函数 客户端发送报文信息的接口函数（添加主接入号） SendBusinessPkgByParam 函数 客户端可以用于所有用户类型的客户端发送报文的接口函数 CloseConnect
函数 客户端关闭连接的接口函数 3.2 接口描述
3.2.1 StartAndManageConnect_User接口
3.2.1.1 功能描述：
调用 StartAndManageConnect_User(name, pwd, ip, port)函数;用于建立连接并发送认证包。(参见SendTest程序中CSendTestDlg::OnConnect()方法) ,如果认证成功后，会创建守护进程（即发送心跳包），维持连接不断开。
3.2.1.2 接口参数描述：
StartAndManageConnect_User(name, pwd, ip, port) 参数 name pwd ip 数据类型 String String String 描述 API用户名 API用户密码 API公网接连IP地址 第5页 共19页
约定 202.102.41.101 江苏电信企信通API接口说明文档
port
Int API访问端口号 9005 3.2.1.3 用法示例
3.2.1.4 接口函数返回值
0: S_OK连接认证成功 创建守护线程成功 1: S_FALSE连接认证成功 创建守护线程失败 102 103 104 105 106 107 108 201 202 203 204 205 206 207 208 209 301 302 303 304 305 306 307 308 309 310 311 312
服务器返回结果:-服务器系统错误 服务器返回结果:-登录用户名错误 服务器返回结果:-登录密码错误 服务器返回结果:-连接数超过限制 服务器返回结果:-每秒发送条目数超过限制 服务器返回结果:-发送的目的号码受限制 服务器返回结果:-网络错误
服务器返回结果:-每月发送条目数超过限制 服务器返回结果:-客户端关闭连接 服务器返回结果:-短信网关关闭连接 服务器返回结果:-超时退出 服务器返回结果:-连接数据库错误
SEND_PAR_USER_ERROE-参数错误:没有输入用户名 SEND_PAR_CODE_ERROE-参数错误:没有输入用户密码
SEND_PAR_DESTCODE_ERROE-参数错误:没有输入目的号码 // SEND_PAR_IP_ERROE-参数错误:输入的服务器地址不正确 SEND_PAR_PORT_ERROE-参数错误:输入的服务器端口不正确 SEND_PAR_CONTEXT_ERROE-参数错误:没有输入发送内容 // SEND_PAR_SENDTYPE_ERROE-参数错误:输入发送类型不正确 // SEND_WSAStartup_ERROE-windows启动socket错误 SEND_socket_ERROE-WINDOWS的socket()错误 SEND_gethostbyname_ERROE-域名解析错误 SEND_setsockopt_ERROE-设置选项错误 SEND_connect_ERROE-建立连接connect()错误
SEND_send_ERROE-发送send()错误,可能是由于连接失效 SEND_SOCKET_ERROR-发送send()返回SOCKET错误 SEND_recv_ERROR-接受recv()错误
SEND_TYPE_AUTH_REPLY_ERROR-认证请求的响应类型错误,响应类型不符合协议
第6页 共19页
江苏电信企信通API接口说明文档
313 314 315 316 317 318 319 320
服务器返回结果:-连接短信网关错误 服务器返回结果:-非法内容 服务器返回结果:-非法时间 服务器返回结果:-服务器未定义 服务器返回结果:-服务器未定义 服务器返回结果:-服务器未定义 服务器返回结果:-服务器未定义 服务器返回结果:-服务器未定义
3.2.2 StartRecv _User接口
3.2.2.1 功能描述：
当认证通过后即可调用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的值相应的取不同的字段从而可以分别得到业务响应包，回执包，上行短信包。
3.2.2.2 接口参数描述：
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_flag 数据类型 String 描述 约定 当flag == 4时，此时为业务响应包； 当flag == 5时，此时为上行短信包； 当flag == 7时 此时为回执包 BS_svalue1 BS_svalue2 String String 包序号 flag=4时，BS_ svalue2为业务响应包的MsgId; flag=5时，BS_svalue2为上行短信包的发送号码; flag=7时，BS_ svalue2为回执包的MsgId; BS_svalue3 String flag=4时，BS_ svalue3为status，即业务响应包的状态值; flag=5时，BS_ svalue3为上行包接收号码 flag=7时，BS_ svalue3为回执包里接收号码 BS_svalue4 BS_svalue5 String String flag=5时，BS_ svalue4为上行包接收时间 flag=7时，BS_ svalue4为回执包里发送号码 flag=5时，BS_ svalue5为上行包短信内容 第7页 共19页
标识包类型 当flag==2 时，此时为认证响应包； 江苏电信企信通API接口说明文档
flag=7时，BS_ svalue5为回执包里提交时间 BS_svalue6 BS_svalue7 BS_svalue8
String String String flag=7时，BS_ svalue6为回执包里下发时间 flag=7时，BS_ svalue7为回执包里短信状态 flag=7时，BS_ svalue8为回执包里错误代码 3.2.2.3 用法示例
3.2.2.4 接口函数返回值
0:
S_OK创建接收线程成功
1: S_FALSE创建接收线程失败
3.2.2.5 响应包里的状态值
状态码 0 1 2 3 4 5 6 7 8 9 10 11 12 描述 成功 系统错误 帐号错误 密码错误 连接数超过限制 秒发送条目数限制 发送目的号码限制 网络原因 月发送条目数限制 客户端关闭连接 gw关闭连接 超时退出 连接数据库错误 第8页 共19页
江苏电信企信通API接口说明文档
13 14 15 16 17 18 19 20 21 22 连接网关错误 非法内容 非法时间 非法ip 向用户信息列表中加入用户失败 从数据库初始化用户信息失败 接入号码错误 验证网信账号失败 天翼号码错误 指定号码不在号码池 3.2.2.6 回执包中的状态值 000 成功 DELIVRD
001 用户不能通信 EXPIRED 002 用户忙 EXPIRED
003 终端无此部件号 UNDELIV 004 非法用户 UNDELIV
005 用户在黑名单内 UNDELIV 006 系统错误 UNDELIV 007 用户内存满 EXPIRED 008 非信息终端 UNDELIV 009 数据错误 UNDELIV 010 数据丢失 UNDELIV 999 未知错误 UNKNOWN
3.2.3 SendBusinessPkg接口
3.2.3.1 功能描述：
调用SendBusinessPkg函数;用于发送短信(参见SendTest程序中CSendTestDlg::OnSendmsg()方法)
3.2.3.2 接口参数描述：
SendBusinessPkg(control_type,name,pwd,sc,dc,ip,port,content,sendtype,comid,NeedReceipt, VARIANT *pvSeqID,) 参数 数据类描述 约定 第9页 共19页
江苏电信企信通API接口说明文档
型 control_type name pwd sc dc ip port content sendtype String String String String String String String String String 用户名 用户密码 发送号码 目的号码 API公网接连IP地址 API访问端口号 短信内容 发送类型 此时填send，表示发送短信 202.102.41.101 9005 Sendtype=0，默认用用户信息表中的主号码作为发送号码 Sendtype=1，默认用用户信息表中的号码池中随机取一个作为发送号码 Sendtype=1，默认用自带的发送号码作为发送号码 comid NeedReceipt pvSeqID
String String 企业ID 标识是否需要回执 0代表不需要回执，1代表需要回执 VARIANT 用于返回包序号 3.2.3.3 用法示例
3.2.3.4 接口函数返回值
1: 102 103 104 105 106 107 108 201 202 203
SEND_OK发送成功
SEND_PAR_USER_ERROE-参数错误:没有输入用户名 SEND_PAR_CODE_ERROE-参数错误:没有输入用户密码 SEND_PAR_DESTCODE_ERROE-参数错误:没有输入目的号码 SEND_PAR_IP_ERROE-参数错误:输入的服务器地址不正确 SEND_PAR_PORT_ERROE-参数错误:输入的服务器端口不正确 SEND_PAR_CONTEXT_ERROE-参数错误:没有输入发送内容 SEND_PAR_SENDTYPE_ERROE-参数错误:输入发送类型不正确 SEND_WSAStartup_ERROE-windows启动socket错误 SEND_socket_ERROE-WINDOWS的socket()错误 SEND_gethostbyname_ERROE-域名解析错误
第10页 共19页
江苏电信企信通API接口说明文档
204 205 206 207 208 209 210
SEND_setsockopt_ERROE-设置选项错误 SEND_connect_ERROE-建立连接connect()错误
SEND_send_ERROE-发送send()错误,可能是由于连接失效 SEND_SOCKET_ERROR-发送send()返回SOCKET错误 SEND_recv_ERROR-接受recv()错误
SEND_TYPE_AUTH_REPLY_ERROR-认证请求的响应类型错误,响应类型不符合协议 SEND_NO_CONNECT-用于表示发送业务包时无连接
3.2.1 SendBusinessPkg _New接口
3.2.1.1 功能描述：
调用SendBusinessPkg_New 函数;用于发送短信(参见SendTest程序中CSendTestDlg::OnSendmsg()方法)
3.2.1.2 接口参数描述：
SendBusinessPkg_New(control_type,name,pwd,sc,dc,ip,port,content,sendtype,comid,NeedReceipt, BSTR mainAccessNum, VARIANT *pvSeqID,) 参数 control_type name pwd sc dc ip port content sendtype 数据类型 String String String String String String String String String 用户名 用户密码 发送号码 目的号码 API公网接连IP地址 API访问端口号 短信内容 发送类型 此时填send，表示发送短信 202.102.41.101 9005 Sendtype=0，默认用用户信息表中的主号码作为发送号码 Sendtype=1，默认用用户信息表中的号码池中随机取一个作为发送号码 Sendtype=1，默认用自带的发送号码作为发送号码 comid NeedReceipt mainAccessNum pvSeqID VARIANT 用于返回包序号 String String String 企业ID 标识是否需要回执 住接入号 0代表不需要回执，1代表需要回执 用于可替代其他用户类型用于查找计费号码和企业ID 描述 约定 3.2.1.3 接口函数返回值
1:
SEND_OK发送成功
第11页 共19页
江苏电信企信通API接口说明文档
102 103 104 105 106 107 108 201 202 203 204 205 206 207 208 209 210
SEND_PAR_USER_ERROE-参数错误:没有输入用户名 SEND_PAR_CODE_ERROE-参数错误:没有输入用户密码 SEND_PAR_DESTCODE_ERROE-参数错误:没有输入目的号码 SEND_PAR_IP_ERROE-参数错误:输入的服务器地址不正确 SEND_PAR_PORT_ERROE-参数错误:输入的服务器端口不正确 SEND_PAR_CONTEXT_ERROE-参数错误:没有输入发送内容 SEND_PAR_SENDTYPE_ERROE-参数错误:输入发送类型不正确 SEND_WSAStartup_ERROE-windows启动socket错误 SEND_socket_ERROE-WINDOWS的socket()错误 SEND_gethostbyname_ERROE-域名解析错误 SEND_setsockopt_ERROE-设置选项错误 SEND_connect_ERROE-建立连接connect()错误
SEND_send_ERROE-发送send()错误,可能是由于连接失效 SEND_SOCKET_ERROR-发送send()返回SOCKET错误 SEND_recv_ERROR-接受recv()错误
SEND_TYPE_AUTH_REPLY_ERROR-认证请求的响应类型错误,响应类型不符合协议 SEND_NO_CONNECT-用于表示发送业务包时无连接
3.2.2 SendBusinessPkgByParam接口
3.2.2.1 功能描述：
调用SendBusinessPkgByParam函数;用于发送短信可用于所有用户类型
3.2.2.2 接口参数描述：
STDMETHODIMP CFullTunnelServiceControl::SendBusinessPkgByParam( BSTR control_type, BSTR paramList, BSTR paramListLen, VARIANT* pvSeqID, VARIANT *pvRE) 数据类型 control_type paramList String String 此时填send，表示发送短信 4位的参数类型值 1位的参数内容格式 S是string，I是int型，LSHI long型 8位的参数值长度 TLV格式的参数值，从而获取值 paramListLen String pvSeqID paramList的长度 VARIANT 用于返回包序号 描述 约定 参数 第12页 共19页
江苏电信企信通API接口说明文档
3.2.2.3 接口函数返回值
1: 102 103 104 105 106 107 108 201 202 203 204 205 206 207 208 209 210
SEND_OK发送成功
SEND_PAR_USER_ERROE-参数错误:没有输入用户名 SEND_PAR_CODE_ERROE-参数错误:没有输入用户密码 SEND_PAR_DESTCODE_ERROE-参数错误:没有输入目的号码 SEND_PAR_IP_ERROE-参数错误:输入的服务器地址不正确 SEND_PAR_PORT_ERROE-参数错误:输入的服务器端口不正确 SEND_PAR_CONTEXT_ERROE-参数错误:没有输入发送内容 SEND_PAR_SENDTYPE_ERROE-参数错误:输入发送类型不正确 SEND_WSAStartup_ERROE-windows启动socket错误 SEND_socket_ERROE-WINDOWS的socket()错误 SEND_gethostbyname_ERROE-域名解析错误 SEND_setsockopt_ERROE-设置选项错误 SEND_connect_ERROE-建立连接connect()错误
SEND_send_ERROE-发送send()错误,可能是由于连接失效 SEND_SOCKET_ERROR-发送send()返回SOCKET错误 SEND_recv_ERROR-接受recv()错误
SEND_TYPE_AUTH_REPLY_ERROR-认证请求的响应类型错误,响应类型不符合协议 SEND_NO_CONNECT-用于表示发送业务包时无连接
3.2.3 CloseConnect接口
3.2.3.1 功能描述：
当用户不在需要发送或接收数据时调CloseConnect();断开连接。参见CSendTestDlg::OnDisconnect()。
3.2.3.2 接口参数描述：
CloseConnect()
3.2.3.3 用法示例
3.2.3.4 接口函数返回值
0:
S_OK 关闭连接成功
1: S_FALSE关闭连接失败 2: 连接已关闭
第13页 共19页
江苏电信企信通API接口说明文档
代码示例
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 = \ string strName = username.Text;// string strPwd = password.Text;
string strServerip = ip.Text;//218.94.58.243 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:
第14页 共19页
江苏电信企信通API接口说明文档
textBox1.AppendText(\登陆用户名错误\\n\);
break;
case 303:
textBox1.AppendText(\登陆密码错误\\n\);
break;
case 304:
textBox1.AppendText(\连接数超过限制\\n\);
break;
default:
textBox1.AppendText(\连接认证失败：\ + hr.ToString() + \); 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 = \;
string strName = username.Text; //用户名 string strPwd = password.Text; //密码 string strServerip = ip.Text;//218.94.58.243 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;
第15页 共19页
江苏电信企信通API接口说明文档
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() == \){
//MessageBox.Show(seqID.ToString()); //MessageBox.Show(\发送业务包成功\
appendStringCtrl(\发送短信成功SequenceID:\ + seqID.ToString() + \); }
else if (hr.ToString() == \) {
textBox1.AppendText(\发送短信时无连接\\n\); } else {
//textBox1.Text = \发送业务包失败\ //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() == \){
textBox1.AppendText(\创建接收线程成功\\n\); } else {
textBox1.AppendText(\创建接收线程失败\\n\); } }
第16页 共19页
江苏电信企信通API接口说明文档
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(\) == 0 ){
msgtemp += \业务响应包] SequenceID:\+ svalue1+\+svalue2+\STATUS:\+svalue3;
//MessageBox.Show(msgtemp,\业务响应包\ appendStringCtrl(msgtemp); }
else if (BS_flag.CompareTo(\) == 0){
msgtemp += \上行短信包] SequenceID:\ + svalue1 +\发送号码:\ + svalue2 +\接收号码:\ + svalue3+
\接收时间:\ + svalue4 + \短信内容:\ +svalue5; MessageBox.Show(msgtemp,\上行短信包\); //textBox1.AppendText(msgtemp + \ }
else if (BS_flag.CompareTo(\) == 0){
msgtemp += \短信回执包] SequenceID:\ + svalue1 + \ + svalue2 + \接收号码:\+ svalue3
+ \发送号码:\ + svalue4 + \提交时间:\+ svalue5 + \下发时间:\ + svalue6
+\短信状态:\ + svalue7 + \错误代码:\ + svalue8; //MessageBox.Show(msgtemp, \短信回执包\ appendStringCtrl(msgtemp); } }
private void button3_Click(object sender, EventArgs e) {
//FullTunnelServiceControl ctr1 = new FullTunnelServiceControl(); object hr = ctr1.StartRecv_User(pCallBack);
if (hr.ToString() == \){
第17页 共19页
江苏电信企信通API接口说明文档
textBox1.AppendText(\创建接收线程成功\\n\); } else {
textBox1.AppendText(\创建接收线程失败\\n\); } }
4.2.4 关闭连接示例
private void button4_Click(object sender, EventArgs e) {
// FullTunnelServiceControl ctr1 = new FullTunnelServiceControl(); object hr = ctr1.CloseConnect();
if (hr.ToString() == \) {
textBox1.AppendText(\断开连接成功\\n\); } else {
textBox1.AppendText(\断开连接失败\\n\); }
常见问题
1、在服务运行过程中，如果网络出现异常，该组件会检测到，并自动重新连接至企信通API服务端。
2、调用关闭连接的函数CloseConnect之后，重新使用API请从第二步开始。
3、用户可以不使用该组件中的自动重连功能，自己来实现断开重连功能。调用断开连接函数CloseConnect，然后依照上述流程的第二步开始重新连接。
第18页 共19页
江苏电信企信通API接口说明文档
注意事项：
1. 链接一旦建立请不要断开 系统会自动发出心跳保持链接如果二次连接的话对于相同
的客户端IP地址，服务端会将第一次的连接断开，允许第二次连接；对于不同的客户端IP地址，认证将不成功
2. 默认的秒发送速度 每秒提交2条，每月发送上限 默认8000条。
3. 一个账号只能有一个连接。如果二次连接的话对于相同的客户端IP地址，服务端会将
第一次的连接断开，允许第二次连接；对于不同的客户端IP地址，认证将不成功
其他
第19页 共19页