行情API使用指南

本文介绍行情API的完整业务流程，从初始化、登录、订阅行情、到行情数据处理、查询等。

业务流程概览

典型的行情API使用流程如下：

1. 创建API实例（x1::XLTQuoteApi::create）
2. 配置参数（x1::XLTQuoteConfig）
3. 初始化（x1::XLTQuoteApi::initialize）
4. 登录（x1::XLTQuoteApi::login）
5. 订阅行情（x1::XLTQuoteApi::subscribe_quote）
6. 在回调中接收并处理行情数据（x1::XLTQuoteSpi::on_quote）
7. 按需查询静态信息 / Level1行情 / 回补逐笔

创建与初始化

首先创建API实例，然后配置参数并初始化。API实例只能创建一次，初始化也只能调用一次。

using namespace x1;
 
// 1. 创建API实例
XLTQuoteApi* api = XLTQuoteApi::create();
 
// 2. 配置参数
XLTQuoteConfig config;
config.set_trading_day(20260402);                            // 设置交易日（必填）
config.set_local_addr(                                       //（必填）设置本地网卡IP地址。生产环境中，quote对应网卡建议为solarflare网卡，solarflare网卡将自动使用ef_vi，以便达到最优的性能，非solarflare网卡则回退到内核sock模式
    "172.16.10.155",                                         // agw 连接agw的本地网卡IP，生产环境需为AGW接入网段IP
    "172.16.10.155"                                          // quote 接收行情的本地网卡IP，生产环境需为行情网段IP
    );
config.add_agw_addr("192.168.5.215", 6060);                  // 添加AGW地址（必填，可多次调用）
 
// 3. 初始化：传入配置和回调对象
MyQuoteSpi spi;  // 继承自 XLTQuoteSpi 的用户实现类
if (!api->initialize(&config, &spi)) {
    xlt_error_info_t err = XLTQuoteApi::get_last_error();
    // 处理初始化失败
}

登录

登录请求为异步操作，调用 x1::XLTQuoteApi::login 发起请求后，通过 x1::XLTQuoteSpi::on_login 回调获取结果。登录成功后返回 session_id，后续所有接口调用都需要使用此 session_id。

行情API只能登录一次，如果需要重新登录，需要先调用 x1::XLTQuoteApi::logout 登出。

uint64_t request_id = 1;
uint16_t client_id = 1;
const char* account = "88888888888801";
const char* password = "12345678";
const char* pub_key = "XXXXXXXXXXXXXX";
 
api->login(request_id, client_id, account, password, pub_key);

登录回调处理：

void MyQuoteSpi::on_login(uint64_t session_id, uint64_t request_id,
                          const xlt_error_info_t* error_info) {
    if (error_info && error_info->error_code_type != 0) {
        // 登录失败
        return;
    }
    // 登录成功，保存 session_id
    session_id_ = session_id;
}

订阅行情

登录成功后，调用 x1::XLTQuoteApi::subscribe_quote 订阅行情数据。需要配置行情接收线程，每个线程可绑定CPU核心并指定负责接收的行情组播类型。

行情接收线程配置

通过 x1::quote_thread_t 结构体配置每个行情接收线程：

字段	说明
x1::quote_thread_t::cpu_affinity	CPU亲和力，-1 表示不绑核，0 表示绑定到CPU0，以此类推
x1::quote_thread_t::mc_count	本线程负责接收的行情组播数量
x1::quote_thread_t::mc_types	行情组播类型列表（x1::QuoteMCType）

行情组播类型（QuoteMCType）

类型	说明
XLT_SSE_L1	Xlight上交所L1行情
XLT_SZSE_L1	Xlight深交所L1行情
HPF_SSE_L2_STOCK_SNAP	盛立上交所L2股票快照
HPF_SSE_L2_STOCK_TICK	盛立上交所L2股票逐笔
HPF_SSE_L2_INDEX	盛立上交所L2指数快照
HPF_SSE_L2_BOND_SNAP	盛立上交所L2债券快照
HPF_SSE_L2_BOND_TICK	盛立上交所L2债券逐笔
HPF_SZSE_L2_STOCK_SNAP	盛立深交所L2股票快照
HPF_SZSE_L2_STOCK_TICK	盛立深交所L2股票逐笔
HPF_SZSE_L2_INDEX	盛立深交所L2指数快照
HPF_SZSE_L2_BOND_SNAP	盛立深交所L2债券快照
HPF_SZSE_L2_BOND_TICK	盛立深交所L2债券逐笔

订阅示例

quote_thread_t quote_threads[3] = {};
 
// 线程一：绑定CPU0，接收Xlight上交所和深交所L1行情
quote_threads[0].cpu_affinity = 0;
quote_threads[0].mc_count = 2;
quote_threads[0].mc_types[0] = QuoteMCType::XLT_SSE_L1;
quote_threads[0].mc_types[1] = QuoteMCType::XLT_SZSE_L1;
 
// 线程二：绑定CPU1，接收盛立上交所L2行情
quote_threads[1].cpu_affinity = 1;
quote_threads[1].mc_count = 5;
quote_threads[1].mc_types[0] = QuoteMCType::HPF_SSE_L2_STOCK_SNAP;
quote_threads[1].mc_types[1] = QuoteMCType::HPF_SSE_L2_STOCK_TICK;
quote_threads[1].mc_types[2] = QuoteMCType::HPF_SSE_L2_INDEX;
quote_threads[1].mc_types[3] = QuoteMCType::HPF_SSE_L2_BOND_SNAP;
quote_threads[1].mc_types[4] = QuoteMCType::HPF_SSE_L2_BOND_TICK;
 
// 线程三：绑定CPU2，接收盛立深交所L2行情
quote_threads[2].cpu_affinity = 2;
quote_threads[2].mc_count = 5;
quote_threads[2].mc_types[0] = QuoteMCType::HPF_SZSE_L2_STOCK_SNAP;
quote_threads[2].mc_types[1] = QuoteMCType::HPF_SZSE_L2_STOCK_TICK;
quote_threads[2].mc_types[2] = QuoteMCType::HPF_SZSE_L2_INDEX;
quote_threads[2].mc_types[3] = QuoteMCType::HPF_SZSE_L2_BOND_SNAP;
quote_threads[2].mc_types[4] = QuoteMCType::HPF_SZSE_L2_BOND_TICK;
 
// 订阅行情，使用自动接收模式
api->subscribe_quote(session_id, 3, quote_threads, QuoteRxMode::RX_MODE_AUTO);

行情接收模式（QuoteRxMode）

模式	说明
RX_MODE_AUTO	自动选择，优先使用 ef_vi（Solarflare 网卡），不可用时回退到内核 socket
RX_MODE_SOCKET	强制使用内核 socket 接收
RX_MODE_EFVI	强制使用 ef_vi 接收（需 Solarflare 网卡）

行情数据接收与解码

订阅成功后，行情数据通过 x1::XLTQuoteSpi::on_quote 回调推送。回调参数为原始 UDP 包数据，需要使用解码器进行解码。

void MyQuoteSpi::on_quote(QuoteMCType mc_type, const void* msg_data, uint32_t msg_len) {
    // 使用 XLTQuoteDecoder 解码 Xlight L1 行情
    const XLTQuoteItem* item;
    XLTQuoteDecoder decoder(mc_type, msg_data, msg_len);
    while ((item = decoder.get_next()) != nullptr) {
        switch (item->data_type) {
        case QuoteMsgType::SSE_L1_INDEX:
            // 处理上交所L1指数: item->data.sse_l1_index
            break;
        case QuoteMsgType::SSE_L1_SNAPSHOT:
            // 处理上交所L1快照: item->data.sse_l1_snapshot
            break;
        case QuoteMsgType::SZSE_L1_INDEX:
            // 处理深交所L1指数: item->data.szse_l1_index
            break;
        case QuoteMsgType::SZSE_L1_SNAPSHOT:
            // 处理深交所L1快照: item->data.szse_l1_snapshot
            break;
        case QuoteMsgType::SZSE_L1_BOND_SNAPSHOT:
            // 处理深交所L1债券快照: item->data.szse_l1_snapshot_bond
            break;
        default:
            break;
        }
    }
 
    // 使用 EFHQuoteDecoder 解码盛立 L2 行情
    const EFHQuoteItem* efh_item;
    EFHQuoteDecoder efh_decoder(mc_type, msg_data, msg_len);
    while ((efh_item = efh_decoder.get_next()) != nullptr) {
        // 根据 efh_item->data_type 处理不同的L2行情数据
    }
}

查询

查询静态行情信息

调用 x1::XLTQuoteApi::query_static_quote_info 查询全量证券静态信息（涨跌停价、最小变动价位、委托数量限制等），结果通过 x1::XLTQuoteSpi::on_query_static_quote_info 回调返回。

api->query_static_quote_info(session_id, request_id);

回调处理：

void MyQuoteSpi::on_query_static_quote_info(uint64_t session_id, uint64_t request_id,
                                            const XLTStaticQuoteList* static_quotes,
                                            bool is_last, const xlt_error_info_t* error_info) {
    if (error_info && error_info->error_code_type != 0) return;
    for (size_t i = 0; i < static_quotes->data_count(); ++i) {
        const xlt_static_quote_full_info_t* info = static_quotes->get(i);
        // 处理静态信息：info->security_code, info->upper_limit_price, ...
    }
    // is_last == true 表示数据已全部返回
}

查询Level1行情

查询单个证券的Level1行情：

// 查询上交所 600000 的Level1行情
api->query_level1_quote(session_id, request_id, ExchangeIndex::SH, "600000");

结果通过 x1::XLTQuoteSpi::on_query_level1_quote 回调返回。

查询全量Level1行情：

api->query_all_level1_quote(session_id, request_id);

结果通过 x1::XLTQuoteSpi::on_query_all_level1_quote 回调返回，数据量较大时会分多条消息返回，通过 is_last 参数判断是否接收完毕。

回补Level2逐笔行情

如果发现行情数据缺失（如逐笔序号不连续），可调用 x1::XLTQuoteApi::request_rebuild_tick_quote 请求回补指定通道、指定序号范围的逐笔行情数据。

xlt_rebuild_tick_quote_req_t request = {};
request.exchange_index = ExchangeIndex::SH;  // 上交所
request.channel_no = 1;                      // 通道号
request.begin_sequence = 1;                  // 起始序号
request.end_sequence = 100;                  // 结束序号
 
api->request_rebuild_tick_quote(session_id, request_id, &request);

• 请求失败通过 x1::XLTQuoteSpi::on_request_rebuild_tick_quote_error 返回错误信息。
• 回补数据通过 x1::XLTQuoteSpi::on_rebuild_tick_quote 逐条推送。

断线处理

当连接断开时，会触发 x1::XLTQuoteSpi::on_disconnect 回调。用户需要在此回调中重新发起登录：

void MyQuoteSpi::on_disconnect(uint64_t session_id) {
    // 连接断开，需要重新调用 login() 建立连接
}

退订行情

不再需要接收行情数据时，调用 x1::XLTQuoteApi::unsubscribe_quote 退订。退订后API会销毁所有行情接收线程并释放资源。

api->unsubscribe_quote(session_id);