客户端生命周期

创建 QuoteClient 和 TradeClient

explicit QuoteClient(const ClientConfig &cf, bool is_grab_permission = true)
explicit TradeClient(const ClientConfig &cf)

说明

创建行情或交易 HTTP 客户端。当前 QuoteClient 实现无条件调用 grab_quote_permission()，没有读取 is_grab_permission；该参数虽有默认值，但当前版本不能用于关闭抢占行为。

参数

参数名	类型	是否必填	描述
cf	const ClientConfig&	Yes	已配置的开发者凭证；交易客户端还需要账户
is_grab_permission	bool	No	头文件默认 `true`；当前实现忽略该值

构造 QuoteClient 或 TradeClient。两者不可复制或移动，因为继承的 TigerClient 删除了复制/移动操作。

示例

TIGER_API::ClientConfig config(false, U("your_config_directory_path"));
TIGER_API::QuoteClient quote_client(config);
TIGER_API::TradeClient trade_client(config);

创建推送客户端

static std::shared_ptr<IPushClient> IPushClient::create_push_client(
    const ClientConfig &client_config)

说明

使用配置副本创建异步推送客户端。返回的共享指针必须覆盖所有异步回调。

参数

参数名	类型	是否必填	描述
client_config	const ClientConfig&	Yes	已通过校验的开发者、账户和 socket 配置

std::shared_ptr<IPushClient>。创建对象不代表网络已连接。

示例

#include "tigerapi/client_config.h"
#include "tigerapi/push_client.h"

int main() {
    TIGER_API::ClientConfig config(false, U("your_config_directory_path"));
    auto client = TIGER_API::IPushClient::create_push_client(config);
    client->connect();
    client->disconnect();
}

获取配置

const ClientConfig& IPushClient::get_client_config() const

说明

返回客户端持有的只读配置引用。引用生命周期不超过客户端。

参数

无。

const ClientConfig&，不可用于修改客户端配置。

示例

const TIGER_API::ClientConfig& active_config = client->get_client_config();
utility::ucout << active_config.account << std::endl;

建立连接

void IPushClient::connect()

说明

启动工作线程并异步连接。实际结果通过 set_connected_callback、set_inner_error_callback 或 set_error_callback 通知；无同步返回值。

参数

无。

void。方法返回不表示握手成功。

示例

client->set_connected_callback([]() { std::cout << "connected\n"; });
client->connect();

断开连接

void IPushClient::disconnect()

说明

向工作线程异步提交断开操作。使用 set_disconnected_callback 观察完成，不要将方法返回视为网络连接已经关闭。

参数

无。

void。

示例

client->set_disconnected_callback([]() { std::cout << "disconnected\n"; });
client->disconnect();

刷新访问令牌

utility::string_t TigerClient::refresh_token()

说明

向服务端获取新 token，成功时持久化并更新线程安全配置；失败返回空字符串。query_token() 是保留的废弃别名。

参数

无。

utility::string_t 新 token；失败为空字符串。

示例

TIGER_API::QuoteClient client(config);
const utility::string_t token = client.refresh_token();
if (token.empty()) {
    std::cerr << "token refresh failed\n";
}

刷新 token 兼容别名

utility::string_t TigerClient::query_token()

说明

refresh_token() 的废弃兼容别名。新代码应使用 refresh_token()。

参数

无。

utility::string_t 新 token；失败返回空字符串。

示例

const utility::string_t token = client.query_token(); // 仅兼容旧代码

启动自动刷新

bool TigerClient::start_token_refresh(int interval_seconds)

说明

按秒启动后台刷新。interval_seconds 必须为正；已有刷新线程时返回 false。客户端不可复制或移动，必须在销毁前保持有效。

参数

参数名	类型	是否必填	描述
interval_seconds	int	Yes	正数刷新周期，单位秒

bool；成功启动返回 true，已有刷新线程返回 false。

示例

if (!client.start_token_refresh(3600)) {
    std::cerr << "refresh thread already running\n";
}

停止自动刷新

void TigerClient::stop_token_refresh()

说明

通知后台线程停止并等待退出。析构前会清理线程，但建议在业务关闭流程中显式调用。

参数

无。

void。

示例

client.stop_token_refresh();

ClientConfig 构造与配置

ClientConfig(bool sandbox_debug = false)
ClientConfig(utility::string_t tiger_id, utility::string_t private_key, utility::string_t account)
ClientConfig(utility::string_t tiger_id, utility::string_t private_key, utility::string_t account,
             bool sandbox_debug = false, utility::string_t lang = U("en_US"))
ClientConfig(bool sandbox_debug, const utility::string_t props_path)
ClientConfig(const ClientConfig& other)

说明

从默认值、显式凭证或 properties 路径创建配置。复制构造只复制配置和当前 token，不复制刷新线程；赋值和移动已删除。

参数

参数名	类型	是否必填	描述
sandbox_debug	bool	No	SDK 默认 `false`
tiger_id	utility::string_t	条件必填	显式凭证构造时必填
private_key	utility::string_t	条件必填	RSA 私钥；不得写入日志
account	utility::string_t	条件必填	交易账户；行情-only 用法可稍后配置
lang	utility::string_t	No	SDK 默认 `U("en_US")`
props_path	const utility::string_t	条件必填	properties 文件目录/路径
other	const ClientConfig&	条件必填	被复制配置；复制时不得运行刷新线程

构造 ClientConfig 对象。公共配置字段和默认值以 include/tigerapi/client_config.h 为准，包括 charset = U("UTF-8")、sign_type = U("RSA")、use_full_tick = false、发送/接收间隔 10000 毫秒。

示例

TIGER_API::ClientConfig config(
    U("tiger-id"), U("-----BEGIN PRIVATE KEY-----..."), U("account"),
    false, U("zh_CN"));

ClientConfig 校验方法

void ClientConfig::check() const
void ClientConfig::check_account() const

说明

check() 校验客户端请求所需配置；check_account() 额外校验交易账户。

参数

无。

void；配置无效时抛出 SDK 异常，不返回 JSON。

示例

config.check();
config.check_account();

ClientConfig 端点访问方法

void ClientConfig::set_server_url(const utility::string_t& url)
void ClientConfig::set_socket_url(const utility::string_t& url)
void ClientConfig::set_socket_port(const utility::string_t& port)
void ClientConfig::set_server_public_key(const utility::string_t& key)
const utility::string_t& ClientConfig::get_server_url() const
const utility::string_t& ClientConfig::get_server_pub_key() const
const utility::string_t& ClientConfig::get_socket_url() const
const utility::string_t& ClientConfig::get_socket_port() const

说明

设置或读取 HTTP、socket 和服务端公钥配置。

参数

参数名	类型	是否必填	描述
url	const utility::string_t&	Yes	完整 HTTP 或 socket 主机地址
port	const utility::string_t&	Yes	socket 端口字符串
key	const utility::string_t&	Yes	服务端 RSA 公钥

setter 返回 void；getter 返回配置内字符串的 const 引用。

示例

config.set_server_url(U("https://openapi.tigerfintech.com/gateway"));
const auto& server_url = config.get_server_url();

ClientConfig token 方法

void ClientConfig::set_token(const utility::string_t& token)
utility::string_t ClientConfig::get_token() const
bool ClientConfig::start_token_refresh(int interval_seconds,
    std::function<utility::string_t()> fetch_fn)
void ClientConfig::stop_token_refresh()

说明

线程安全地设置/读取 token，或用调用方提供的获取函数管理后台刷新。通常优先使用 TigerClient::start_token_refresh(int)，它已绑定 SDK 刷新请求。

参数

参数名	类型	是否必填	描述
token	const utility::string_t&	Yes	新 token；不得记录到日志
interval_seconds	int	Yes	正数刷新周期，单位秒
fetch_fn	std::function callback	Yes	无参数并返回 `utility::string_t` 新 token

get_token() 返回 token 副本；start_token_refresh 成功启动返回 true，已有线程返回 false；其余返回 void。

示例

config.set_token(U("redacted-token"));
const utility::string_t token_copy = config.get_token();
const bool started = config.start_token_refresh(3600, []() {
    return utility::string_t{}; // 用应用自己的安全 token 获取逻辑替换
});
config.stop_token_refresh();

判断美国站点

bool ClientConfig::is_us()

说明

根据当前配置判断是否使用美国站点。

参数

无。

bool。

示例

if (config.is_us()) {
    std::cout << "US environment\n";
}

TigerClient 文档范围

用户生命周期 API 包括具体 QuoteClient/TradeClient 构造函数、公开 client_config、refresh_token()、废弃别名 query_token()、start_token_refresh(int) 和 stop_token_refresh()。TigerClient(const ClientConfig&) 是基类构造细节，不建议直接实例化基类；具体客户端构造函数见本页。

以下 public 方法不作为面向用户的业务 API 单独记录：post、get、send_request 是 QuoteClient/TradeClient 的底层签名与 HTTP 调度原语；identifiers_to_options 是期权标识转换辅助函数。它们没有稳定的业务参数、权限或响应契约，直接使用会绕过类型化客户端方法。本次文档明确排除它们，但保留源码可见性。来源：tiger_client.h。

ClientConfig 的权威声明见 client_config.h，推送生命周期声明见 push_client.h。