深证通信工程技术文档 FDEAPI 用户手册.docx
《深证通信工程技术文档 FDEAPI 用户手册.docx》由会员分享，可在线阅读，更多相关《深证通信工程技术文档 FDEAPI 用户手册.docx（81页珍藏版）》请在冰点文库上搜索。
深证通信工程技术文档FDEAPI用户手册
深证通信工程技术文档
FDEAPI用户手册
文档编号：
FDEP-FDEAPI-PUM001
文档密级：
外部公开
文档信息
文档名称
FDEAPI用户手册
说明
所属项目
金融数据交换平台
修订历史
日期
版本
修改人员
修改说明
20120725
1.0
利驿飞
完成初稿。
20140328
1.1
利驿飞
2.3节增加PersistEnable配置项的说
明。
20140507
1.2
利驿飞
2.3节增加非windows平台环境变量
MRAPI_LOGCONF_PATH的说明。
20140811
1.3
陈仲恒
增加6、7、8三章，对Java编程进行说明，并对4.3节中Mr2IsLinkOK和Mr2GetPeerUserStat两个函数进行了补
充说明。
20151116
1.4
利驿飞
第5节重写C++编程示例。
6.1.2节修正返回值“非0”表示成功。
6.1.6节修正返回值sourceUserID,sourceAppID,destUserID长度为32字节；修正返回值“NULL”表示为接收失败。
7.2.1节修正mrapi.java部分注释。
7.2.2节重写Java调用示例代码。
4.3.15Mr2GetPeerUserStat23
4.3.16调用顺序23
5C++编程示例24
6JAVA接口说明34
6.1.1方法清单34
6.1.2Mr2Init35
6.1.3Mr2IsLinkOK36
6.1.4Mr2CreatePkgID36
6.1.5Mr2Send37
6.1.6Mr2Receive139
6.1.7Mr2Receive340
6.1.8Mr2Destroy42
6.1.9Mr2GetVersion42
6.1.10Mr2RegRecvCondition42
6.1.11Mr2GetPeerUserStat44
6.1.12调用顺序44
7JAVA编程示例45
7.1示例说明45
7.2具体步骤45
7.2.1建立工程45
7.2.2示例代码49
8注意事项55
图索引
图1FDEAPI应用环境4
图2用户标识与应用标识5
图3FDEAPI主要函数调用顺序24
本文是金融数据交换平台客户端应用程序开发接口FDEAPI（FinancialDataExchangeApplicationProgrammingInterface）的使用手册。
主要说明使用FDEAPI进行开发的方法、各个API函数的功能、输入、输出等，以指导开发人员使用FDEAPI。
本文的读者为使用FDEAPI的开发人员、测试人员、维护人员等。
其他术语英文缩写：
FDEP：
FinancialDataExchangePlatform，金融数据交换平台。
FDSH：
FDEPSwitchingHub，金融数据交换平台的交换中枢。
FDSU：
FDEPSwitchingUnit，金融数据交换平台交换单元，BSSH的构成元素。
FDAP：
FDEPAccessPoint，金融数据交换平台的接入客户端。
FDMR：
FinancialMessageRouter，金融消息路由器，FDAP的构成元素。
FPG：
FinancialProtocolGateway，银证协议转换网关。
2安装及应用发布
2.1Windows平台
FDEAPI目前支持32位Windows2003和64位Windows2008操作系统。
Windows平台的FDEAPI由以下几个文件组成：
文件名
说明
mr2api.h
开发用头文件。
mrapi.dll
FDEAPI动态链接库，用FDEAPI开发的应用运行时用到。
mrapi_log.conf
日志配置文件。
使用FDEAPI进行开发，建议将以上全部文件拷贝到用户的可执行文件同一个目录下；也可以将dll文件拷贝到适当的路径下，将其它文件拷贝到开发环境相应的路径下。
发布FDEAPI应用时，请把mrapi.dll和mrapi_log.conf一起发布。
2.2其他平台
FDEAPI目前还支持64位Linux的RHELServer6.2的操作系统。
FDEAPI可根据用户环境要求进行定制，以支持其他平台上的开发和使用。
2.3关于配置的说明
FDEAPI在使用过程中，可以产生运行日志并记入日志文件。
。
[CONFIG]
PersistEnable=0
[LOG]
Type=1LockType=1Level=0Display=1LogDir=./log
LogName=mrapi.log
MaxFileCount=20MaxFileSize=500000000
配置文件mrapi_log.conf包含FDEAPI内部的一些控制参数，以及控制日志的产生和输出。
文件格式如下：
（1）PersistEnable控制FDEAPI发送数据包时Flag标志。
当没有该配置项或者PersistEnable=0时，Flag禁用MR2_MSGFLAG_PERSIST标志，即发送数据包时，MR2_MSGFLAG_PERSIST标志会被FDEAPI去掉；当PersistEnable=1时，Flag不会禁用MR2_MSGFLAG_PERSIST。
缺省值为0。
配置文件mrapi_log.conf默认没有该配置项。
（2）Type表示日志类型，其取值范围是1至2，缺省值为1。
1表示循环记录日志；2表示按日期记录日志。
（3）LockType表示写日志锁类型，其取值范围是1至2，缺省值为1。
1表示线程锁；2表示进程锁。
（4）Level表示日志的级别，其取值范围是0至10，缺省值为0。
0级日志信息最少，只报告错误和重要的运行信息，这也是正式运行时设置的级别；10级日志信息最多，包括所有的错误、警告和信息，一般只在程序调试错误时使用。
其它常用的级别还有1和5，其信息量中等。
（5）Display表示日志输出的方式，其取值范围是0至3，缺省值为1。
0表示不显示也不记录日志；1表示只在文件中记录日志；2表示只在屏幕上显示日志（只对控制台程序时有效）；3表示在文件中记录同时在屏幕上显示日志。
（6）LogDir表示日志文件的目录；
（7）LogName表示日志文件名称的前缀；
（8）MaxFileCount表示最大文件的数目，默认是20个。
假如LogName是mrapi.log，MaxFileCount是20，则日志文件文件名为mrapi.log、mrapi_01.log、mrapi_02.log、„„、mrapi_19.log。
其中mrapi.log是最新的日志文件，mrapi19.log是最旧的日志文件，更早的日志文件将自动被删除；
（9）MaxFileSize表示其中一个日志文件的大小，默认是500000000，约500MB；
在Windows环境下mrapi_log.conf需要和mrapi.dll放置在同一目录下；在非Windows平台环境下按照解包后的层次结构放置，若配置文件mrapi_log.conf不在mrapi动态链接库的同一级目录下，则需要设置环境变量“MRAPI_LOGCONF_PATH”为配置文件mrapi_log.conf的存放路径。
如果配置文件不存在，或者里面少配置了某个参数，则相应参数采用缺省值。
该配置文件的[LOG]关于日志的参数选项可以在使用FDEAPI的程序运行过程中动态修改，修改后30秒内生效。
[CONFIG]的参数选项只在FDEAPI初始化时才有效。
3使用概述
3.1功能
FDEAPI是一组提供给用户调用的C语言的应用程序编程接口，用户可以调用该API开发，实现与金融数据交换平台进行数据交换。
FDEAPI可以完成通信的自动连接、发送消息包、接收消息包、加密压缩等功能，应用程序可以用FDEAPI与金融数据交换平台的接入客户端实现交互。
3.2应用环境
FDEAPI
TCP
收发消息
接交
入
客TCP换
户SSL中
端枢
图1
FDEAPI应用环境
在金融数据交换平台中，接入客户端负责向交换中枢认证用户的身份，也负责与交换中枢建立安全的SSL连接，可靠的传输数据。
接入客户端向用户展现的FDEAPI不必再提供复杂的身份认证和加密机制。
3.3地址的标识
金融数据交换平台的基本功能是在用户间传输消息，每个消息都有一个源地址和一个目的地址。
金融数据交换平台的每个用户有一个唯一的用户标识（UserID），用户标识由不超过63个字符组成，字符可以是大写字母、小写字母、数字、减号或下划线，首字符必须是字母。
事实上，一个用户标识即对应一个接入客户端。
在用户处，一个接入客户端可以支持多个业务应用接入金融数据交换平台。
为了区分不同的应用，给每个应用一个唯一的应用标识（AppID），应用标识的命名规则和用户标识相同。
图2
用户标识与应用标识
消息是由具体的应用发出的，最终也要由具体的应用接收并处理。
因此，消息的源地址和目的地址都要用用户标识和应用标识两个要素共同表示。
一条消息有四个必需的地址要素：
源用户标识、源应用标识、目的用户标识、目的应用标识。
3.4线程安全性
FDEAPI中的所有函数都是线程安全的，用户可以根据需要生成多个与接入客户端FDAP连接的线程，同时与金融数据交换平台进行数据交换，以提高交换性能。
3.5应用系统的安全性
用户在其应用软件中调用了FDEAPI，在FDEAPI中不会包含故意攻击用户系统的软件或代码，不会故意影响用户系统的安全运行。
用户系统自身的安全性，应该由用户自己进行检查和维护，FDEAPI无法保证用户系统本身的安全性。
4编程参考
4.1常量定义
4.1.1
名称
定义值
说明
MR2_MSGFLAG_PERSIST
0x01
持久消息标志，用于可靠传输。
目前暂不支持
MR2_MSGFLAG_COMPRESS
0x02
压缩标志，需进行压缩传输。
MR2_MSGFLAG_REPLYTOME
0x04
应答包自动推送到发送方标志。
消息标志位常量
。
4.1.2长度常量
名称
定义值
说明
MR2_MAXLEN_ADDR
32
用户标识及应用标识的最大长度。
MR2_MAXLEN_PKGID
64
消息包标识的最大长度。
MR2_MAXLEN_USERDATA
256
用户保留数据的最大长度。
MR2_MAXLEN_MSGTYPE
256
消息类型标识的最大长度。
MR2_MAXLEN_IP
16
IP地址长度。
4.1.3函数返回错误值
对于Mr2Send、Mr2Receive*的各个函数的返回值，如果返回0，表示成功，否则表示错误，错误返回值在mr2api.h文件中已定义。
mr2api.h文件中函数错误返回值定义如下：
#define
MR2_ERRCODE_OK
0
#define
MR2_ERRCODE_PARAMERR
-1
#define
MR2_ERRCODE_CONNERR
-2
#define
MR2_ERRCODE_TIMEEXPIRED
-3
#define
MR2_ERRCODE_TIMEOUT
-4
#define
MR2_ERRCODE_NOMSG
-5
#define
MR2_ERRCODE_BUFTOOSHORT
-6
#define
MR2_ERRCODE_BUFTOOBIG
-7
#define
MR2_ERRCODE_SYSERROR
-8
#define
MR2_ERRCODE_COMMU_NOTALLOW
-9
#define
MR2_ERRCODE_DEST_NOTONLINE
-10
#define
MR2_ERRCODE_DEST_FULL
-11
4.2数据结构说明
4.2.1息属性STUMsgProperty2和
STUMultiDestMsgProperty
STUMsgProperty2结构用来表示一条单发消息的各种属性，
STUMultiDestMsgProperty结构用来表示一条群发消息的各种属性。
结构定义：
字段说明：
字段
说明
m_szSourceUserID
源用户标识，以“\0”结尾的字符串。
m_szSourceAppID
源应用标识，以“\0”结尾的字符串。
m_szDestUserID
目的用户标识，以“\0”结尾的字符串。
m_szDestAppID
目的应用标识，以“\0”结尾的字符串。
m_szPkgID
消息包的包标识，以“\0”结尾的字符串，或者由用户
调用MrCreatePkgID函数生成，或者为空（即’\0’）。
m_szCorrPkgID
相关包标识，以“\0”结尾的字符串，供用户自用。
m_szUserData1
用户数据1，以“\0”结尾的字符串，供用户自用。
m_szUserData2
用户数据2，以“\0”结尾的字符串，供用户自用。
m_ucFlag
消息标志，由8个二进制位组成，各位含义如下：
位0--为1表示持久消息，需可靠传输，暂不支持；
位1--为1表示消息需压缩传输；
位2--为1表示应答包会自动推送到发送方。
m_ucBizType
业务类型标志：
0～255。
m_ucPriority
优先级别标志：
3～5，5为最低，3为最高。
m_ucSensitiveLevel
敏感级别标志：
0～255，0为最低，255为最高。
m_szMsgType
消息类型标识，首字符‘M’为消息，‘F’为文件。
m_iDestUserCount
目的地址个数。
m_pArrDestUserAddr
包含m_iDestUserCount个目的地址的数组指针。
特殊说明：
m_szCorrPkgID、m_szUserData1、m_szUserData2三个字段是供用户自己使用的，金融数据交换平台本身不会使用这几个字段，也不会主动的改变它们。
消息包的压缩及解压由金融数据交换平台自动完成，对用户透明。
m_ucFlag的位0置1是通知金融数据交换平台对消息进行可靠传输；m_ucFlag的位1置1是通知金融数据交换平台对消息压缩后传输，用户通过FDEAPI接触到的消息包永远是非压缩的；m_ucFlag的位2置1是通知金融数据交换平台对应答包自动推送到发送方。
约定：
如果用户调用Mr2Send函数发送的是业务应答包，对于pMsgPropery参数中的m_szCorrPkgID字段，统一约定填写为与对应请求包中的m_szPkgID字段中相同的值，以方便请求方接收到应答包后，根据该字段查找对应的请求包。
对于业务请求包或者其它类型的包，该字段填写为空（即’\0’）。
4.2.2连接信息STUConnInfo2
该结构用来定义与接入客户端建立连接所需的各种信息。
结构定义：
字段说明：
字段
说明
m_szMRIP
接入客户端消息路由器的IP地址，以“\0”结尾的字符串，
格式为“xxx.xxx.xxx.xxx”。
m_usMRPort
接入客户端消息路由器的连接端口。
特殊说明：
该结构在调用Mr2Init函数时作为输入参数使用，用户需传入该结构的数组指针和数组元素个数。
Mr2Init首先尝试与结构数组中指定的第一个消息路由器连接，如不成功再尝试连接数组的下一个消息路由器。
接入客户端至少由两个消息路由器组成，可以有更多个。
使用FDEAPI时，只要指定连接其中一个消息路由器，会自动在接入客户端所有的消息路由器间进行负载均衡。
也就是说，应用程序最终连接的消息路由器可能不是该结构中指定的任何一个。
4.3函数接口
4.3.1函数清单
FDEAPI是一个简明易用的编程接口，它提供了如下14个函数：
序号
函数名称
函数功能
1
Mr2Init
初始化，获取相关资源，并尝试与接入客户
端FDAP建立连接。
2
Mr2Init2
初始化，获取相关资源，并尝试与接入客户端FDAP建立连接。
该函数与Mr2Init相比可以启动多个回调函数的线程，并且可以根
据设定接收的条件，比Mr2Init的功能更强。
3
Mr2IsLinkOK
查看并判断当前与接入客户端FDAP的连接
是否正常。
4
Mr2CreatePkgID
生成消息包标识。
5
Mr2Send
通过FDAP向消息中枢单发消息，请求转发。
6
Mr2MultiDestSend
通过FDAP向消息中枢群发消息，将在中枢
端分拆成多个独立的消息分别处理并转发。
7
Mr2Receive1
以方式1条件接收消息中枢转发来的消息。
8
Mr2Receive1_FreeBuf
释放Mr2Receive1函数调用中分配的内存。
9
Mr2Receive2
以方式2条件接收消息中枢转发来的消息。
10
Mr2Receive3
以方式3条件接收消息中枢转发来的消息。
11
Mr2Destroy
断开与FDAP的连接，释放相关资源。
12
Mr2GetVersion
取得该API的版本号。
13
Mr2RegRecvCondition
注册包下推条件，一次推送所有条件。
14
Mr2GetPeerUserStat
获取通信对端用户状态。
注意：
MRAPI动态链接库中也包含有MR开头的函数，是为了兼容旧版的接口而保留的；MR2开头的函数是新接口，新旧接口函数不可混用。
4.3.2Mr2Init
连接FDAP时的初始化函数。
该函数对FDEAPI进行初始化，分配获取相关资源，并尝试与接入客户端建立通信连接。
FDEAPI在调用此初始化函数时，会尝试使用TCP方式连接接入客户端，一般情况下，在该函数返回之前将连接成功。
如果接入客户端临时不可用，或者有网络问题，调用此函数返回时，可能还没有连接上接入客户端，由于FDEAPI具有断线重连的功能，该API内部将自动重试与对方进行连接。
函数原型：
void*_stdcallMr2Init（constchar*psAppID,constchar*psPasswd,int（*OnReceive2）（constchar*psPkg,intiPkgLen,
constSTUMsgProperty2*pMsgPropery,void*pvUserData）,
constSTUConnInfo2*pArrConnInfo,
intiArrConnInfoCount，void*pvUserData）;
参数说明：
参数
说明
psAppID[in]
本应用的应用标识。
psPasswd[in]
本应用在接入客户端设置的密码，密码必须与预设的
匹配才能继续。
OnReceive2[in]
接收到消息包时的回调函数。
该回调函数不能与下面的Mr2Receive1/Mr2Receive1_FreeBuf、Mr2Receive2
或Mr2Receive3/Mr2Receive1_FreeBuf同时使用。
pArrConnInfo[in]
接入客户端连接信息数组。
iArrConnInfoCount[in]
接入客户端连接信息数组元素个数。
pvUserData[in]
供回调函数使用的用户数据。
返回值说明：
返回值
说明
NULL
初始化失败。
非NULL
初始化成功，返回一个连接句柄，该句柄将作为其他函数调用
的参数。
4.3.3Mr2Init2
连接FDAP时的初始化函数。
该函数对FDEAPI进行初始化，分配获取相关资源，并尝试与接入客户端建立通信连接。
FDEAPI在调用此初始化函数时，会尝试使用TCP方式连接接入客户端，一般情况下，在该函数返回之前将连接成功。
如果接入客户端临时不可用，或者有网络问题，调用此函数返回时，可能还没有连接上接入客户端，由于FDEAPI具有断线重连的功能，该API内部将自动重试与对方进行连接。
该函数与Mr2Init函数的区别是：
（1）增加了最后一个参数iThreadCount，表示回调函数OnReceive2的线程个数（Mr2Init函数调用OnReceive2只有一个线程）；
（2）增加了一个参数pOnRecvMsgPropery，表示接收筛选条件并作为回调函数OnReceive2的一个输入参数；（3）返回的handle改为第一个参数，返回双指针。
函数原型：
void_stdcallMr2Init2（void**ppHandle,constchar*psAppID,
constchar*psAppPasswd,STUMsgProperty2*pOnRecvMsgPropery,int（*OnReceive2）（constchar*psPkg,intiPkgLen,
constSTUMsgProperty2*pMsgPropery,void*pvUserData）,constSTUConnInfo2*pArrConnInfo,intiArrConnInfoCount，void*pvUserData,intiThreadCount）;
参数说明：
参数
说明
ppHandle[out]
Mr2Init2函数返回的句柄，该句柄将作为其他函数
调用的参数。
psAppID[in]
本应用的应用标识。
psPasswd[in]
本应用在接入客户端设置的密码，密码必须与预设
的匹配才能继续。
pOnRecvMsgPropery[in]
这是回调函数OnReceive2的接收条件，如果不需要
任何条件，则可以填NULL
OnReceive2[in]
接收到消息包时的回调函数。
该回调函数不能与下面的Mr2Receive1/Mr2Receive1_FreeBuf、Mr2Receive2或Mr2Receive3/Mr2Receive1_FreeBuf
同时使用。
pArrConnInfo[in]
接入客户端连接信息。
i
升级会员 