You must initialize request options (oss_request_options_t) and specify an endpoint when you use Object Storage Service (OSS) SDK for C.
Initialize request options
Use the V4 signature algorithm (recommended)
Use the V1 signature algorithm (not recommend)
We recommend that you use the V4 signature algorithm which provides better security. If you use the V4 signature algorithm, include two additional parameters: region, cn-hangzhou
and signature_version = 4
. Set region to an Alibaba Cloud Region ID. The OSS SDK for C 3.11.0 or later supports the V4 signature algorithm.
The following sample code provides an example on how to create an OSSClient instance by using an OSS endpoint and the V4 signature algorithm. To create an OSSClient instance by using a custom domain name or access credentials obtained from STS, modify the following sample code accordingly.
#include "oss_api.h"
#include "aos_http_io.h"
const char *endpoint = "yourEndpoint";
const char *region = "yourRegion";
void init_options(oss_request_options_t *options)
{
options->config = oss_config_create(options->pool);
aos_str_set(&options->config->endpoint, endpoint);
aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
aos_str_set(&options->config->region, region);
options->config->signature_version = 4;
options->config->is_cname = 0;
options->ctl = aos_http_controller_create(options->pool, 0);
}
int main() {
aos_pool_t *p;
oss_request_options_t *options;
if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
return -1;
}
aos_pool_create(&p, NULL);
options = oss_request_options_create(p);
init_options(options);
aos_pool_destroy(p);
aos_http_io_deinitialize();
return 0;
}
Important
From March 1, 2025, the V1 signature algorithm of OSS is no longer available to new customers with new UIDs. From September 1, 2025, OSS no longer updates and maintains the V1 signature algorithm, and the V1 signature algorithm is no longer available for new buckets. Upgrade V1 signatures to V4 signatures at the earliest opportunity to prevent impact on your business.
Use an OSS endpoint to initialize request options
Use a custom domain name to initialize request options
Use STS-provided temporary access credentials to initialize request options
The following sample code provides an example on how to use an OSS endpoint to initialize request options:
#include "oss_api.h"
#include "aos_http_io.h"
const char *endpoint = "yourEndpoint";
void init_options(oss_request_options_t *options)
{
options->config = oss_config_create(options->pool);
aos_str_set(&options->config->endpoint, endpoint);
aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
options->config->is_cname = 0;
options->ctl = aos_http_controller_create(options->pool, 0);
}
int main() {
aos_pool_t *p;
oss_request_options_t *options;
if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
return -1;
}
aos_pool_create(&p, NULL);
options = oss_request_options_create(p);
init_options(options);
aos_pool_destroy(p);
aos_http_io_deinitialize();
return 0;
}
The following sample code provides an example on how to use a custom domain name to initialize request options:
#include "oss_api.h"
#include "aos_http_io.h"
# Specify the custom domain name. */
const char *endpoint = "yourCustomEndpoint";
void init_options(oss_request_options_t *options) {
options->config = oss_config_create(options->pool);
aos_str_set(&options->config->endpoint, endpoint);
aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
options->config->is_cname = 1;
options->ctl = aos_http_controller_create(options->pool, 0);
}
int main() {
aos_pool_t *p;
oss_request_options_t *options;
if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
return -1;
}
aos_pool_create(&p, NULL);
options = oss_request_options_create(p);
init_options(options);
aos_pool_destroy(p);
aos_http_io_deinitialize();
return 0;
}
The following sample code provides an example on how to use temporary access credentials that are obtained from Security Token Service (STS) to initialize request options:
#include "oss_api.h"
#include "aos_http_io.h"
const char *endpoint = "yourEndpoint";
const char *access_key_id = getenv("YOUR_ACCESS_KEY_ID");
const char *access_key_secret = getenv("YOUR_ACCESS_KEY_SECRET");
const char *sts_token = "<yourSecurityToken>";
void init_options(oss_request_options_t *options)
{
options->config = oss_config_create(options->pool);
aos_str_set(&options->config->endpoint, endpoint);
aos_str_set(&options->config->access_key_id, access_key_id);
aos_str_set(&options->config->access_key_secret, access_key_secret);
aos_str_set(&options->config->sts_token, sts_token);
options->config->is_cname = 0;
options->ctl = aos_http_controller_create(options->pool, 0);
}
int main() {
aos_pool_t *p;
oss_request_options_t *options;
if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
return -1;
}
aos_pool_create(&p, NULL);
options = oss_request_options_create(p);
init_options(options);
aos_pool_destroy(p);
aos_http_io_deinitialize();
return 0;
}
Parameters
The following table describes the common parameters.
Parameter | Description |
speed_limit | The lower limit on the average speed. Unit: bytes/second. Default value: 1024. |
speed_time | The maximum time period allowed if the speed is less than the lower limit on the average speed. Unit: seconds. Default value: 15. Important Both the speed_limit and speed_time parameters are required. If the average speed is less than the lower limit that is specified by the speed_limit parameter for a period of time that is specified by the speed_time parameter, the request is interrupted. |
connect_timeout | The timeout period for establishing a connection. Unit: seconds. Default value: 10. |
dns_cache_timeout | The timeout period of the DNS cache. Unit: seconds. Default value: 60. |
max_memory_size | The maximum size of data that can be written to the memory when data is downloaded. Unit: bytes. By default, the maximum size of data that can be written to the memory when data is downloaded is 1 GB. |
enable_crc | Specifies whether to enable CRC-64. Valid values: |
verify_ssl | Specifies whether to enable SSL-based authentication. Valid values: |
ca_path | The root path of the CA certificate. This parameter is valid when verify_ssl is set to 1. By default, this parameter is left empty. |
ca_file | The path of the CA certificate. This parameter is valid when verify_ssl is set to 1. By default, this parameter is left empty. |
proxy_host | The address of the proxy server in the host:port format. |
proxy_auth | The password of the proxy server in the user:password format. |
Configuration examples
Specify a timeout period
Configure SSL-based authentication
The following sample code provides an example on how to specify a timeout period:
#include "oss_api.h"
#include "aos_http_io.h"
const char *endpoint = "yourEndpoint";
void init_options(oss_request_options_t *options)
{
options->config = oss_config_create(options->pool);
aos_str_set(&options->config->endpoint, endpoint);
aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
options->config->is_cname = 0;
options->ctl = aos_http_controller_create(options->pool, 0);
options->ctl->options->connect_timeout = 10;
options->ctl->options->dns_cache_timeout = 60;
options->ctl->options->speed_limit = 1024;
options->ctl->options->speed_time = 15;
}
int main() {
aos_pool_t *p;
oss_request_options_t *options;
if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
return -1;
}
aos_pool_create(&p, NULL);
options = oss_request_options_create(p);
init_options(options);
aos_pool_destroy(p);
aos_http_io_deinitialize();
return 0;
}
By default, SSL-based authentication is enabled for OSS SDK for C 3.9.2 and later. If SSL-based authentication fails, check whether the path of the SSL certificate is correct or disable SSL-based authentication.
The following sample code provides an example on how to configure SSL-based authentication:
#include "oss_api.h"
#include "aos_http_io.h"
const char *endpoint = "yourEndpoint";
void init_options(oss_request_options_t *options)
{
options->config = oss_config_create(options->pool);
aos_str_set(&options->config->endpoint, endpoint);
aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
options->config->is_cname = 0;
options->ctl = aos_http_controller_create(options->pool, 0);
Configure the verify_ssl parameter to specify whether to enable SSL-based authentication. Valid values: 0 and 1. Default value: 1. The value 1 specifies that SSL-based authentication is enabled.
Configure the ca_path parameter to specify the root path of the CA certificate. This parameter is valid when verify_ssl is set to 1. By default, this parameter is left empty.
Configure the ca_file parameter to specify the path of the CA certificate. This parameter is valid when verify_ssl is set to 1. By default, this parameter is left empty. */
}
int main() {
aos_pool_t *p;
oss_request_options_t *options;
if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
return -1;
}
aos_pool_create(&p, NULL);
options = oss_request_options_create(p);
init_options(options);
aos_pool_destroy(p);
aos_http_io_deinitialize();
return 0;
}