消息流

本文介绍交易API推送消息的订阅、重推和处理方式。

订阅交易消息

登录成功后，调用 x1::XLTTradeApi::subscribe_trade_message 订阅交易消息。 每个 session_id 仅第一次调用有效。

using namespace x1;
XLTTradeApi* api;
 
// 选择订阅的消息类型（按位或组合）
trade_message_type_t msg_type = TradeMessageType::REPORT | TradeMessageType::ORDER_BOOK;
 
// 选择推送方式
api->subscribe_trade_message(session_id, request_id, msg_type, TradeResumeType::QUICK, 0);

消息类型（TradeMessageType）

通过 x1::trade_message_type_t 按位或组合指定需要订阅的消息类型：

类型	值	说明
REPORT	1	委托回报消息：申报成功、撤单成功、成交回报、委托失败、订单结束
RAW_REPORT	1<<1	交易所原始报文，需要用户自行解码
ORDER_BOOK	1<<2	订单簿消息：订单簿变动、资金变动、持仓变动

可同时订阅多种类型，例如：

trade_message_type_t msg_type = TradeMessageType::REPORT | TradeMessageType::ORDER_BOOK;

注意：资金划拨相关推送（\ref x1::XLTTradeSpi::on_counter_fund_transfer_request 等）在订阅任意消息类型后均会推送。

推送方式（TradeResumeType）

方式	说明
x1::TradeResumeType::RESTART	从本交易日日初开始推送
x1::TradeResumeType::QUICK	从最新数据开始推送（不回补历史）
x1::TradeResumeType::SPECIFY	从指定 start_sequence 开始推送

重推消息

如果需要重新拉取某个区间的历史消息，可调用 x1::XLTTradeApi::rebuild_trade_message ：

// 重推 sequence 101 ~ 200 之间的消息（从 start_sequence+1 开始推送）
api->rebuild_trade_message(session_id, request_id, msg_type, 100, 200);

重推的消息通过与正常订阅相同的回调接口推送，可通过 x1::xlt_msg_desc_t::is_rebuild 字段区分是否为重推消息。

委托回报消息（REPORT）

订阅掩码包含 REPORT 时，以下回调会被触发：

回调	触发时机	数据结构
x1::XLTTradeSpi::on_order_response	新订单申报成功（交易所已接受）	x1::xlt_order_response_t
x1::XLTTradeSpi::on_cancel_response	撤单成功	x1::xlt_cancel_response_t
x1::XLTTradeSpi::on_trade_report	成交回报	x1::xlt_trade_report_t
x1::XLTTradeSpi::on_order_error_response	委托失败（内部拒单/交易所拒单/废单/撤单失败）	x1::xlt_order_error_response_t
x1::XLTTradeSpi::on_order_end	订单到达终止状态（全成/全撤/废单等）	x1::xlt_order_end_t

特点：直接由交易所回报转换而来，推送速度快，适合需要快速获取订单响应/成交回报的场景。

注意：委托回报消息可能不包含交易费用等信息，本地计算资金/持仓时可能存在误差。

典型使用方式：

1）登录成功后获取日初资金和持仓：

• x1::XLTTradeApi::get_init_assets
• x1::XLTTradeApi::get_init_positions

2）订阅委托回报消息：

api->subscribe_trade_message(session_id, request_id, TradeMessageType::REPORT, TradeResumeType::QUICK, 0);

3）实现回调接口，在回调中更新本地订单、资金、持仓状态。

• x1::XLTTradeSpi::on_counter_fund_transfer_result
• x1::XLTTradeSpi::on_cluster_fund_transfer_result

委托回报消息处理时序：

订单簿消息（ORDER_BOOK）

订阅掩码包含 ORDER_BOOK 时，以下回调会被触发：

回调	触发时机	数据结构
x1::XLTTradeSpi::on_order_book_insert	新订单创建	x1::xlt_order_book_insert_t
x1::XLTTradeSpi::on_order_book_update	订单状态变更（申报响应/撤单/成交等）	x1::xlt_order_book_update_t
x1::XLTTradeSpi::on_order_book_error	订单错误（申报失败/撤单失败）	x1::xlt_order_book_error_t
x1::XLTTradeSpi::on_asset	资金变动	x1::xlt_asset_info_t
x1::XLTTradeSpi::on_position	持仓变动	x1::xlt_position_info_t

特点：将柜台订单簿、资金、持仓状态变动同步推送，用户通常不需要自行推导计算，仅需按推送更新本地状态。

注意：相对委托回报消息，推送速度略慢。

典型使用方式：

1）登录成功后获取日初资金和持仓：

• x1::XLTTradeApi::get_init_assets
• x1::XLTTradeApi::get_init_positions

2）订阅订单簿消息：

api->subscribe_trade_message(session_id, request_id, TradeMessageType::ORDER_BOOK, TradeResumeType::QUICK, 0);

3）实现回调接口，在回调中直接用推送数据更新本地订单、资金、持仓状态。

提示： x1::xlt_order_book_update_t 中的 x1::xlt_order_book_update_t::report_type 字段标识了本次变动的类型（申报成功/撤单成功/成交），对应 x1::xlt_order_book_update_t::report 联合体中的不同字段。

订单簿消息处理时序：

原始报文消息（RAW_REPORT）

订阅掩码包含 RAW_REPORT 时，交易所原始订单执行报告通过 x1::XLTTradeSpi::on_raw_report 推送。原始报文需要用户自行解码。

资金划拨消息

资金划拨相关消息在订阅任意消息类型后均会推送：

回调	触发时机
x1::XLTTradeSpi::on_fund_transfer_exec_result	资金划拨执行结果
x1::XLTTradeSpi::on_counter_fund_transfer_request	主柜资金划拨请求推送
x1::XLTTradeSpi::on_counter_fund_transfer_result	主柜资金划拨结果推送
x1::XLTTradeSpi::on_cluster_fund_transfer_request	双中心资金划拨请求推送
x1::XLTTradeSpi::on_cluster_fund_transfer_result	双中心资金划拨结果推送

消息描述（xlt_msg_desc_t）

每条推送消息都携带 x1::xlt_msg_desc_t 描述信息：

字段	说明
x1::xlt_msg_desc_t::account_index	账号索引
x1::xlt_msg_desc_t::sequence	消息序号，递增，用于断点续传。为0时不能作为续传标识（快速订单回报为0）
x1::xlt_msg_desc_t::is_rebuild	是否为重推消息：true 表示由 x1::XLTTradeApi::rebuild_trade_message 发起

关于 sequence 和断点续传的更多说明，参见 关键概念 。

同时订阅两类消息

REPORT 和 ORDER_BOOK 可以同时订阅：

trade_message_type_t msg_type = TradeMessageType::REPORT | TradeMessageType::ORDER_BOOK;
api->subscribe_trade_message(session_id, request_id, msg_type, TradeResumeType::QUICK, 0);

此时委托回报回调和订单簿回调会同时触发。两类消息独立推送，用户可根据业务需求选择一种或同时使用：

• 需要低延迟响应 → 使用 REPORT
• 需要完整状态同步 → 使用 ORDER_BOOK
• 同时使用 → 可对照两类消息做校验或互补