本文档介绍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);

后续的回报以及订单信息将带回此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

重要注意事项 ：

启用自定义订单序号后，用户必须确保每次下单时，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);

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

以下消息中包含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::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::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);
    }
}