文档首页/ 对象存储服务 OBS/ SDK参考/ C/ 初始化(C SDK)/ 配置option(C SDK)
更新时间：2026-07-13 GMT+08:00
查看PDF
分享

配置option(C SDK)

开发过程中，您有任何问题可以在GitHub上提交issue，或者在华为云对象存储服务论坛中发帖求助。

在调用C SDK的功能函数时，都要传入obs_options参数，您可通过init_obs_options函数初始化obs_options配置，通过obs_options设置AK、SK、Endpoint、bucket、超时时间、临时鉴权。obs_options主要包括obs_bucket_context和obs_http_request_option两个结构，可以设置的参数见下表：

表1 obs_options.obs_bucket_context参数

参数名称

参数类型

是否必选

描述

host_name

char *

必选

参数解释：

终端节点（Endpoint），即OBS服务的访问域名。

约束限制：

不需要带"http://"或"https://"前缀，通过protocol参数控制协议类型。

取值范围：

无

默认取值：

无

bucket_name

char *

必选

参数解释：

操作的桶名。

约束限制：

桶名需全局唯一，3～63个字符，数字或字母开头，支持小写字母、数字、"-"、"."。

取值范围：

无

默认取值：

无

protocol

obs_protocol

可选

参数解释：

请求使用的协议类型。

约束限制：

无

取值范围：

  • OBS_PROTOCOL_HTTPS（使用https协议）、OBS_PROTOCOL_HTTP（使用http协议）。

默认取值：

OBS_PROTOCOL_HTTPS，出于安全性考虑，建议使用https协议。

access_key

char *

必选

参数解释：

连接对象存储服务的AK。

约束限制：

无

取值范围：

无

默认取值：

无

secret_access_key

char *

必选

参数解释：

鉴权使用的SK，可用于字符串的签名。

约束限制：

无

取值范围：

无

默认取值：

无

storage_class

表1 obs_storage_class

可选

参数解释：

在PUT、POST请求中，需要配置存储类别时设置此参数。

约束限制：

无

取值范围：

请详见表1 obs_storage_class。

默认取值：OBS_STORAGE_CLASS_STANDARD

token

char *

可选

参数解释：

临时访问密钥的SecurityToken。

约束限制：

无

取值范围：

无

默认取值：

无

bucket_type

表5 obs_bucket_type

可选

参数解释：

创建桶时，指定是对象桶还是并行文件系统。

约束限制：

无

取值范围：

请详见表5 obs_bucket_type。

默认取值：OBS_BUCKET_OBJECT

bucket_list_type

表6 obs_bucket_list_type

可选

参数解释：

列举桶时，确定列举桶的类型。

约束限制：

无

取值范围：

请详见表6 obs_bucket_list_type。

默认取值：

OBS_BUCKET_LIST_ALL
表2 obs_options.obs_http_request_option参数

参数名称

参数类型

是否必选

描述

keep_alive

bool

可选

参数解释：

是否开启长链接。

约束限制：

无

取值范围：

true：开启长链接；false：不开启长链接。

默认取值：

false

keep_idle

int

可选

参数解释：

以秒为单位，在连接空闲后，发送keepalive探测之前等待的时间间隔。

约束限制：

仅在keep_alive为true时生效。

取值范围：

正整数。

默认取值：

120（单位：秒）

keep_intvl

int

可选

参数解释：

以秒为单位，设置在发送keepalive探测之间等待的时间间隔。

约束限制：

仅在keep_alive为true时生效。

取值范围：

正整数。

默认取值：

60（单位：秒）

forbid_reuse_tcp

bool

可选

参数解释：

是否禁止重用tcp连接。

约束限制：

无

取值范围：

true：禁止重用；false：允许重用。

默认取值：

false

outgoing_interface

char *

可选

参数解释：

本地出接口（网卡名或IP），NULL表示不绑定。

约束限制：

无

取值范围：

网卡名（如"eth0"）或本地IP地址（如"192.168.1.100"）。

默认取值：

NULL

local_port

unsigned int

可选

参数解释：

本地源端口。

约束限制：

无

取值范围：

0表示不绑定，1..65535表示绑定到指定端口。

默认取值：

0

local_port_range

unsigned int

可选

参数解释：

从local_port开始的端口尝试数量。

约束限制：

local_port_range是尝试数量，不是结束端口号。

取值范围：

无

默认取值：

1

connect_time

int

可选

参数解释：

建立HTTP/HTTPS连接的超时时间。

约束限制：

无

取值范围：

建议取值[10000, 60000]。

默认取值：

60000（单位：毫秒）

max_connected_time

int

可选

参数解释：

整个请求的最大超时时间，包含连接建立和数据传输阶段。

约束限制：

0表示不设置超时限制，请求保持连接直到完成。

取值范围：

无

默认取值：

0（单位：秒）

proxy_host

char *

可选

参数解释：

代理服务器地址。

约束限制：

需要同时设置proxy_host和proxy_auth才可使用代理。代理失败不会自动切换为直连。

取值范围：

支持HTTP、HTTPS、SOCKS5代理，格式为"协议://地址:端口"，例如"https://proxy.example.com:8080"、"socks5://proxy.example.com:1080"。

默认取值：

NULL

proxy_auth

char *

可选

参数解释：

代理认证信息，用于代理服务器的用户身份验证。

约束限制：

仅支持Basic认证方式，不支持NTLM、Digest等认证方式。无需认证时不需要设置此参数。

取值范围：

格式为"username:password"。

默认取值：

NULL
  • connect_time 单位为毫秒，max_connected_time 单位为秒，请注意区分。
  • 如网络状况不佳，建议增大connect_time和max_connected_time的值。

代码示例-绑定本地IP或网卡

  • outgoing_interface绑定的是本地源地址，不是目标服务地址。常见使用场景：多网卡环境下指定出口网卡、防火墙策略要求流量从指定IP出去。
  • 网卡名因平台不同而异：Linux下常见"eth0"、"ens33"等；Windows下常见"以太网"、"Wi-Fi"等中文名称。建议优先使用本地IP地址，兼容性更好
// 常见场景：多网卡环境指定出口、防火墙要求指定源IP
void example_bind_local_interface(obs_options *obs_options)
{
    // 方法1: 使用本地IP地址（推荐，跨平台兼容）
    obs_options->request_options.outgoing_interface = "192.168.1.100"; // TODO: 替换为实际的本地IP
    // 方法2: 使用网卡名（平台相关）
    // Linux:   "eth0", "ens33"
    // Windows: "以太网", "Wi-Fi"
    // obs_options->request_options.outgoing_interface = "eth0";
}

代码示例-绑定单端口

  • local_port绑定的是本地源端口，不是目标服务端口。建议使用1024~65535范围内的端口，避免与系统保留端口（0~1023）和常见服务端口冲突。绑定1024以下端口可能需要管理员权限。;
  • 当local_port指定的端口被占用时，SDK会尝试local_port_range范围内的后续端口。若所有端口均被占用，请求将返回连接失败。
  • 企业网络环境中，防火墙可能对出站端口有限制，请确保绑定的端口在防火墙允许范围内。
// 常见场景：多网卡环境指定出口、防火墙要求指定源IP
void example_bind_local_interface(obs_options *obs_options)
{
    // 方法1: 使用本地IP地址（推荐，跨平台兼容）
    obs_options->request_options.outgoing_interface = "192.168.1.100"; // TODO: 替换为实际的本地IP
    // 方法2: 使用网卡名（平台相关）
    // Linux:   "eth0", "ens33"
    // Windows: "以太网", "Wi-Fi"
    // obs_options->request_options.outgoing_interface = "eth0";
}

代码示例-绑定本地网卡 + 端口范围

// 从 local_port 开始，总共尝试 local_port_range 个端口
// 例如：local_port=40000, local_port_range=10 表示依次尝试 40000~40009
void example_bind_interface_and_port_range(obs_options *obs_options)
{
    // 同时指定本地出接口和端口范围
    obs_options->request_options.outgoing_interface = "192.168.1.100"; // TODO: 替换为实际的本地IP
    obs_options->request_options.local_port = 40000;
    obs_options->request_options.local_port_range = 10;  // 依次尝试 40000~40009
}
父主题： 初始化(C SDK)

相关文档