| Xlight API用户手册 v1.5.1.2 Xlight极速柜台接口文档

载入中...
搜索中...
未找到
关键概念

本文档介绍xlt_api的核心概念。

# 委托源(client_id)

client_id 是客户端标识ID，取值范围[0, 255]，在登录时指定。

在本次登录session中进行的委托以及回报，系统都将打上此client_id标记，用于用户进行委托隔离。

例如，用户可以使用不同的client_id来区分不同的策略或客户端：

using namespace x1;
XLTApi *api;
// ... 省略初始化过程
// 相同账号，策略1使用client_id=1
api->login(request_id, 1, account_name, password, pub_key);
// 登录回调得到策略1的session_id, 如session_id_s1
// 相同账号，策略2使用client_id=2
api->login(request_id, 2, account_name, password, pub_key);
// 登录回调得到策略2的session_id, 如session_id_s2
// 策略1下单
xlt_order_insert_info_t order_info_1 = {};
uint64_t xid_1 = api->insert_order(session_id_s1, &order_info_1);
// 策略2下单
xlt_order_insert_info_t order_info_2 = {};
uint64_t xid_2 = api->insert_order(session_id_s2, &order_info_2);
x1::XLTApi
接口类
定义 xlt_api.h:350
x1::XLTApi::login
virtual bool login(uint64_t request_id, uint16_t client_id, const char *account_name, const char *password, const char *pub_key)=0
用户登请求
x1::XLTApi::insert_order
virtual uint64_t insert_order(uint64_t session_id, xlt_order_insert_info_t *order, uint64_t algo_mid=0)=0
委托
x1::xlt_order_insert_info_t
新订单请求数据结构
定义 xlt_trade_struct.h:17

后续的回报以及订单信息将带回此client_id:

- x1::xlt_order_response_t::client_id
- x1::xlt_trade_report_t::client_id
- x1::xlt_cancel_response_t::client_id
- x1::xlt_order_error_response_t::client_id
- x1::xlt_order_end_t::client_id
- x1::xlt_order_info_t::client_id

# 订单序号(order_sequence)

默认情况下，API会自动生成订单序号，用户无需关心订单序号的生成规则。

若用户启用自定义订单序号: config.set_order_seq_self_define(true) 见 配置API ，则用户在每次下单时，必须在 x1::xlt_order_insert_info_t 或 x1::xlt_cancel_order_info_t 结构体中指定 `order_sequence` 字段。

用户可以通过xid获取对应订单序号

using namespace x1;
XLTApi *api;
xlt_order_insert_info_t order_insert_info = {};
order_insert_info.order_sequence = 99; // 用户自定义序号
uint64_t xid = api->insert_order(session_id, &order_insert_info);
// xid为委托的时候返回的订单标识，在回报及订单信息中也会带回
uint64_t order_sequence = x1::XLTApi::get_order_sequence(xid); // order_sequence == 99
xlt_cancel_order_info_t cancel_order_info = {};
cancel_order_info.order_sequence = 500099; // 用户自定义序号
uint64_t cancel_xid = api->cancel_order(session_id, &cancel_order_info);
uint64_t cancel_order_sequence = x1::XLTApi::get_order_sequence(cancel_xid); // cancel_order_sequence == 500099
x1::XLTApi::cancel_order
virtual uint64_t cancel_order(uint64_t session_id, xlt_cancel_order_info_t *cancel_order, uint64_t algo_mid=0)=0
撤单
x1::XLTApi::get_order_sequence
static uint64_t get_order_sequence(uint64_t xid)
根据订单ID获取订单序列号
x1::xlt_cancel_order_info_t
撤单请求数据结构
定义 xlt_trade_struct.h:31
x1::xlt_cancel_order_info_t::order_sequence
uint64_t order_sequence
订单序号，当API配置中开启自定义模式时，由用户填写，session内不能重复，否则由系统生成，取值范围[1, 2^20-1]。
定义 xlt_trade_struct.h:32
x1::xlt_order_insert_info_t::order_sequence
uint64_t order_sequence
订单序号，当API配置中开启自定义模式时，由用户填写，session内不能重复，否则由系统生成，取值范围[1, 2^20-1]。
定义 xlt_trade_struct.h:18

重要注意事项 ：

- 启用自定义订单序号后，用户必须确保每次下单时，`order_sequence` 字段值唯一，否则可能导致重单，重单将没有任何响应
- `order_sequence` 字段取值范围[1, 2^20-1]
- 启用自定义订单序号后，建议委托和撤单使用不同的订单序号分段，以便管理委托和撤单，例如委托使用1~500000，撤单使用500001~1000000

# 请求标识(request_id)

request_id 用于用户在异步回调中定位对应的请求。

当XLTApi接口使用到request_id时，不对request_id做任何验证及业务假设，在回调中原样返回给用户。

用户可以根据实际业务场景自定义request_id，例如使用递增的序号、时间戳等：

using namespace x1;
XLTApi *api;
uint64_t next_request_id() {
static std::atomic<uint64_t> counter(0);
return ++counter;
}
uint64_t request_id = next_request_id();
api->login(request_id, client_id, account_name, password, pub_key);

# 回报消息序号(sequence)

sequence 柜台对交易消息进行全局唯一递增的编号，用于用户恢复数据时续传定位。

注意订阅回报数据指定sequence，柜台会从sequence的下一个sequence开始推送。

using namespace x1;
XLTApi *api;
// 此处省略正常初始化及登录操作
// 从指定序号开始订阅回报: TradeResumeType::SPECIFY
uint64_t last_sequence; // last_sequence为记录的最后一个序号
api->subscribe_report(global_session_id, TradeResumeType::SPECIFY, last_sequence);
x1::XLTApi::subscribe_report
virtual bool subscribe_report(uint64_t session_id, TradeResumeType resume_type, uint64_t start_sequence)=0
请求推送交易数据 每个session_id，仅第一次调用有效。

需要注意的是，回报消息sequence可能为0，此时表示快速返回交易所回报。故恢复数据断点续传时，需要根据 report_id 进行去重。

以下消息中包含sequence字段。

- x1::xlt_order_response_t::sequence
- x1::xlt_trade_report_t::sequence
- x1::xlt_cancel_response_t::sequence
- x1::xlt_order_error_response_t::sequence
- x1::xlt_order_end_t::sequence

# 回报消息唯一标识(report_id)

回报消息唯一标识为report_id, 32个字节长度， 非字符串

在单个API生命周期中，API回调会保证相同report_id只回调一次，但是在异常恢复情况下，用户重拉回报需要自行与本地持久化的回报根据此report_id进行去重。

若本地没有持久化，建议重启进程时从头开始拉取回报：

using namespace x1;
XLTApi *api;
// 此处省略正常初始化及登录操作
// 从头开始拉取回报: TradeResumeType::RESTART
api->subscribe_report(global_session_id, TradeResumeType::RESTART, 0);

以下消息中包含report_id字段。

- x1::xlt_order_response_t::report_id
- x1::xlt_trade_report_t::report_id
- x1::xlt_cancel_response_t::report_id
- x1::xlt_order_error_response_t::report_id
- x1::xlt_order_end_t::report_id

# 订单超时

订单超时 是指在指定时间内未收到订单的成交回报或状态更新时触发的通知。

订单超时不代表委托失败，需要用户自行查询确认订单状态。

可以通过 x1::XLTApiConfig::set_order_timeout() 设置订单超时时间（单位：秒）。

当订单超时时，会触发 x1::XLTTradeSpi::on_order_timeout() 回调：

void MyTradeSpi::on_order_timeout(uint64_t session_id, uint64_t xid) override {
// 订单超时，可以查询订单状态或重发订单
// 注意：超时不代表委托失败，需要查询确认
}

如果订单超时，用户可以选择调用 x1::XLTApi::resend_order_request() 接口重发订单。

重发订单，如果柜台已经处理第一次请求，重发上来的订单xid一样，会被识别为重复订单，重复订单将不会有任何响应。

# 请求超时

请求超时 是指查询请求在指定时间内没有收到任何响应时触发的通知。

可以通过 x1::XLTApiConfig::set_request_timeout() 设置请求超时时间（单位：秒）。

当请求超时时，会触发 x1::XLTTradeSpi::on_request_timeout() 回调：

void MyTradeSpi::on_request_timeout(uint64_t session_id, uint64_t request_id) override {
// 请求超时，可以重试查询
}

# 断线通知

当与服务器的连接异常断开时，会触发 x1::XLTTradeSpi::on_disconnect() 回调：

void MyTradeSpi::on_disconnect(uint64_t session_id) override {
// 断线通知，需要重新登录
// 注意：断线后需要重新调用login()方法建立连接并登录
}

注意：断线后需要重新调用 x1::XLTApi::login() 方法建立连接并登录。

# 分页查询

对于数据量较大的查询（如订单查询），API支持分页查询。

分页查询使用 x1::XLTApi::query_orders_by_page() 方法：

xlt_query_by_page_param_t page_param = {};
page_param.req_count = 100; // 每页数量
page_param.reference = 0; // 首次查询为0
uint64_t request_id = next_request_id();
api->query_orders_by_page(session_id, request_id, &page_param);
x1::XLTApi::query_orders_by_page
virtual bool query_orders_by_page(uint64_t session_id, uint64_t request_id, const xlt_query_by_page_param_t *page_query_param, uint64_t algo_mid=0)=0
分页请求查询报单
x1::xlt_query_by_page_param_t
分页查询请求参数
定义 xlt_data_type.h:194
x1::xlt_query_by_page_param_t::req_count
uint64_t req_count
分页查询条数，若填写小于1的值，则默认查询1条
定义 xlt_data_type.h:195
x1::xlt_query_by_page_param_t::reference
uint64_t reference
上一次收到的查询结果中带回来的索引，如果是从头查询，请置0
定义 xlt_data_type.h:196

查询结果通过 x1::XLTTradeSpi::on_query_orders_by_page() 回调返回，回调中包含 `query_reference` 字段，用于下一次分页查询：

void MyTradeSpi::on_query_orders_by_page(
uint64_t session_id, uint64_t request_id,
xlt_order_info_t order_infos[], uint64_t data_count,
uint64_t req_count, uint64_t rsp_count,
uint64_t query_reference, bool is_last,
xlt_error_info_t *error_info) override {
// 处理查询结果
// 如果is_last为true且rsp_count等于req_count，表示还有更多数据
if (is_last && rsp_count == req_count) {
// 进行下一次分页查询
xlt_query_by_page_param_t next_page_param = {};
next_page_param.req_count = req_count;
next_page_param.reference = query_reference; // 使用上次返回的reference
api->query_orders_by_page(session_id, next_request_id(), &next_page_param);
}
}
x1::xlt_error_info_t
错误信息
定义 xlt_data_type.h:173
x1::xlt_order_info_t
订单信息结构体
定义 xlt_trade_struct.h:114