NGES交易系统交易API和行情API接口规范.docVIP

1 nges 交易系统交易系统 交易交易 api 和行情和行情 api 接口规范接口规范 versionversion：1.201.20 发布日期：发布日期： 20092009 年年 6 6 月月 2020 日日 2 i修订记录、核准记录和审核记录修订记录、核准记录和审核记录 修订记录修订记录 版本编号版本编号修订日期修订日期主要修订摘要主要修订摘要 1.20-r0022009/5/4技术中心和技术公司：根据会员接入规范和 流程测试结果修改文档。 1.20-r0012008/12/4技术公司：增加灾备接口；增加主题查询接 口说明。 1.12-r0032008/01/28 技术公司：增加 restart、resume 和 quick 三种数据流恢复模式。 1.12-r0022007/12/17 技术部：合并 traderapi 和 mduserapi 文档， 调整部分章节内容。 1.12-r0012007/12/11 技术公司：增加了错误代码处理；增加了私 有流序列号设置功能；增加了前置机 nameserver 内容，但暂时不开放。 1.08-r0012007/8/31 上海期货交易所技术部：根据 nges v1.08 交易系统修改部分接口；提高压缩效率；增 加交易员私有流。 1.002006/8/11上海期货信息技术有限公司制定初稿。 核准记录核准记录 核准人员核准人员属于部门（单位）属于部门（单位）核准日期核准日期 严少辉严少辉技术中心技术中心2009/6/20 审核记录审核记录 审核人员审核人员属于部门（单位）属于部门（单位）审核日期审核日期 邹文军邹文军技术中心技术中心2009/5/20 文件制作和维护：上海期货交易所技术部；上海期货信息技术有限公司。文件制作和维护：上海期货交易所技术部；上海期货信息技术有限公司。 i 目目 录录 第一部分、第一部分、ngesnges 交易系统接口介绍交易系统接口介绍 4 4 1.1.介绍介绍4 4 1.1.背景.4 1.2.traderapi 简介4 1.3.mduserapi 简介 .4 1.4.traderapi/mduserapi 发行的平台.4 1.5.修改历史.4 1.5.1.版本 1.204 2.2.ftdftd 体系结构体系结构 4 4 2.1.通讯模式.4 2.2.数据流.4 3.3.接口模式接口模式4 4 3.1.traderapi 接口4 3.1.1.对话流和查询流编程接口4 3.1.2.私有流编程接口4 3.1.3.公共流编程接口4 3.2.mduserapi 接口 .4 3.2.1.对话流编程接口4 3.2.2.行情流编程接口4 4.4.运行模式运行模式4 4 4.1.工作流程.4 4.1.1.初始化阶段4 4.1.2.功能调用阶段4 4.2.工作线程.4 4.3.会员系统使用 traderapi 与交易系统的交互.4 4.4.与交易所前置系统的连接.4 4.5.本地文件.4 4.6.请求/应答日志文件4 4.7.可靠数据流的订阅方式.4 4.7.1.api 维护重传报文的序号 4 4.7.2.会员系统维护重传报文的序号4 4.8.心跳机制（heartbeat） .4 4.9.前置机列表.4 4.10.灾备接口.4 第二部分、第二部分、traderapitraderapi 参考手册参考手册 4 4 1.1.traderapitraderapi 接口分类接口分类 4 4 1.1.管理接口.4 1.2.业务接口.4 1.3.当前版本不开放的业务.4 2.2.traderapitraderapi 参考手册参考手册 4 4 2.1.cshfeftdctraderspi接口 4 2.1.1.onfrontconnected 方法.4 2.1.2.onfrontdisconnected 方法.4 2.1.3.onheartbeatwarning 方法4 2.1.4.onpackagestart 方法.4 2.1.5.onpackageend 方法4 2.1.6.onrspuserlogin 方法.4 ii 2.1.7.onrspuserlogout 方法4 2.1.8.onrspuserpasswordupdate 方法 4 2.1.9.onrspsubscribetopic 方法.4 2.1.10.onrspqrytopic 方法4 2.1.11.onrsperror 方法 4 2.1.12.onrsporderinsert 方法 4 2.1.13.onrsporderaction 方法.4 2.1.14.onrspquoteinsert 方法4 2.1.15.onrspquoteaction 方法4 2.1.16.onrspexecorderinsert 方法 4 2.1.17.onrspexecorderaction 方法.4 2.1.18.onrspqrypartaccount 方法.4 2.1.19.onrspqryorder 方法.4 2.1.20.onrspqryquote 方法.4 2.1.21.onrspqrytrade 方法.4 2.1.22.onrspqryclient 方法.4 2.1.23.onrspqrypartposition 方法.4 2.1.24.onrspqryclientposition 方法4 2.1.25.onrspqryinstrument 方法.4 2.1.26.onrspqryinstrumentstatus 方法 .4 2.1.27.onrspqrybulletin 方法4 2.1.28.onrspqrymarketdata 方法 .4 2.1.29.onrspqrymblmarketdata 方法.4 2.1.30.onrspqryhedgevolume 方法.4 2.1.31.onrtntrade 方法4 2.1.32.onrtnorder 方法4 2.1.33.onrtnquote 方法 .4 2.1.34.onrtnexecorder 方法4 2.1.35.onrtninstrumentstatus 方法4 2.1.36.onrtninsinstrument 方法.4 2.1.37.onrtndelinstrument 方法4 2.1.38.onrtninscombinationleg 方法.4 2.1.39.onrtndelcombinationleg 方法 4 2.1.40.onrtnbulletin 方法 4 2.1.41.onrtnaliasdefine 方法4 2.1.42.onrtnflowmessagecancel 方法.4 2.1.43.onerrrtnorderinsert 方法.4 2.1.44.onerrrtnorderaction 方法.4 2.1.45.onerrrtnquoteinsert 方法4 2.1.46.onerrrtnquoteaction 方法 4 2.1.47.onerrrtnexecorderinsert 方法.4 2.1.48.onerrrtnexecorderaction 方法.4 2.1.49.onrspcomborderinsert 方法4 2.1.50.onrspqrycomborder 方法 4 2.1.51.onrtncomborder 方法.4 2.1.52.onerrrtncomborderinsert 方法.4 2.2.cshfeftdctraderapi接口4 2.2.1.createftdctraderapi 方法.4 2.2.2.getversion 方法 4 iii 2.2.3.release 方法 .4 2.2.4.init 方法 4 2.2.5.join 方法.4 2.2.6.gettradingday 方法4 2.2.7.registerspi 方法.4 2.2.8.registerfront 方法4 2.2.9.registernameserver 方法.4 2.2.10.setheartbeattimeout 方法.4 2.2.11.openrequestlog 方法.4 2.2.12.openresponselog 方法 4 2.2.13.subscribeprivatetopic 方法 4 2.2.14.subscribepublictopic 方法4 2.2.15.subscribeusertopic 方法4 2.2.16.requserlogin 方法 4 2.2.17.requserlogout 方法 4 2.2.18.requserpasswordupdate 方法.4 2.2.19.reqsubscribetopic 方法 .4 2.2.20.reqqrytopic 方法.4 2.2.21.reqorderinsert 方法.4 2.2.22.reqorderaction 方法.4 2.2.23.reqquoteinsert 方法.4 2.2.24.reqquoteaction 方法.4 2.2.25.reqexecorderinsert 方法.4 2.2.26.reqexecorderaction 方法.4 2.2.27.reqqrypartaccount 方法.4 2.2.28.reqqryorder 方法4 2.2.29.reqqryquote 方法 .4 2.2.30.reqqrytrade 方法4 2.2.31.reqqryclient 方法 .4 2.2.32.reqqrypartposition 方法4 2.2.33.reqqryclientposition 方法 4 2.2.34.reqqryinstrument 方法4 2.2.35.reqqryinstrumentstatus 方法4 2.2.36.reqqrymarketdata 方法4 2.2.37.reqqrybulletin 方法 4 2.2.38.reqqrymblmarketdata 方法 .4 2.2.39.reqqryhedgevolume 方法4 2.2.40.reqcomborderinsert 方法4 2.2.41.reqqrycomborder 方法.4 3.3.traderapitraderapi 开发示例开发示例 4 4 第三部分、第三部分、mduserapimduserapi 参考手册参考手册 4 4 1.1.mduserapimduserapi 接口分类接口分类 4 4 1.1.管理接口.4 1.2.业务接口.4 2.2.mduserapimduserapi 参考手册参考手册 4 4 2.1.cshfeftdcmduserspi接口4 2.1.1.onfrontconnected 方法.4 2.1.2.onfrontdisconnected 方法.4 2.1.3.onheartbeatwarning 方法4 iv 2.1.4.onpackagestart 方法.4 2.1.5.onpackageend 方法4 2.1.6.onrspuserlogin 方法.4 2.1.7.onrspuserlogout 方法4 2.1.8.onrspsubscribetopic 方法.4 2.1.9.onrspqrytopic 方法4 2.1.10.onrsperror 方法 4 2.1.11.onrtndepthmarketdata 方法 4 2.2.cshfeftdcmduserapi接口.4 2.2.1.createftdcmduserapi 方法.4 3.1.1.getversion 方法 4 2.2.2.release 方法 .4 2.2.3.init 方法 4 2.2.4.join 方法.4 2.2.5.gettradingday 方法4 2.2.6.registerspi 方法.4 2.2.7.registerfront 方法4 3.1.2.registernameserver 方法.4 2.2.8.setheartbeattimeout 方法.4 2.2.9.subscribemarketdatatopic 方法.4 2.2.10.requserlogin 方法 4 2.2.11.requserlogout 方法 4 2.2.12.reqsubscribetopic 方法 .4 2.2.13.reqqrytopic 方法.4 3.3.mduserapimduserapi 开发示例开发示例 4 4 第四部分第四部分 附录附录4 4 1.1.错误编码列表错误编码列表4 4 2.2.枚举值列表枚举值列表4 4 3.3.数据类型列表数据类型列表4 4 第 1 页 第一部分、第一部分、nges 交易系统接口介绍交易系统接口介绍 本部分主要介绍 nges 交易系统的接口，包括： 第一章引入 nges 交易系统的两个接口，traderapi 用于会员系统下达交 易、控制和查询指令，接收私有流（含报单插入、报单操作响应和成交回报） 、 公共流（市场控制提示） 、响应流和查询流（查询结果） ；mduserapi 用于会员 系统和行情转发商系统接收行情流。 第二章介绍了两个 api 之后使用的通信协议 ftd（futures trading data exchange protocol） ，重点说明了数据流。 第三章介绍了两个 api 对应于不同类型应用的编程接口。 第四章介绍了 api 的工作模式，包括线程之间的通信、心跳机制和私有流 信息传输的可靠性实现。 作为 nges 交易系统的接口基础，traderapi 和 mduserapi 的用户应该仔 细阅读第一部分内容。 第 2 页 1. 介绍介绍 1.1.背景背景 上海期货交易所于 2006 年 11 月 3 日成功上线了“新一代交易所系统” （简 称 nges）的第一阶段项目，其中包括交易系统（简称 nges 交易系统） 。 nges 交易系统使用了开放的主流平台，可以运行在 unix 和 windows 操作系 统上。 在中国证监会信息中心的统一领导下，上海期货交易所（简称 shfe 或者 交易所） 、郑州商品交易所（简称 czce）和大连商品交易所（简称 dce）联合 研究了期货交易数据交换标准（futures trading data exchange protocol，简称 ftd 或者 ftd 协议） 。中国证监会于 2005 年 3 月 25 日发布了 ftd（jr/t 0016-2004） ，并于同日作为行业标准实施。 nges 交易系统本质上使用 ftd 作为会员远程交易的主接入协议；同时为 保持兼容和会员远程交易系统平稳切换，nges 交易系统支持原有基于 stratus 交易主机的 v1 和 v2 版本的接口（分别简称为 ofpv1 和 ofpv2） ；ofpv1 和 v2 在 nges 交易系统内部通过前置机实现了到 ftd 的翻译和转换。 和 ofpv1 和 v2 不同，ftd 协议体系较为复杂，为简化会员端远程交易系 统的开发难度，同时也为提高交易系统运行的可靠性，shfe 不建议会员的远 程交易系统（简称会员系统或者会员端）直接使用 ftd 协议接入 nges 交易系 统。为此，上海期货交易所发布了 nges 交易系统的交易 api 接口（简称 nges traderapi 或者 traderapi）和行情 api 接口（简称 nges mduserapi 或 者 mduserapi） 。 会员系统调用 traderapi 即可完成与 nges 交易系统的对接，接收到交易 所的报单和成交回报后 traderapi 将回调（callback）会员系统；会员系统或者 行情转发商（简称行情商） （会员和行情转发商接收交易所行情的系统统称为行 情接收端程序）系统调用 mduserapi 即可完成与 nges 交易系统的对接，接收 到交易所的行情后 mduserapi 将回调（callback）行情接收端程序（又称为行 情接收系统） 。 第 3 页 traderapi 把与 nges 交易系统之间复杂的协议转换、数据同步和网络通 信进行了封装。traderapi 通过建立一个基于 tcp 的虚链路通道与 nges 交易 系统交易前置机的连接，实现会员系统的报单等交易行为。通过 traderapi 建 立的连接通道具有多地址注册、断线自动重连和交易数据自动重传等特点。 mduserapi 与 traderapi 类似，建立一个基于 tcp 的虚链路通道与 nges 交易系统行情前置机的连接，实现行情的订阅和接收。 1.2.traderapi 简介简介 traderapi 是一个基于 c+的类库，通过使用和扩展类库提供的接口来实现 全部的交易功能，包括报单与报价的录入、报单与报价的撤销、报单与报价的 挂起、报单与报价的激活、报单与报价的修改、报单与报价的查询、成交单查 询、会员客户查询、会员持仓查询、客户持仓查询、合约查询、合约交易状态 查询、交易所公告查询。该类库包含以下 5 个文件： 文件名版本文件大小文件描述 ftdctraderapi.hv1.20交易接口头文件 ftdcuserapistruct.h v1.20 定义了 userapi 所需的一系列数据类 型的头文件 ftdcuserapidatatype. h v1.20 定义了一系列业务相关的数据结构的 头文件 traderapi.dllv1.20动态链接库二进制文件 traderapi.libv1.20导入库文件 支持 ms vc 6.0，ms vc.net 2003 编译器。需要打开多线程编译选项 /mt。 注意：注意：nges 交易系统支持许多新的报单指令（比如市价、最优价、组合 交易等） ，还支持新的交易品种（比如期权及其报价） ，但受现有交易规则限制， nges 交易系统并没有开放上述功能。会员系统在开发过程中需注意“当前版当前版 本不开放的业务本不开放的业务” ，同时在每个功能描述中的具体描述。 1.3.mduserapi 简介简介 mduserapi 也是一个基于 c+的类库，通过使用和扩展类库提供的接口来 第 4 页 实现全部的行情订阅和接收功能。该类库包含以下 5 个文件： 文件名版本文件大小文件描述 ftdcmduserapi.hv1.20行情接口头文件 ftdcuserapistruct.h v1.20 定义了 userapi 所需的一系列数据类 型的头文件 ftdcuserapidatatype. h v1.20 定义了一系列业务相关的数据结构的 头文件 mduserapi.dllv1.20动态链接库二进制文件 mduapi.libv1.20导入库文件 支持 ms vc 6.0，ms vc.net 2003 编译器。需要打开多线程编译选项 /mt。 1.4.traderapi/mduserapi 发行的平台发行的平台 目前发布了以下操作系统平台的版本： intel x86/windowsxp：包括.h 文件、.dll 文件和.lib 文件。 intel linux：包括.h 文件和.so 文件；在 redhat kernel 2.6.9-42 下完成编 译。 如果需要其他操作系统版本请和下面相关人员联系： 联系人：王君鹏联系人：王君鹏 电话：电话：+86-21-68400751 手机：手机：+86-0邮箱：邮箱： 1.5.修改历史修改历史 1.5.1. 版本版本 1.20 本版本基于nges 交易系统交易 api 和行情 api 接口规范 v1.12 r003 修改。主要有以下变更： 本版本提供了灾备功能： 增加【4.10 灾备接口】 ，简要说明了灾备原理。 第 5 页 由于登录报文中增加了数据中心代码，traderapi、mduserapi 修 改了 requserlogin 和 onrspuserlogin 方法的参数。 traderapi 中增加了“数据流回退通知”onrtnflowmessagecancel 方法的说明。 本版本提供了数据流长度的查询功能： 登录交易系统时，应答中会返回当前会员私有流长度和交易员私有 流长度。 traderapi、mduserapi 增加了对 reqqrytopic 和 rspqrytpoic 方 法说明，用于查询流长度。 对以前版本发现问题的修正： traderapi、mduserapi 增加了 getversion 方法说明，之前版本虽 提供功能但无文档说明。 mduserapi 增加了 registernameserver 方法说明，之前版本虽提供 功能但无文档说明。 修改了联系人，将周军改成王君鹏。 第 6 页 2. ftd 体系结构体系结构 会员和行情商的系统并不直接与 nges 交易系统的核心主机通信；从安全 隔离角度上看，会员和行情商甚至不能意识到有交易撮合主机和行情主机的存 在；会员和行情商只能连接到上述主机的两个代理服务器，分别是交易前置机 （简称交易前置，也被称为交易系统或交易所系统）和行情前置机（简称为行 情前置） 。交易前置机负责会员系统的交易业务，但不负责发送行情，此项功能 由行情前置机完成。 traderapi 使用建立在 tcp 协议之上的 ftd 协议与 nges 交易系统的前置 机通信。 mduserapi 使用建立在 tcp 协议之上的 ftd 协议与 nges 交易系统的行 情前置机通信。行情前置负责处理行情接收系统的行情订阅请求，并将所订阅 的行情推送到行情接收系统。 2.1.通讯模式通讯模式 ftd 协议中的所有通讯都基于某个通讯模式。通讯模式实际上就是通讯双 方协同工作的方式。 ftd 涉及的通讯模式共有三种： 对话通讯模式 私有通讯模式 广播通讯模式 对话通讯模式是指由会员系统主动发起的通讯请求。该请求被交易系统接 收和处理，并给予响应。例如报单、查询等。这种通讯模式与普通的客户/服务 器模式相同。 私有通讯模式是指交易系统主动，向某个特定的会员或者特定会员的某个 特定交易员发出的信息。例如成交回报等。 广播通讯模式是指交易系统主动，向市场中的所有会员都发出相同的信息。 例如公告、市场公共信息等。 第 7 页 通讯模式和网络的连接不一定存在简单的一对一的关系。也就是说，一个 网络连接中可能传送多种不同通讯模式的报文，一种通讯模式的报文也可以在 多个不同的连接中传送。 无论哪种通讯模式，其通讯过程都如图 1 所示： 会员系统交易所系统 发送请求(如果在对话模式下) 给出响应(如果在对话模式下) 连接请求 连接确认 身份认证请求 身份认证响应 发出私有信息(如果在私有模式下) 发出市场公告(如果在市场模式下) 断开请求 断开确认 图表图表 1各通讯模式的工作过程各通讯模式的工作过程 第 8 页 2.2.数据流数据流 交易前置支持对话通讯模式、私有通讯模式、广播通讯模式。行情前置的 行情转发功能支持对话通讯模式、广播通讯模式。 1、对话通讯模式、对话通讯模式 对话通讯模式下支持对话数据流和查询数据流。 对话数据流是一个双向数据流，会员系统发送交易请求，交易系统反馈应 答。交易系统不维护对话流的状态。系统故障时，对话数据流会重置，在途的 数据可能会丢失。 查询数据流是一个双向数据流，会员系统发送查询请求，交易系统反馈应 答。交易系统不维护查询流的状态。系统故障时，查询数据流会重置，在途的 数据可能会丢失。 2、私有通讯模式、私有通讯模式 在私有通讯模式下，数据流是可靠的。在一个交易日内，会员系统断线后 恢复连接时，可以请求交易系统发送指定序号之后的私有数据流数据。私有数 据流向会员系统提供报单状态报告、成交回报更等信息。私有数据流分为会员 私有流和交易员私有流两种。 交易系统维护每个会员的私有流，有关该会员的回报信息，如报单回报、 成交回报等都通过会员私有流下发。交易员要有足够的权限才可以订阅会员私 有流。 交易员私有流与会员私有流类似，但只包含该交易员发起的交易引发的回 报信息。每个交易员都可以订阅自已的交易员私有流。 3、广播通讯模式、广播通讯模式 广播通讯模式下支持公共数据流。 公共数据流是一个单向数据流，由交易系统或者行情系统发向会员系统， 用于发送市场公共信息；公共数据流是一个可靠的数据流，交易系统维护整个 系统的公共数据流，在一个交易日内，会员系统断线恢复连接时，可以请求交 易系统发送指定序号之后的公共数据流数据。 以行情为例，行情数据流是一个公共数据流，由行情发布系统发向会员系 统，用于发送行情信息；行情流是一个可靠的数据流，交易系统维护整个系统 第 9 页 的行情流，在一个交易日内，行情接收系统断线恢复连接时，可以请求交易系 统发送指定序号之后的行情流数据。 交易系统所提供的行情内容是按照主题组织的。每个主题包括一组合约的 行情，还包括了行情发布内容和发布方式，包括行情深度、采样频率、延迟时 间等。交易所会公布各行情主题的具体内容，并设定每个行情用户所能订阅的 行情主题。每个行情主题对应着一个行情流。 要获得行情通知，行情接收系统必需在连接行情前置后，订阅一个或多个 行情发布主题。 第 10 页 3. 接口模式接口模式 3.1.traderapi 接口接口 traderapi 提供了二个接口，分别为 cshfeftdctraderapi 和 cshfeftdctraderspi。这两个接口是对 ftd 协议的封装。 会员系统可以通过 cshfeftdctraderapi 发出操作请求，通过继承 cshfeftdctraderspi 并重载回调函数来处理交易系统的回复或响应。 3.1.1. 对话流和查询流编程接口对话流和查询流编程接口 通过对话流进行通讯的编程接口通常如下： /请求：请求： int cshfeftdctraderapi:reqxxx( cshfeftdcxxxfield *preqxxx, int nrequestid) /响应：响应： void cshfeftdctraderspi:onrspxxx( cshfeftdcxxxfield *prspxxx, cshfeftdcrspinfofield *prspinfo, int nrequestid, bool bislast) 其中请求接口第一个参数为请求的内容，不能为空。该参数根据请求命令 的不同使用具有不同的类，该类的成员变量的类型和合法的数值请参阅附录中 的“枚举值列表枚举值列表”和“数据类型列表数据类型列表” 。 请求接口的第二个参数为请求号。请求号由会员系统负责维护，交易所建 议每个请求的请求号不会重复。在接收交易系统的响应时，可以得到当时发出 请求时填写的请求号，从而可以将响应与请求对应起来。 当收到交易系统应答时，cshfeftdctraderspi 的回调函数会被调用。如果响 应数据不止一个，则回调函数会被多次调用。 第 11 页 回调函数一共包含四个参数。其中： 第一个参数为响应的具体数据，如果出错或没有结果有可能为 null。 第二个参数为处理结果，表明本次请求的处理结果是成功还是失败。在发生多次 回调时，除了第一次回调，其它的回调该参数都可能为 null。 第三个参数为请求号，即原来发出请求时填写的请求号。 第四个参数为响应结束标志，表明是否是本次响应的最后一次回调。 3.1.2. 私有流编程接口私有流编程接口 私有流中的数据为会员或者交易员的私有信息，包括报单回报、成交回报、 报价回报、执行宣告回报等。 通过私有流接收回报的编程接口通常如下： void cshfeftdctraderspi:onrtnxxx(cshfeftdcxxxfield *pxxx)； /或者或者 void cshfeftdctraderspi:onerrrtnxxx(cshfeftdcxxxfield *pxxx, cshfeftdcrspinfofield *prspinfo); 当收到交易系统通过私有流发布的回报数据时，cshfeftdctraderspi 的回调 函数会被调用。回调函数的参数为回报的具体内容。 3.1.3. 公共流编程接口公共流编程接口 公共流中的数据中交易所的公共信息，包括合约、公告等。 通过公共流接收回报的编程接口通常如下： void cshfeftdctraderspi:onrtnxxx(cshfeftdcxxxfield *pxxx)； 当收到交易系统通过公共流发布的回报数据时，cshfeftdctraderspi 的回调 函数会被调用。回调函数的参数为通知的具体内容。 3.2.mduserapi 接口接口 与 traderapi 类似，mduserapi 提供了二个接口，分别为 cshfeftdcmduserapi 和 cshfeftdcmduserspi。这两个接口是对 ftd 协议的封装。 第 12 页 行情接收系统可以通过 cshfeftdcmduserapi 发出操作请求，通继承 cshfeftdcmduserspi 并重载回调函数来处理交易系统的响应。 3.2.1. 对话流编程接口对话流编程接口 通过对话流进行通讯的编程接口通常如下： /请求：请求： int cshfeftdcmduserapi:reqxxx( cshfeftdcxxxfield *preqxxx, int nrequestid) /响应：响应： void cshfeftdcmduserspi:onrspxxx( cshfeftdcxxxfield *prspxxx, cshfeftdcrspinfofield *prspinfo, int nrequestid, bool bislast) 其中请求接口第一个参数为请求的内容，不能为空。 请求接口的第二个参数为请求号。请求号由行情接收系统应用程序负责维 护，正常情况下每个请求的请求号不会重复。在接收交易系统的响应时，可以 得到当时发出请求时填写的请求号，从而可以将响应与请求对应起来。 当收到交易系统应答时，cshfeftdcmduserspi 的回调函数会被调用。如果 响应数据不止一个，则回调函数会被多次调用。 回调函数一共包含四个参数。其中： 第一个参数为响应的具体数据，如果出错或没有结果有可能为 null。 第二个参数为处理结果，表明本次请求的处理结果是成功还是失败。在发 生多次回调时，除了第一次回调，其它的回调该参数都可能为 null。 第三个参数为请求号，即原来发出请求时填写的请求号。 第四个参数为响应结束标志，表明是否是本次响应的最后一次回调。 第 13 页 3.2.2. 行情流编程接口行情流编程接口 行情流中的数据包含了交易系统推出的行情信息。 通过行情流接收回报的编程接口通常如下： void cshfeftdcmduserspi:onrtnxxx(cshfeftdcxxxfield *pxxx)； 当收到交易系统通过行情流发布的行情数据时，cshfeftdcmduserspi 的回 调函数会被调用。回调函数的参数为通知的具体内容。 第 14 页 4. 运行模式运行模式 4.1.工作流程工作流程 会员系统/行情接收系统和交易系统的交互过程分为 2 个阶段：初始化阶段 和功能调用阶段。 4.1.1. 初始化阶段初始化阶段 在初始化阶段，会员系统/行情接收系统的程序必须完成如下步骤（具体代 码请参考开发实例）： 顺序会员系统行情接收系统 1产生一个 cshfeftdctraderapi 实例；产生一个 cshfeftdcmduserapi 实例； 2产生一个事件处理的实例；产生一个事件处理的实例； 3注册一个事件处理的实例； 注册一个事件处理的实例； 4订阅私有流； 订阅公共流； 订阅行情流； 5设置交易前置 nameserver 的网络地址。 1 设置行情服务 nameserver 的网络地址。 1 6 初始化 初始化 1为了保持与上一版的兼容性，api 仍然提供了注册交易前置（行情服务）的接口，但交 易所建议不要使用这些接口，这些接口将在下一版本中取消。有关 nameserver 的说明参见 4.9 前置机列表。 4.1.2. 功能调用阶段功能调用阶段 在功能调用阶段，会员系统可以任意调用交易接口中的请求方法，如 requserlogin、reqorderinsert 等，同时提供回调函数以响应回报信息。注意事 项： 1.api 请求的输入参数不能为 null。 第 15 页 2.api 请求的返回参数，0 表示正确，其他表示错误，详细错误编码请查 表。 4.2.工作线程工作线程 会员/行情接收系统应用程序至少由两个线程组成，一个是应用程序主线程， 一个是 api 工作线程（traderapi 或者 mduserapi） 。应用程序与交易或者行情 前置的通信是由 api 工作线程驱动的。 cshfeftdctraderapi 和 cshfeftdcmduserapi 提供的接口是线程安全的，可 以有多个应用程序线程同时发出请求。 cshfeftdctraderspi 提供的接口回调是由 traderapi 工作线程驱动，通过实 现 spi 中的接口方法，从交易前置收取所需数据。 cshfeftdcmduserspi 提供的接口回调是由 mduserapi 工作线程驱动，通过 实现 spi 中的接口方法，从行情前置收取所需数据。 如果重载的会员系统的应用程序的某个回调函数阻塞，则等于阻塞了 traderapi 或者 mduserapi 工作线程，api 与交易/行情前置的通信会停止，因 此通常应该迅速返回。在 cshfeftdctraderspi 和 cshfeftdcmduserspi 派生类的 回调函数中，可以利用将数据放入缓冲区或通过 windows 的消息机制来实现迅 速返回。 第 16 页 spi对象 api请求的应答 委托修改信息 成交信息 错误委托信息 合约资料修改信息 等等 交易前置 api对象 登陆请求 委托请求 查询请求 等等api请求 会员报盘程序 spi对象 行情信息 行情前置 api对象 登陆请求 订阅请求 行情接收系统 图表图表 2 traderapi工作线程工作线程图表图表 3 mduserapi工作线程工作线程 4.3.会员系统使用会员系统使用 traderapi 与交易系统的交互与交易系统的交互 会员系统通过 traderapi 与交易系统交互。会员系统的请求通过 traderapi 发送到交易系统；交易系统返回的应答和回报通过 traderapi 返回给会员系统。 traderapi 的交易接口和私有流接口会有相互关联，如用户报单录入 reqorderinsert，马上会收到报单响应 onrsporderinsert，说明交易系统已经收 到报单。报单进入交易系统后，如果报单的交易状态发生变化，就会收到报单 回报 onrtnorder。如果报单被撮合(包括全部成交和部分成交)，就会收到成交 回报 onrtntrade。其中，一个用户的报单回报和成交回报也会被所属会员下其 他的交易员接收到（如果该用户不使用仅接收交易员私有流方式登录） 。 以交易员日常交易为例，有两个会员系统 a 和 b，发生的事件包括： 1交易员 a 报单，cu0711，买，20 手，64000 元； cshfeftdctraderapi:reqorderinsert：报单录入请求。本函数由会员系统的应 用主线程调用，通过对话流发送到 nges 交易系统前置机。 第 17 页 交易系统报单处理：报单系统编号为 1；由于此时撮合队列中无对手，报单状态为“未成 交还在队列中” 。nges 交易系统的前置机发出报单响应给交易员 a 的对话流；发出报单 回报给交易员 a 的私有流和交易员 a 所属会员的私有流。响应和回报的报文由 traderapi 工作线程处理并调用 spi 对象的方法。 cshfeftdctraderspi:onrsqorderinsert：交易所的交易前置给出请求的应答， 内容为：录入成功，本地编号为 1 的报单的系统编号为 1。本函数由 traderapi 工作线 程在收到交易前置应答后调用。 cshfeftdctraderspi:onrtnorder：交易所的交易前置立即在交易员 a 所属会员的 私有流中或者交易员 a 的私有流中给出报单回报，因其他席位无法获得报单的具体信息， 为保持信息同步，因此回报内容包括报单的状态等报单的全部内容。本函数由 traderapi 工作线程在收到交易前置的报单回报后调用。如果会员 a 还有其他交易员连 接并登录到交易系统，并且接收会员私有流，将收到相同的报单回报（以下同） 。 2交易员 b 报单，cu0711，卖，10 手，64000 元； cshfeftdctraderapi:reqorderinsert：报单录入请求。 交易系统报单处理：报单系统编号为 2；由于此时撮合队列中无对手，报单状态为“未成 交还在队列中” 。 交易系统报单处理：报单系统编号为 2；尝试撮合并能成交，因此报单状态为“完全成交” 。nges 交易系统的前置机发出报单响应给交易员 b 的对话流；发出报单回报给交易员 b 的私有流和交易员 b 所属的会员私有流；发出报单回报给交易员 a 的私有流和交易员 a 所属会员的私有流，提示系统编号为 1 的报单状态交易系统已经修改为“部分成交还在队 列中” ，报单的“剩余数量”调整为 10 手；发出成交回报给交易员 b 的私有流和交易员 b 所属的会员私有流；发出成交回报给交易员 b 的私有流和交易员 b 所属的会员私有流。 nges 交易系统将确保报单的回报在成交回报之前送达会员系统，并且报单回报中的交易系统将确保报单的回报在成交回报之前送达会员系统，并且报单回报中的“剩剩 余数量余数量”字段已经反映交易系统报单簿中的最新数量，没有必要再根据成交回报的数量再字段已经反映交易系统报单簿中的最新数量，没有必要再根据成交回报的数量再 调整。调整。 cshfeftdctraderspi:onrsqorderinsert：交易所的交易前置给出请求的应答， 内容为：录入成功，本地编号为 1 的报单的系统编号为 2。 cshfeftdctraderspi:onrtnorder：交易所的交易前置立即在交易员 b 所属会员的 私有流中或者交易员 b 的私有流中给出报单回报，报单状态为“完全成交” 。 cshfeftdctraderspi:onrtnorder：交易所的交易前置立即在交易员 a 所属会员的 第 18 页 私有流中或者交易员 a 的私有流中给出报单回报，报单状态为“部分成交还在队列中” ， 剩余数量为 10 手。 cshfeftdctraderspi:onrtntrade：交易所的交易前置立即在交易员 a 所属会员的 私有流中或者交易员 a 的私有流中给出成交回报。 cshfeftdctraderspi:onrtntrade：交易所的交易前置立即在交易员 b 所属会员的 私有流中或者交易员 b 的私有流中给出成交回报。 3交易员 a 撤单； 下图说明了会员系统、traderapi 和交易系统之间的 uml 交互图。 交易员api交易所交易系统交易员api 报单请求:本地号=1,cu0711,买,20手,64000元 报单应答:成功,本地号=1,系统号=1 报单回报:系统号=1,本地号=1,状态=未成交还在队列中 处理报单 报单请求:本地号=1,cu0711,卖,10手,64000元 处理报单 报单应答:成功,本地号=1,系统号=2 报单回报:系统号=1,本地号=1,状态=部分成交还在队列中 成交回报:成交号=1,系统号=1,本地号=1 报单回报:系统号=2,本地号=1,状态=完全成交 成交回报:成交号=1,系统号=2,本地号=1 撤单请求:系统号=1 撤单应答:成功 报单回报:系统号=1,本地号=1,状态=已撤单 处理撤单 说明: 会员系统a cshfeftdctraderapi:reqorderinsert cshfeftdctraderspi:onrsporderinsert cshfeftdctraderspi:onrtnorder cshfeftdctraderspi:onrtnorder cshfeftdctraderspi:onrtntrade cshfeftdctraderspi:onrsporderaction cshfeftdctraderapi:reqorderaction 会员系统b cshfeftdctraderapi:reqorderinsert cshfeftdctraderspi:onrsporderinsert cshfeftdctraderspi:onrtnorder cshfeftdctraderspi:onrtntrade 响应流私有流 图表图表 4会员系统与交易系统信息交互示例会员系统与交易系统信息交互示例 4.4.与交易所前置系统的连接与交易所前置系统的连接 traderapi 和 mduserapi 使用建立在 tcp 协议之上的 ftd 协议与交易所的 交易/行情前置系统进行通信。traderapi 使用 cshfeftdctraderapi:registerfront 方法注册交易所前置系统的网络地址。mduserapi 使用 cshfeftdcmduserapi: registerfront 方法注册交易所行情前置系统的网络通讯地址。 交易所拥有多个交易/行情前置系统，用于负载均衡且互为备份，从而提高 第 19 页 系统的性能和可靠性。为保证交易时通信的可靠性，traderapi 和 mduserapi 可以注册多个前置。api 在初始化后，会从已注册的前置中随机挑选一个前置， 尝试建立网络连接，如果不成功，则依次逐个尝试其它前置，直到连接成功为 止。如果在交易过程中网络连接出现故障， api 依然使用上述过程，尝试连接 其它前置。 上海期货交易所将公布至少两台前置机的网络地址（位于上海期货大厦数 据中心） ，因此会员系统应该至少注册两个前置机的网络地址以防止所连交易前 置发生故障从而引发单点隐患。上海期货交易所正在建设张江灾备中心，届时 将发布另外至少两台前置机的网络地址（位于张江数据中心） 。鉴于 ftd 协议 的带宽要求比 ofpv1 和 ofpv2 高，建议会员使用 128k 以上 ddn 专线或者 2m sdh 数字专线。上海期货交易所和中国金融期货交易所将共享会员远程交 易网络接入：直接连接上海期货交易所的链路可以作为备份链路接入中国金融 期货交易所；反之亦然。 4.5.本地文件本地文件 traderapi 在运行过程中，会将一些数据写入本地文件中。调用 createftdctraderapi 函数，可以传递一个参数，指明存贮本地文件的路径。该 路径必须在运行前已创建好。本地文件的扩展名都是“.con” 。 mduserapi