Help Center/ Object Storage Service/ SDK Reference/ C/ Initialization (SDK for C)/ Configuring option (SDK for C)
Updated on 2026-08-03 GMT+08:00
View PDF
Share

Configuring option (SDK for C)

If you have any questions during development, post them on the Issues page of GitHub.

When the function of SDK for C is called, the obs_options parameter must be passed. You can use function init_obs_options to initialize the obs_options configuration, including the AK, SK, endpoint, bucket, timeout, and temporary authentication. obs_options consists of obs_bucket_context and obs_http_request_option. The following table describes the parameters that can be set.

Table 1 obs_options.obs_bucket_context parameters

Parameter

Type

Mandatory (Yes/No)

Description

host_name

char *

Yes

Explanation:

Endpoint, which is the access domain name of OBS

Restrictions:

The prefix http:// or https:// is not required. The protocol parameter is used to control the protocol type.

Value range:

None

Default value:

None

bucket_name

char *

Yes

Explanation:

Name of the bucket where the operation is performed

Restrictions:

The bucket name must be globally unique. It can contain 3 to 63 characters and must start with a digit or letter. Only lowercase letters, digits, hyphens (-), and periods (.) are allowed.

Value range:

None

Default value:

None

protocol

obs_protocol

No

Explanation:

Protocol used for sending requests

Restrictions:

None

Value range:

  • OBS_PROTOCOL_HTTPS (HTTPS) or OBS_PROTOCOL_HTTP (HTTP)

Default value:

OBS_PROTOCOL_HTTPS. For security purposes, you are advised to use HTTPS.

access_key

char *

Yes

Explanation:

AK for connecting to OBS

Restrictions:

None

Value range:

None

Default value:

None

secret_access_key

char *

Yes

Explanation:

SK used for authentication. It can be used to sign a character string.

Restrictions:

None

Value range:

None

Default value:

None

storage_class

Table 1

No

Explanation:

This parameter is required when the storage class needs to be configured in a PUT or POST request.

Restrictions:

None

Value range:

For details, see Table 1.

Default value: OBS_STORAGE_CLASS_STANDARD

token

char *

No

Explanation:

Security token in the temporary access keys

Restrictions:

None

Value range:

None

Default value:

None

bucket_type

Table 5

No

Explanation:

Whether to create an object bucket or a parallel file system

Restrictions:

None

Value range:

For details, see Table 5.

Default value: OBS_BUCKET_OBJECT

bucket_list_type

Table 6

No

Explanation:

Type of buckets to be listed

Restrictions:

None

Value range:

For details, see Table 6.

Default value:

OBS_BUCKET_LIST_ALL
Table 2 obs_options.obs_http_request_option parameters

Parameter

Type

Mandatory (Yes/No)

Description

keep_alive

bool

No

Explanation:

Whether to enable persistent connections

Restrictions:

None

Value range:

true: Enable persistent connections. false: Disable persistent connections.

Default value:

false

keep_idle

int

No

Explanation:

Interval for sending keepalive detection messages after a connection is idle, in seconds

Restrictions:

This parameter is valid only when keep_alive is set to true.

Value range:

A positive integer

Default value:

120, in seconds

keep_intvl

int

No

Explanation:

Interval for sending keepalive detection messages, in seconds

Restrictions:

This parameter is valid only when keep_alive is set to true.

Value range:

A positive integer

Default value:

60, in seconds

forbid_reuse_tcp

bool

No

Explanation:

Whether to forbid the reuse of TCP connections

Restrictions:

None

Value range:

true: The reuse is forbidden. false: The reuse is allowed.

Default value:

false

outgoing_interface

char *

No

Explanation:

Local outbound interface (NIC name or IP address). The value NULL indicates no binding.

Restrictions:

None

Value range:

The value can be a NIC name (for example, eth0) or a local IP address (for example, 192.168.1.100).

Default value:

NULL

local_port

unsigned int

No

Explanation:

Local source port

Restrictions:

None

Value range:

The value 0 indicates that no port is bound. Values from 1 to 65535 indicate that the specified port is bound.

Default value:

0

local_port_range

unsigned int

No

Explanation:

Number of port attempts starting from local_port

Restrictions:

local_port_range indicates the number of attempts, not the end port number.

Value range:

None

Default value:

1

connect_time

int

No

Explanation:

Timeout interval for establishing an HTTP/HTTPS connection

Restrictions:

None

Value range:

Recommended value range: [10000, 60000]

Default value:

60000, in milliseconds.

max_connected_time

int

No

Explanation:

Maximum timeout interval of the entire request, including both the connection establishment and data transmission phases

Restrictions:

The value 0 indicates that no timeout limit is set, and the request connection is maintained until the request is complete.

Value range:

None

Default value:

0, in seconds

proxy_host

char *

No

Explanation:

Proxy server address

Restrictions:

The proxy can be used only when both proxy_host and proxy_auth are set. If the proxy fails, the system does not automatically switch to direct connection.

Value range:

HTTP, HTTPS, and SOCKS5 proxies are supported. The format is Protocol://IP address:Port number, for example, https://proxy.example.com:8080 and socks5://proxy.example.com:1080.

Default value:

NULL

proxy_auth

char *

No

Explanation:

Proxy authentication information, which is used to authenticate the user identity on the proxy server

Restrictions:

Only the basic authentication mode is supported. Authentication modes such as NTLM and Digest are not supported. This parameter does not need to be set when authentication is not required.

Value range:

The format is username:password.

Default value:

NULL
  • The unit of connect_time is millisecond, and the unit of max_connected_time is second.
  • If the network is unstable, you are advised to set larger values for connect_time and max_connected_time.

Sample Code – Binding a Local IP Address or NIC

  • The outgoing_interface parameter specifies the local source address to be bound, not the target service address. Common use cases include specifying the outbound NIC in an environment with multiple NICs or complying with firewall policies that require traffic to exit from a specified IP address.
  • The NIC name varies depending on the platform. In Linux, eth0 and ens33 are commonly used. In Windows, Ethernet and Wi-Fi are commonly used. You are advised to use the local IP address for better compatibility.
// Common scenarios: specifying the outbound NIC in an environment with multiple NICs or specifying the source IP address as required by the firewall
void example_bind_local_interface(obs_options *obs_options)
{
    // Method 1: Using the local IP address (recommended, compatible across platforms)
    obs_options->request_options.outgoing_interface = "192.168.1.100"; // TODO: Replace it with the actual local IP address.
    // Method 2: Using the NIC name (platform-related)
    // Linux:   "eth0", "ens33"
    // Windows: "Ethernet", "Wi-Fi"
    // obs_options->request_options.outgoing_interface = "eth0";
}

Sample Code – Binding a Single Port

  • The local_port parameter specifies the local source port to be bound, not the target service port. You are advised to use a port number ranging from 1024 to 65535 to avoid conflicts with reserved ports (0 to 1023) and common service ports. Binding a port number less than 1024 may require administrator permissions.
  • When the port specified by local_port is occupied, the SDK attempts to use subsequent ports, limited to the number defined by local_port_range. If they are all occupied, a connection failure message will be returned.
  • In an enterprise network environment, the firewall may restrict outbound ports. Ensure that the bound port is allowed by the firewall.
// Common scenarios: specifying the outbound NIC in an environment with multiple NICs or specifying the source IP address as required by the firewall
void example_bind_local_interface(obs_options *obs_options)
{
    // Method 1: Using the local IP address (recommended, compatible across platforms)
    obs_options->request_options.outgoing_interface = "192.168.1.100"; // TODO: Replace it with the actual local IP address.
    // Method 2: Using the NIC name (platform-related)
    // Linux:   "eth0", "ens33"
    // Windows: "Ethernet", "Wi-Fi"
    // obs_options->request_options.outgoing_interface = "eth0";
}

Sample Code – Binding a Local NIC and Port Range

// Starting from local_port, a total of local_port_range ports are tried.
// For example, if local_port is set to 40000 and local_port_range is set to 10, ports 40000 to 40009 are tried in sequence.
void example_bind_interface_and_port_range(obs_options *obs_options)
{
    // Specify both the local outbound interface and port range.
    obs_options->request_options.outgoing_interface = "192.168.1.100"; // TODO: Replace it with the actual local IP address.
    obs_options->request_options.local_port = 40000;
    obs_options->request_options.local_port_range = 10;  // Try ports 40000 to 40009 in sequence.
}