XTP

通过 DolphinDB 的 XTP 插件，用户可以接收上交所、深交所以及北交所的实时行情，并将数据存储于 DolphinDB 的共享表中。可接收的数据如下表所示：


	指数	股票	基金	债券	期权
快照	有	有	有	有	有
逐笔	无	有	有	有	无
订单簿	无	有	有	有	无

本插件依赖中泰证券提供的第三方库 libxtpquoteapi.so，可参见文档链接 xtp-中泰证券。

安装插件

版本要求

DolphinDB Server 2.00.10 及更高版本，支持 Linux x64。

安装步骤

在 DolphinDB 客户端中使用 listRemotePlugins 命令查看插件仓库中的插件信息。
注意：仅展示当前操作系统和 server 版本支持的插件。若无预期插件，可自行编译（请选择对应分支下的插件）或在 DolphinDB 用户社区进行反馈。
```
login("admin", "123456")
listRemotePlugins()
```
使用 installPlugin 命令完成插件安装。
```
installPlugin("XTP")
```
使用 loadPlugin 命令加载插件。
```
loadPlugin("XTP")
```

接口说明

setGlobalConfig

语法

XTP::setGlobalConfig(clientId, saveFilePath, logLevel)

详情

设置一些全局配置项。在创建句柄前必须调用至少一次。无返回值。

参数

clientId INT 类型标量，1-99 之间取值，表示账户 ID。如果需要在多个 DolphinDB 进程中使用同一个账户去连接，则需要使用不同的 clientId。

saveFilePath STRING 类型标量，表示存储日志文件的目录，要求必须存在且有可写权限。

logLevel INT 类型标量，表示 xtp 记录日志的级别，0-5 之间取值，分别对应 FATAL ERROR WARNING INFO DEBUG TRACE 级别，默认是 3。

createXTPConnection

语法

XTP::createXTPConnection(name, config)

详情

返回一个连接句柄，可用于登录，订阅数据。

参数

name STRING 类型标量，连接句柄的唯一标识符，不能为空，也不能重复。

config 一个 key 类型为 STRING 的字典，包含如下所示的配置项：


配置项	值类型	说明
receiveTime	整型	可选参数，用于设定是否将接收到数据的时间并为表的最后一列，类型为 NANOTIMESTAMP。1：增加该列；其它不增加；默认不增加。

login

语法

XTP::login(conn, config)

详情

连接 XTP 服务器并登录。无返回值。

注意事项（摘自 XTP 官方文档）：

测试环境使用 TCP 的方式推送行情。由于带宽的限制，建议客户只订阅少量股票，否则会出现推送延时、断线等问题。
XPT 提供的 API 的默认日志级别是 DEBUG，需要调整到 INFO（或 ERROR），否则可能会导致丢包。本插件已将默认级别调整到 INFO，在调试时可以设置为 DEBUG。

参数

conn 由 createXTPConnection 接口返回的句柄。

config 一个 key 类型为 STRING 的字典，包含一些配置项：


配置项	值类型	说明
ip	字符串	服务器 IP 地址
port	整型	服务器端口号
localIP	字符串	可选参数，本地网卡地址，不能为空字符串
user	字符串	登录用户名
password	字符串	登录密码
protocalType	整型	1: TCP；2: UDP
heartBeatInterval	整型	可选参数，设置心跳检测时间间隔，单位为秒。默认填 30
udpBufferSize	整型	可选参数，UDP 方式连接时的缓冲区大小，可填 64，128，256，512，单位 MB，默认填 512
udpRecvCPUId	整型数组	可选参数，UDP 方式接收行情时，接受行情的线程绑定的 CPU 集合。绑核时，将从数组前面的核开始使用。不超过 10 个
udpParseCPUId	整型数组	可选参数，UDP 方式接收行情时，解析行情的线程绑定的 CPU 集合。绑核时，将从数组前面的核开始使用。不超过 10 个
udpOutputFlag	整型	可选参数，设定 UDP 方式接收行情时，是否输出异步日志。1：输出；其它不输出；默认不输出

语法

XTP::subscribe(conn, quotationType, marketType, codeList, tableDic)

详情

订阅行情数据，收到数据后存储到目标表中。无返回值。

注意事项：

订阅同一个行情类型时，在多次订阅上证、深证市场时，要求传入的 tableDic 相同，如果不同，则以第一次订阅传入的 tableDic 为准。
订阅同一个行情类型时，在多次订阅新三板市场时，要求传入的 tableDic 相同，如果不同，则以第一次订阅传入的 tableDic 为准。
订阅同一个行情类型时，市场类型如果已订阅了 4（上证+深证）则不能再次订阅 1（上证）或 2（深证）。
订阅同一个行情类型时，市场类型如果已订阅了 1（上证）或 2（深证）则不能再次订阅 4（上证+深证）。
如果 marketType 填为 4，则不能填 codeList。
各目标表的 schema 可以通过 getSchema 接口获取。
目标表要求是共享表。
公网测试环境仅供客户调试 API 接口，没有订单薄 OB 行情。

参数

conn 由 createXTPConnection 接口返回的句柄。

quotationType INT 类型标量，表示行情类型。1：快照，2：逐笔，3：订单簿。

marketType INT 类型标量，表示市场类型。1：上证， 2：深证，3：新三板，4：上证+深证。

codeList STRING 类型向量，表示合约 ID 数组。如果不填或者填空，则订阅全市场数据。

tableDic 一个字典，key 类型是 STRING，value 必须是共享表，用来指定输出表。根据行情类型的不同，输出表的数量也不同。如果空缺其中若干表，则相对应的行情会被丢弃，详情如下表所示：


行情类型	key	说明
快照	indexTable、optionTable、actualTable、bondTable	指数快照表、期权快照表、现货快照表（股票/基金等）、债券快照表
逐笔	entrustTable、tradeTable、statusTable	逐笔委托表、逐笔成交表、逐笔状态表
订单簿	orderBookTable	订单簿表

unsubscribe

语法

XTP::unsubscribe(conn, quotationType)

详情

取消订阅某个类型的行情数据。无返回值。

参数

conn 由 createXTPConnection 接口返回的句柄。

quotationType INT 类型标量，表示行情类型。1：快照；2：逐笔；3：订单簿。

getStatus

语法

XTP::getStatus([conn])

详情

获取订阅的状态信息。返回一个表，表结构如下所示：


列名	含义	类型
conn	连接名称	STRING
quotationType	订阅类型	STRING
startTime	订阅开始的时间	NANOTIMESTAMP
endTime	订阅结束的时间	NANOTIMESTAMP
lastMsgTime	最后一条消息收到的时间	NANOTIMESTAMP
processedMsgCount	已经处理的消息数	LONG
lastErrMsg	最后一条错误信息	STRING
failedMsgCount	处理失败的消息数	LONG
lastFailedTimestamp	最后一条错误消息发生的时间	NANOTIMESTAMP

参数

conn 由 createXTPConnection 接口返回的句柄，可选参数。如果不填，则返回当前所有连接的状态信息。

getHandle

语法

XTP::getHandle(name)

详情

返回由 name 指定的连接句柄。

参数

name STRING 类型标量，表示连接句柄的唯一标识符。

closeXTPConnection

语法

XTP::closeXTPConnection(conn)

详情

断开连接，销毁句柄。

参数

conn 由 createXTPConnection 接口返回的句柄。

getSchema

语法

XTP::getSchema(type, [needReceiveTime])

详情

返回可存储相应行情类型数据的表的结构。可选的 type 如下表所示：


type	含义
indexMarketData	指数快照表
optionMarketData	期权快照表
actualMarketData	现货快照表
bondMarketData	债券快照表
BSEMarketData	北交所数据表
entrust	逐笔委托表
trade	逐笔成交表
state	逐笔状态表
orderBook	订单簿表

参数

type STRING 类型标量，表示类型。

needReceiveTime BOOL 类型标量，可选参数，默认为 false,，表示是否需要包含 receiveTime 列。如果在 createXTPConnection 时指定了 receiveTime 配置，那么该参数须设置为 true。

使用示例

XTP::setGlobalConfig(11, "/path/to/log", 5)

stockConn = XTP::createXTPConnection("stockConn")

stockConfig = dict(STRING, ANY);
stockConfig["ip"] = "1.2.3.4";
stockConfig["port"] = 6002;
stockConfig["user"] = "3225";
stockConfig["password"] = "225";
stockConfig["protocalType"] = 1;    //1 是 TCP 2 是 UDP, 测试环境只有TCP
stockConfig["heartBeatInterval"] = 60;

XTP::login(stockConn, stockConfig)

tableDic = dict(STRING, ANY);
share  table(1:0, `exchangeID`ticker`lastPrice`qty`turnover`tradesCount`bids`asks`bidQty`askQty`dataTime, [INT, SYMBOL,DOUBLE, LONG,DOUBLE, LONG, DOUBLE[],DOUBLE[],LONG[],LONG[],TIMESTAMP]) as orderBookTable
tableDic["orderBookTable"] = orderBookTable

XTP::subscribe(stockConn, 3, 1, ["600250", "010504"], tableDic)
XTP::getStatus()
XTP::unsubscribe(stockConn, 3)

附录

在使用 createXTPConnection 接口时，可参考如下使用建议（请以 XTP 官方文档描述为准）：

如果需要连接多个 XTP 服务器，则需要创建多个句柄，用每个句柄连接不同的服务器。
在登录任一个 XTP 服务器之前，必须创建完毕所有句柄，即在登录后就不允许创建新的句柄，否则会抛出异常。