upctp

CTP Rust 绑定库 v0.10.0 - 完整文档

← 返回首页

概述

行情 API 用于接收期货市场的实时行情数据。它提供了连接行情服务器、订阅合约行情、接收深度行情数据等功能。

MdApi 方法

方法说明返回值
new(flow_path, is_udp, is_multicast, is_production)创建 MdApi 实例MdApi
get_api_version()获取 API 版本号String
release()释放 API 资源()
init()初始化 API()
join()等待 API 线程结束i32
get_trading_day()获取当前交易日String
register_front(address)注册行情前置地址()
register_name_server(address)注册名字服务器()
register_fens_user_info(info)注册 FENS 用户信息()
register_spi(spi)注册 SPI 回调()
subscribe_market_data(ids)订阅合约行情i32
unsubscribe_market_data(ids)退订合约行情i32
subscribe_for_quote_rsp(ids)订阅询价i32
unsubscribe_for_quote_rsp(ids)退订询价i32
req_user_login(login, request_id)请求用户登录i32
req_user_logout(logout, request_id)请求用户登出i32
req_qry_multicast_instrument(qry, request_id)查询组播合约i32

MdSpi 回调

回调说明
on_front_connected()前置连接成功
on_front_disconnected(n_reason)前置断开连接
on_heart_beat_warning(n_time_lapse)心跳超时警告
on_rsp_user_login(p, p_info, n, b)登录响应
on_rsp_user_logout(p, p_info, n, b)登出响应
on_rsp_qry_multicast_instrument(p, p_info, n, b)查询组播合约响应
on_rsp_error(p_info, n, b)错误响应
on_rsp_sub_market_data(p, p_info, n, b)订阅行情响应
on_rsp_un_sub_market_data(p, p_info, n, b)退订行情响应
on_rsp_sub_for_quote_rsp(p, p_info, n, b)订阅询价响应
on_rsp_un_sub_for_quote_rsp(p, p_info, n, b)退订询价响应
on_rtn_depth_market_data(p)深度行情数据推送
on_rtn_for_quote_rsp(p)询价通知

使用流程

// 1. 创建 MdApi
let mut md_api = MdApi::new("", false, false, false);

// 2. 注册 SPI
md_api.register_spi(Arc::new(MyMdSpi));

// 3. 注册前置地址
md_api.register_front("tcp://180.168.146.187:10131");

// 4. 初始化
md_api.init();

// 回调流程：
// on_front_connected()
//   -> req_user_login()
// on_rsp_user_login() 登录成功
//   -> subscribe_market_data(["rb2501"])
// on_rsp_sub_market_data() 订阅成功
// on_rtn_depth_market_data() 接收行情数据

方法详解

new(flow_path, is_using_udp, is_multicast, is_production_mode)

创建 MdApi 实例

  • flow_path: 存储行情流文件的目录路径
  • is_using_udp: 是否使用 UDP 协议
  • is_multicast: 是否使用组播方式
  • is_production_mode: 是否为生产模式

subscribe_market_data(instrument_ids)

订阅合约行情

  • instrument_ids: 合约代码数组，如 ["rb2501", "rb2510"]
  • 必须在登录成功后调用
  • 订阅成功后通过 on_rtn_depth_market_data() 接收数据

req_user_login(login, request_id)

请求用户登录

  • login: 登录请求结构体 CThostFtdcReqUserLoginField
  • request_id: 请求 ID，用于匹配请求和响应
  • 必须在 on_front_connected() 回调中调用

on_rtn_depth_market_data(p)

深度行情数据推送回调

  • p: 深度行情数据 CThostFtdcDepthMarketDataField
  • 包含最新价、成交量、买卖盘口等完整行情信息
  • 每当交易所发布新行情数据时触发

方法详细说明

get_api_version()

获取 CTP 行情 API 版本号。

返回值：String - API 版本字符串

注意：静态方法，无需创建实例即可调用

let version = MdApi::get_api_version();
println!("API 版本: {}", version);

release()

释放 MdApi 实例资源。

说明：断开与行情前置的连接，释放内部资源。通常在 Drop 时自动调用。

init()

初始化行情 API。

说明：启动内部网络线程，开始连接行情前置。必须在 register_front() 和 register_spi() 之后调用。

join()

阻塞等待 API 内部线程结束。

返回值：i32 - 线程退出码

说明：通常在程序退出前调用，确保资源正确释放。

get_trading_day()

获取当前交易日。

返回值：String - 交易日期字符串，格式为 "YYYYMMDD"

register_front(address)

注册行情前置服务器地址。

参数：address - 前置服务器地址，格式为 "protocol://ip:port"

示例："tcp://180.168.146.187:10131"

注意：必须在 init() 之前调用。可以多次调用注册多个前置地址。

register_name_server(address)

注册名字服务器地址。

参数：address - 名字服务器地址

说明：使用名字服务器可以自动获取可用的行情前置地址。

register_fens_user_info(info)

注册 FENS 用户信息。

参数：info - FENS 用户信息结构体 CThostFtdcFensUserInfoField

说明：用于特定经纪商的认证。

register_spi(spi)

注册行情 SPI 回调接口。

参数：spi - 实现了 MdSpi trait 的对象，需要用 Arc 包装

注意：必须在 init() 之前调用。

subscribe_market_data(instrument_ids)

订阅合约行情。

参数：instrument_ids - 要订阅的合约代码数组，如 ["rb2501", "rb2510"]

返回值：i32 - 0 表示发送成功

注意：必须在登录成功后调用。订阅成功后通过 on_rtn_depth_market_data() 接收数据。

unsubscribe_market_data(instrument_ids)

退订合约行情。

参数：instrument_ids - 要退订的合约代码数组

返回值：i32 - 0 表示发送成功

subscribe_for_quote_rsp(instrument_ids)

订阅询价通知。

参数：instrument_ids - 要订阅询价的合约代码数组

返回值：i32 - 0 表示发送成功

说明：订阅后，当有询价请求时，会通过 on_rtn_for_quote_rsp() 回调收到通知。

unsubscribe_for_quote_rsp(instrument_ids)

退订询价通知。

参数：instrument_ids - 要退订询价的合约代码数组

返回值：i32 - 0 表示发送成功

req_user_login(login, request_id)

请求用户登录。

参数：login - 登录请求结构体 CThostFtdcReqUserLoginField

参数：request_id - 请求 ID，用于匹配请求和响应

返回值：i32 - 0 表示发送成功

注意：必须在 on_front_connected() 回调中调用。

req_user_logout(logout, request_id)

请求用户登出。

参数：logout - 登出请求结构体 CThostFtdcUserLogoutField

参数：request_id - 请求 ID

返回值：i32 - 0 表示发送成功

req_qry_multicast_instrument(qry, request_id)

查询组播合约信息。

参数：qry - 查询请求结构体 CThostFtdcQryMulticastInstrumentField

参数：request_id - 请求 ID

返回值：i32 - 0 表示发送成功

回调详细说明

on_front_connected()

前置连接成功回调。

说明：当 API 成功连接到行情前置服务器时触发。此时可以开始登录操作。

fn on_front_connected(&self) {
    println!("行情前置连接成功！");
    // 触发登录
    self.do_login();
}

on_front_disconnected(n_reason)

前置断开连接回调。

参数：n_reason - 断开原因（0x1001: 网络读失败, 0x1002: 网络写失败, 0x2001: 接收心跳超时, 0x2002: 发送心跳失败, 0x2003: 收到错误消息, 0x2004: 前置关闭）

说明：连接断开后，API 会自动重连。重连成功后会再次触发 on_front_connected()。

on_heart_beat_warning(n_time_lapse)

心跳超时警告回调。

参数：n_time_lapse - 心跳超时时间（毫秒）

说明：当心跳超时时间超过阈值时触发，表示网络连接可能存在问题。

on_rsp_user_login(p, p_info, n_request_id, b_is_last)

登录响应回调。

参数：p - 登录响应数据，登录成功时有效

参数：p_info - 错误信息，登录失败时包含错误码和错误信息

参数：n_request_id - 请求 ID，与发送请求时传入的 ID 对应

参数：b_is_last - 是否为最后一条响应

on_rsp_user_logout(p, p_info, n_request_id, b_is_last)

登出响应回调。

参数：p - 登出响应数据

参数：p_info - 错误信息

参数：n_request_id - 请求 ID

参数：b_is_last - 是否为最后一条响应

on_rsp_qry_multicast_instrument(p, p_info, n_request_id, b_is_last)

查询组播合约响应回调。

参数：p - 组播合约信息

参数：p_info - 错误信息

参数：n_request_id - 请求 ID

参数：b_is_last - 是否为最后一条响应

on_rsp_error(p_info, n_request_id, b_is_last)

错误响应回调。

参数：p_info - 错误信息

参数：n_request_id - 请求 ID

参数：b_is_last - 是否为最后一条响应

on_rsp_sub_market_data(p, p_info, n_request_id, b_is_last)

订阅行情响应回调。

参数：p - 订阅的合约信息

参数：p_info - 错误信息

参数：n_request_id - 请求 ID

参数：b_is_last - 是否为最后一条响应

on_rsp_un_sub_market_data(p, p_info, n_request_id, b_is_last)

退订行情响应回调。

参数：p - 退订的合约信息

参数：p_info - 错误信息

参数：n_request_id - 请求 ID

参数：b_is_last - 是否为最后一条响应

on_rsp_sub_for_quote_rsp(p, p_info, n_request_id, b_is_last)

订阅询价响应回调。

参数：p - 订阅的合约信息

参数：p_info - 错误信息

参数：n_request_id - 请求 ID

参数：b_is_last - 是否为最后一条响应

on_rsp_un_sub_for_quote_rsp(p, p_info, n_request_id, b_is_last)

退订询价响应回调。

参数：p - 退订的合约信息

参数：p_info - 错误信息

参数：n_request_id - 请求 ID

参数：b_is_last - 是否为最后一条响应

on_rtn_depth_market_data(p)

深度行情数据推送回调。

参数：p - 深度行情数据 CThostFtdcDepthMarketDataField

说明：这是行情 API 最核心的回调方法。每当交易所发布新的行情数据时触发。数据包含最新价、成交量、买卖盘口等完整行情信息。

fn on_rtn_depth_market_data(&self, p: Option<&CThostFtdcDepthMarketDataField>) {
    if let Some(d) = p {
        let id = read_cstr(&d.InstrumentID);
        println!("最新价: {}", d.LastPrice);
        println!("成交量: {}", d.Volume);
        println!("持仓量: {}", d.OpenInterest);
        println!("买一价: {} 量: {}", d.BidPrice1, d.BidVolume1);
        println!("卖一价: {} 量: {}", d.AskPrice1, d.AskVolume1);
    }
}

on_rtn_for_quote_rsp(p)

询价通知回调。

参数：p - 询价响应数据 CThostFtdcForQuoteRspField

说明：当有交易者对某合约发起询价时触发。做市商可以据此响应报价。

方法详细说明

new(flow_path, is_using_udp, is_multicast, is_production_mode)

创建 MdApi 实例。

参数：flow_path - 存储行情流文件的目录路径
is_using_udp - 是否使用 UDP 协议
is_multicast - 是否使用组播方式
is_production_mode - 是否为生产模式

返回值：MdApi

说明：测试环境设置 is_production_mode=false。生产环境设置 is_production_mode=true。

get_api_version()

获取 CTP 行情 API 版本号。

返回值：String

说明：静态方法，无需创建实例即可调用。

release()

释放 MdApi 实例资源。

说明：断开与行情前置的连接，释放内部资源。通常在 Drop 时自动调用。

init()

初始化行情 API。

说明：启动内部网络线程，开始连接行情前置。必须在 register_front() 和 register_spi() 之后调用。

join()

阻塞等待 API 内部线程结束。

返回值：i32

说明：返回线程退出码。通常在程序退出前调用，确保资源正确释放。

get_trading_day()

获取当前交易日。

返回值：String

说明：返回交易日期字符串，格式为 YYYYMMDD。

register_front(address)

注册行情前置服务器地址。

参数：address - 前置服务器地址，格式为 protocol://ip:port，示例：tcp://180.168.146.187:10131

说明：必须在 init() 之前调用。可以多次调用注册多个前置地址，API 会自动选择可用的连接。

register_name_server(address)

注册名字服务器地址。

参数：address - 名字服务器地址

说明：使用名字服务器可以自动获取可用的行情前置地址，不需要手动指定具体的前置地址。

register_fens_user_info(info)

注册 FENS 用户信息。

参数：info - FENS 用户信息结构体 CThostFtdcFensUserInfoField

说明：用于特定经纪商的认证。

register_spi(spi)

注册行情 SPI 回调接口。

参数：spi - 实现了 MdSpi trait 的对象，需要用 Arc 包装

说明：必须在 init() 之前调用。SPI 对象会被 API 内部持有，用于接收回调通知。

subscribe_market_data(instrument_ids)

订阅合约行情。

参数：instrument_ids - 要订阅的合约代码数组，如 ["rb2501", "rb2510"]

返回值：i32

说明：必须在登录成功后调用。可以一次订阅多个合约。订阅成功后，会通过 on_rtn_depth_market_data() 回调接收行情数据。

unsubscribe_market_data(instrument_ids)

退订合约行情。

参数：instrument_ids - 要退订的合约代码数组

返回值：i32

说明：退订后不再接收该合约的行情数据推送。

subscribe_for_quote_rsp(instrument_ids)

订阅询价通知。

参数：instrument_ids - 要订阅询价的合约代码数组

返回值：i32

说明：订阅后，当有交易者对某合约发起询价时，会通过 on_rtn_for_quote_rsp() 回调收到通知。做市商可以据此响应报价。

unsubscribe_for_quote_rsp(instrument_ids)

退订询价通知。

参数：instrument_ids - 要退订询价的合约代码数组

返回值：i32

说明：退订后不再接收该合约的询价通知。

req_user_login(login, request_id)

请求用户登录。

参数：login - 登录请求结构体 CThostFtdcReqUserLoginField
request_id - 请求 ID，用于匹配请求和响应

返回值：i32

说明：必须在 on_front_connected() 回调中调用。登录成功后才能订阅行情。

req_user_logout(logout, request_id)

请求用户登出。

参数：logout - 登出请求结构体 CThostFtdcUserLogoutField
request_id - 请求 ID

返回值：i32

说明：断开与行情服务器的用户会话。

req_qry_multicast_instrument(qry, request_id)

查询组播合约信息。

参数：qry - 查询请求结构体 CThostFtdcQryMulticastInstrumentField
request_id - 请求 ID

返回值：i32

说明：查询组播模式下的合约信息。

回调详细说明

on_front_connected()

前置连接成功回调。

说明：当 API 成功连接到行情前置服务器时触发。此时可以开始登录操作。

on_front_disconnected(n_reason)

前置断开连接回调。

参数：n_reason - 断开原因（0x1001: 网络读失败, 0x1002: 网络写失败, 0x2001: 接收心跳超时, 0x2002: 发送心跳失败, 0x2003: 收到错误消息, 0x2004: 前置关闭）

说明：连接断开后，API 会自动重连。重连成功后会再次触发 on_front_connected()。

on_heart_beat_warning(n_time_lapse)

心跳超时警告回调。

参数：n_time_lapse - 心跳超时时间（毫秒）

说明：当心跳超时时间超过阈值时触发，表示网络连接可能存在问题。

on_rsp_user_login(p, p_info, n_request_id, b_is_last)

登录响应回调。

参数：p - 登录响应数据 CThostFtdcRspUserLoginField
p_info - 错误信息
n_request_id - 请求 ID
b_is_last - 是否为最后一条响应

说明：登录成功后 p 有效，可以开始订阅行情。登录失败时 p_info 包含错误信息。

on_rsp_user_logout(p, p_info, n_request_id, b_is_last)

登出响应回调。

参数：p - 登出响应数据 CThostFtdcUserLogoutField
p_info - 错误信息
n_request_id - 请求 ID
b_is_last - 是否为最后一条响应

on_rsp_qry_multicast_instrument(p, p_info, n_request_id, b_is_last)

查询组播合约响应回调。

参数：p - 组播合约信息 CThostFtdcMulticastInstrumentField
p_info - 错误信息
n_request_id - 请求 ID
b_is_last - 是否为最后一条响应

on_rsp_error(p_info, n_request_id, b_is_last)

错误响应回调。

参数：p_info - 错误信息 CThostFtdcRspInfoField
n_request_id - 请求 ID
b_is_last - 是否为最后一条响应

说明：当请求发生错误时触发。p_info.ErrorID 包含错误码，p_info.ErrorMsg 包含错误描述。

on_rsp_sub_market_data(p, p_info, n_request_id, b_is_last)

订阅行情响应回调。

参数：p - 订阅的合约信息 CThostFtdcSpecificInstrumentField
p_info - 错误信息
n_request_id - 请求 ID
b_is_last - 是否为最后一条响应

on_rsp_un_sub_market_data(p, p_info, n_request_id, b_is_last)

退订行情响应回调。

参数：p - 退订的合约信息 CThostFtdcSpecificInstrumentField
p_info - 错误信息
n_request_id - 请求 ID
b_is_last - 是否为最后一条响应

on_rsp_sub_for_quote_rsp(p, p_info, n_request_id, b_is_last)

订阅询价响应回调。

参数：p - 订阅的合约信息 CThostFtdcSpecificInstrumentField
p_info - 错误信息
n_request_id - 请求 ID
b_is_last - 是否为最后一条响应

on_rsp_un_sub_for_quote_rsp(p, p_info, n_request_id, b_is_last)

退订询价响应回调。

参数：p - 退订的合约信息 CThostFtdcSpecificInstrumentField
p_info - 错误信息
n_request_id - 请求 ID
b_is_last - 是否为最后一条响应

on_rtn_depth_market_data(p)

深度行情数据推送回调。

参数：p - 深度行情数据 CThostFtdcDepthMarketDataField

说明：这是行情 API 最核心的回调方法。每当交易所发布新的行情数据时触发。数据包含最新价、成交量、买卖盘口（5档）、持仓量、结算价、涨跌幅等完整行情信息。

on_rtn_for_quote_rsp(p)

询价通知回调。

参数：p - 询价响应数据 CThostFtdcForQuoteRspField

说明：当有交易者对某合约发起询价时触发。做市商可以据此响应报价。