金融基础件0接入T2SDK开发手册.docx
《金融基础件0接入T2SDK开发手册.docx》由会员分享，可在线阅读，更多相关《金融基础件0接入T2SDK开发手册.docx（126页珍藏版）》请在冰豆网上搜索。
金融基础件0接入T2SDK开发手册
金融基础件2.0接入
T2SDK开发手册
文档版本
V2.0
发布日期
2013-06-27
修改记录
版本号
日期
修改者
修改说明
V2.0
许欣芃
创建
前言
产品简介
英文全称TCP2SoftwareDevelopmentKit。
T2SDK是接入金融基础件2.0的客户端开发包，因为该开发包底层采用TCP协议，取名为“T2SDK”。
T2SDK以dll（Windows下）或so（Linux下）的形式提供给开发者，通过使用T2SDK开发程序可以轻松实现和CRES2.0（金融基础件2.0）平台的对接，使用T2_SDK开发的程序在本文档中也称为“客户端”。
读者对象
本指南主要适用于以下人员：
●开发人员，仅限于C++开发，对接各种在CRES2.0平台基础上搭建的系统，譬如：
UFX，UF2.0等等。
手册概况
本手册各章节内容如下表所示。
章节
内容
1开发包简介
介绍开发包的支持系统，获取方式
2开发流程
介绍开发的步骤，异步同步的开发模式
3开发接口
具体的开发接口的函数说明
4示例代码
开发的demo的实例代码
5使用注意事项
介绍接口调用时禁止的方式
缩略语/术语
下面列出了本手册中出现的缩略语和术语。
C
CRES2.0
金融基础件2.0
恒生的新一代金融基础件平台，本文档介绍的开发包就是接入此平台的C++版本的开发包。
下面说的服务端不特殊说明都是指CRES2.0.
U
UFX
恒生统一接入系统
客户端的统一接入控制系统，是基于CRES2.0平台之上搭建，用T2SDK可以接入。
UF2.0
恒生经济运营平台
恒生的证券经纪运营平台系统，是基于CRES2.0平台之上搭建，用T2SDK可以接入。
M
MC2.0
消息中心2.0
本文档提到的订阅发布接口都是针对消息中心2.0,1.0的订阅发布不能用这个接口，需要自己开发代码
MC1.0
消息中心1.0
消息中心1.0需要通过业务消息中增加字段来订阅，没有现成的接口调用。
1.开发包简介
名称：
开发语言：
C++
支持操作系统：
windows/linux
版本信息获取：
⏹WINDOWS：
右键->属性->详细信息，里面有版本信息，格式是“1.0.0.*”。
⏹LINUX：
通过命令“strings|grepversion”，如下所示：
[integration@fbase56lib]$strings|grepversion
lzo_version
_lzo_version_string
_lzo_version_date
_Z10conversionc
_Z10conversionPc
versionJun27201314:
47:
40这就是版本信息
SSLhandshakefailed,maybeclientandserverSSLversionmismatch.
version
获取方式：
●恒生内部的员工，以项目组的形式向研发中心客服申请使用。
●恒生外部开发商，向对应的项目的恒生接口人获取开发包。
2.开发流程
本章节主要介绍两种开发的模式，同步、异步。
2.1同步开发流程
2.2异步开发流程
3.开发接口
本章主要介绍开发包提供的所有接口，函数参数说明。
没有特殊说明，接口都是线程安全的。
3.1T2SDK引出函数
3.1.1取开发包版本信息（GetVersionInfo）
函数原型：
intFUNCTION_CALL_MODEGetVersionInfo（）;
输入参数：
参数名称
参数说明
用法
无
返回：
返回发布包的版本信息，返回类型是一个INT型数据。
用法说明：
返回的INT数据，高位的4bit表示开发包的类型，始终为1，后面28bit表示版本信息，版本信息值越大，版本越高。
3.1.2创建配置接口（NewConfig）
函数原型：
CConfigInterface*FUNCTION_CALL_MODENewConfig（）;
输入参数：
参数名称
参数说明
用法
无
返回：
新的连接配置项接口。
用法说明：
通过返回的新的连接配置项接口，设置相应的连接属性，具体的接口说明参照下面的CConfigInterface接口说明。
注意
NewConfig（）返回的接口，必须调用AddRef，否则调用Release接口就无法释放
3.1.3创建连接接口（NewConnection）
函数原型：
CConnectionInterface*FUNCTION_CALL_MODENewConnection（CConfigInterface*lpConfig）;
输入参数：
参数名称
参数说明
用法
CConfigInterface*lpConfig
配置对象，通过NewConfig（）返回
输入参数
返回：
新的连接接口，所有发包收包都是建立在连接接口之上。
用法说明：
通过返回的连接接口指针，就可以访问服务端，发功能号，收应答，所有操作都是基于连接。
注意
NewConnection（）返回的接口，必须调用AddRef，否则调用Release接口就无法释放
3.1.4创建打包器接口（NewPacker）
函数原型：
IF2Packer*FUNCTION_CALL_MODENewPacker（intiVersion）;
输入参数：
参数名称
参数说明
用法
intiVersion
打包器的版本，支持1,2两种
输入参数
返回：
新的打包器接口，用于业务数据的组装，传递业务接口需要的参数
用法说明：
打包器需要什么版本，根据业务接口的说明来决定。
注意
NewPacker返回的接口，必须调用AddRef，否则调用Release接口就无法释放
3.1.5创建解包器接口（NewUnPacker）
函数原型：
IF2UnPacker*FUNCTION_CALL_MODENewUnPacker（void*lpBuffer,unsignedintiLen）;
输入参数：
参数名称
参数说明
用法
void*lpBuffer
二进制数据的首指针
输入参数
unsignedintiLen
二进制数据的长度
输入参数
返回：
根据传入的二进制数据进行解包，生成新的解包器，数据不符合解包器格式，就放那会NULL。
用法说明：
解包器一般用于收到应答时，对业务应答的解析，获取自己需要的内容。
注意
NewUnPacker返回的接口，必须调用AddRef，否则调用Release接口就无法释放
3.1.6加密接口（Encode）
函数原型：
char*FUNCTION_CALL_MODEEncode（char*EncodePass,constchar*Password,intnReserve=0）;
输入参数：
参数名称
参数说明
用法
char*EncodePass
传出的加密结果，长度不超过16（包括'\0'）
输出参数
constchar*Password
传入的待加密的密码
输入参数
intnReserve
保留输入参数，采用默认值即可
输入参数
返回：
对密码加密处理，返回，输出参数的空间是外面申请。
用法说明：
用于客户端传递密码时，加密处理，防止密码以明文形式传递。
不过此接口已经不用，由下面的EncodeEx取代。
3.1.7密码加密接口（EncodeEx）
函数原型：
intFUNCTION_CALL_MODEEncodeEx（constchar*pIn,char*pOut）;
输入参数：
参数名称
参数说明
用法
constchar*pIn
传入的待加密的字符串
输入参数
char*pOut
长度和传入的字符串大小一样，由外部申请
输出参数
返回：
对密码加密处理，返回，输出参数的空间是外面申请。
用法说明：
用于客户端传递密码时，加密处理，防止密码以明文形式传递。
3.1.8创建过滤接口（NewFilter）
函数原型：
CFilterInterface*FUNCTION_CALL_MODENewFilter（）;
输入参数：
参数名称
参数说明
用法
无
返回：
新的过滤接口，用于订阅发布的时候添加过滤属性用
用法说明：
订阅和发布的时候需要根据订阅主题，指定相关的过滤参数，根据过滤条件获取对应的发布消息。
注意
NewFilter返回的接口，必须调用AddRef，否则调用Release接口就无法释放
3.1.9创建订阅参数接口（NewSubscribeParam）
函数原型：
CSubscribeParamInterface*FUNCTION_CALL_MODENewSubscribeParam（）;
输入参数：
参数名称
参数说明
用法
无
返回：
新的订阅参数接口，用于订阅时候添加订阅属性用
用法说明：
订阅时候用来添加订阅属性，包括主题信息，过滤信息，发送频度等等。
注意
NewSubscribeParam返回的接口，必须调用AddRef，否则调用Release接口就无法释放
3.1.10创建业务消息接口（NewBizMessage）
函数原型：
IBizMessage*FUNCTION_CALL_MODENewBizMessage（）;
输入参数：
参数名称
参数说明
用法
无
返回：
新的业务消息接口
用法说明：
通过这个接口设置业务相关的属性，底层根据这个消息构造二进制发送。
注意
NewBizMessage返回的接口，必须调用AddRef，否则调用Release接口就无法释放
3.2配置接口【CConfigInterface】
3.2.1读取配置文件（Load）
函数原型：
virtualintFUNCTION_CALL_MODELoad（constchar*szFileName）=0;
输入参数：
参数名称
参数说明
用法
constchar*szFileName
连接属性的配置文件
输入参数
返回：
加载成功返回0，其他值表示失败
用法说明：
这里加载的文件是ini格式的文件，下面是文件的简单实例：
[t2sdk]
;许可证文件
license_file=
;服务器地址
servers=192.168.194.56:
6002;192.168.194.56:
8001
;接受缓存初始化大小
init_recv_buf_size=512
;发送缓存初始化大小
init_send_buf_size=512
;发送队列
send_queue_size=1000
[safe]
;安全级别
safe_level=none
;客户号
client_id=123456
;客户密码
comm_pwd=888888
;ssl证书
cert_file=
;ssl证书密码
cert_pwd=xxxxxxxx
每个标签以及属性都有自己的含义，下面是一些通用标签和含义的解释：
标签名
属性名
含义
[t2sdk]
基本参数
servers
客户端要连接的服务端的IP和端口，可以配置一个或多个，中间以;分割，第一次连接时，会从这串服务端地址中，随即选择一个地址来尝试建立连接；再次连接时，会取当前地址的后一个地址来尝试建立连接，以此类推
lang
语言取值及含义如下：
2052：
中文（缺省）
1033：
英文
errormsg
用户指定错误信息文件，错误号从-70到0，缺省为””。
init_recv_buf_size
接收缓存的初始大小，单位字节，实际接收到服务端的数据时，可能会扩大（如果需要）
init_send_buf_size
每块发送缓存的初始大小，单位字节，该大小也会根据需要动态扩大
send_queue_size
发送队列的大小，该大小不会动态变化，若该配置项很小，且连接发包很频繁，则可能因为发送队列满而造成发送失败
license_file
此配置项配置许可证文件的路径，如果没有配置，则默认为当前目录下的。
该许可证需向恒生电子股份有限公司申请。
heartbeat_time
客户端给服务端发送心跳的间隔时间，单位为秒，最小值为5秒，不配或者配<=0，表示不开启客户端心跳
if_error_log
是否记录错误日志的参数，1表示记录，0表示不记录，默认不记录。
logdir
记录日志的目录，默认在程序运行的当前目录，只有开启记录日志，才会记录
if_sendRecv_log
记录发包和收包的日志，用于客户端查找问题，1表示记录，0表示不记录，默认不记录
login_name
有名客户端的名字，默认是匿名
license_pwd
许可证的加密密码，用于UFX接入时，默认没有密码
event_count
指定事件个数，缺省为10。
connect_time
指定连接超时，缺省为5。
support_multi
指定是否支持多线程同步调用，0:
不支持（缺省）非0:
支持。
enable_nagle
指定是否禁用Nagle算法，1:
禁用，非1:
开启（缺省）。
addipmac
指定是否在注册包中加IP和MAC，1:
是（缺省），非1:
否。
machine_code
指定机器码。
auto_reconnect
指定是否自动重连，1:
是，非1:
否（缺省）。
compatible
是否开启1.0订阅模式，底层是2.0的订阅实现；默认0不开启，非0开启。
[safe]
连接相关
safe_level
连接的安全模式，可以选择明文（none），通信密码（pwd），SSL（ssl）,注意大小写敏感
client_id
当连接的安全模式为pwd时，client_id配置项才生效,客户号，一个客户号对应一个密码
comm_pwd
在pwd模式下，当client_id为空时，comm_pwd为默认的密钥;注意当client_id为空时，comm_pwd必须和服务端的配置一致方可正常使用
ca_file
指定客户端的证书（根证书，校验服务端用）
ca_pwd
若证书为*.pfx，则需要配ca_pwd，若为*.pem，则可配可不配
cert_file
cert_file配置被服务端校验的证书路径和密码
cert_pwd
不管格式如何，cert_pwd必配
check_server_cert
是否校验服务端，可不配，若不配，默认校验服务端，0表示不校验。
1表示校验
version
指定SSL版本，缺省为””。
verify_depth
指定校验深度，缺省为0。
[proxy]
代理参数
proxy_type
可配置采用何种代理配置http/socks4/socks5，空表示不采用代理
ip
若proxy_type不为空，下面配置生效;代理服务器的IP地址
port
代理服务器的端口
user_name
登陆代理服务器的用户名
password
登陆代理服务器的密码
3.2.2保存配置文件（Save）
函数原型：
virtualintFUNCTION_CALL_MODESave（constchar*szFileName）=0;
输入参数：
参数名称
参数说明
用法
constchar*szFileName
需要保存属性的配置文件
输入参数
返回：
保存成功返回0，其他值表示失败
用法说明：
这个函数是把属性内存落地成文件，文件格式如上面加载的文件。
3.2.3获取字符型配置项值（GetString）
函数原型：
virtualconstchar*FUNCTION_CALL_MODEGetString（constchar*szSection,constchar*szEntry,constchar*szDefault）=0;
输入参数：
参数名称
参数说明
用法
constchar*szSection
节名
输入参数
constchar*szEntry
变量名
输入参数
constchar*szDefault
默认值
输入参数
返回：
获取ini配置里面相应的节点名和变量名的属性值，用字符串形式返回。
用法说明：
[t2sdk]
license_file=
上面t2sdk就是节点名，license_file就是属性名，如果配置中没有节点名和属性名，用第三个参数作为返回值。
3.2.4获取整型配置项值（GetInt）
函数原型：
virtualintFUNCTION_CALL_MODEGetInt（constchar*szSection,constchar*szEntry,intiDefault）=0;
输入参数：
参数名称
参数说明
用法
constchar*szSection
节名
输入参数
constchar*szEntry
变量名
输入参数
intiDefault
默认值
输入参数
返回：
获取ini配置里面相应的节点名和变量名的属性值，用整型形式返回。
用法说明：
节点名和属性名定义如上面所示，同样的，如果不存在这个属性，就返回第三个参数。
3.2.5设置字符型配置项值（SetString）
函数原型：
virtualintFUNCTION_CALL_MODESetString（constchar*szSection,constchar*szEntry,constchar*szValue）=0;
输入参数：
参数名称
参数说明
用法
constchar*szSection
节名
输入参数
constchar*szEntry
变量名
输入参数
constchar*szValue
需要设置的值
输入参数
返回：
设置字符串型属性值到对应的节点和变量中。
返回0表示设置成功，其他表示失败。
用法说明：
通过代码设置属性到配置项中，可以不需要读取配置文件。
3.2.6设置整型配置项值（SetInt）
函数原型：
virtualintFUNCTION_CALL_MODESetInt（constchar*szSection,constchar*szEntry,intiValue）=0;
输入参数：
参数名称
参数说明
用法
constchar*szSection
节名
输入参数
constchar*szEntry
变量名
输入参数
intiValue
需要设置的值
输入参数
返回：
设置整型属性值到对应的节点和变量中。
返回0表示设置成功，其他表示失败。
用法说明：
下面代码展示如果通过代码设置连接属性，不需要读取配置文件，当然读取文件之后，也是可以再设置属性，属性设置是覆盖的：
CConfigInterface*lpConfig=NewConfig（）;
lpConfig->AddRef（）;
lpConfig->SetString（"t2sdk","servers","192.168.94.30:
9999"）;
lpConfig->SetString（"t2sdk","license_file",""）;
lpConfig->SetInt（"t2sdk","send_queue_size",100）;
lpConfig->SetString（"safe","safe_level","none"）;
3.3连接回调接口【CCallbackInterface】
如果是异步的模式，需要完成的回调接口定义。
上层业务代码需要定义类继承这个接口，然后实现相应的功能。
3.3.1TCP连接成功回调（OnConnect）
这个函数在TCP连接成功之后就会回调。
函数原型：
virtualvoidFUNCTION_CALL_MODEOnConnect（CConnectionInterface*lpConnection）=0;
回调参数：
参数名称
参数说明
用法
CConnectionInterface*lpConnection
当前回调产生的连接指针
回调
用法说明：
在SOCKET套接字建立成功之后，回调这个函数，这个回调里面一般也就是简单的展示连接信息，无法进行任何操作。
3.3.2安全连接成功回调（OnSafeConnect）
这个函数在安全连接成功之后就会回调，安全连接就是指，密码安全模式下，密码交换成功之后；或者SSL连接建立成功之后。
函数原型：
virtualvoidFUNCTION_CALL_MODEOnSafeConnect（CConnectionInterface*lpConnection）=0;
回调参数：
参数名称
参数说明
用法
CConnectionInterface*lpConnection
当前回调产生的连接指针
回调
用法说明：
在安全连接建立成功之后，回调这个函数，这个回调里面一般也就是简单的展示连接信息，无法进行任何操作。
3.3.3注册成功回调（OnRegister）
这个函数在成功收到服务端注册应答之后就会回调，注册动作时发生在安全连接之后。
函数原型：
virtualvoidFUNCTION_CALL_MODEOnRegister（CConnectionInterface*lpConnection）=0;
回调参数：
参数名称
参数说明
用法
CConnectionInterface*lpConnection
当前回调产生的连接指针
回调
用法说明：
在注册成功之后，回调这个函数，这个回调里面可以通知其他线程已经可以开始干活了，连接已经建立，可以发包收包做业务操作了。
3.3.4连接断开回调（OnClose）
这个函数在连接断开之后，会进入这个回调，连接断开可能是服务器断开，或者客户端检测到连接断开，等等。
函数原型：
virtualvoidFUNCTION_CALL_MODEOnClose（CConnectionInterface*lpConnection）=0;
回调参数：
参数名称
参数说明
用法
CConnectionInterface*lpConnecti
升级会员 