Overview
This document provides an overview of APIs and SDK sample codes related to basic bucket operations and access control lists (ACL).
Basic operations
API |
Operation |
Description |
PUT Bucket |
Creating a bucket |
Creates a bucket under a specified account |
DELETE Bucket |
Deleting a bucket |
Deletes an empty bucket from a specified account |
Extracting a bucket and its permissions
API |
Operation |
Description |
HEAD Bucket |
Checking a bucket and its permissions |
Checks whether a bucket exists and whether you have permission to access it |
Basic operations
Creating a bucket
Description
This API is used to create a bucket under a specified account.
Method prototype
cos_status_t *cos_create_bucket(const cos_request_options_t *options,
const cos_string_t *bucket,
cos_acl_e cos_acl,
cos_table_t **resp_headers);
Parameter description
Parameter |
Description |
Type |
options |
COS request options |
Struct |
bucket |
Bucket name in the format: BucketName-APPID |
String |
cos_acl |
Allow users to customize permissions. Valid values: COS_ACL_PRIVATE(0) (default), COS_ACL_PUBLIC_READ(1) , COS_ACL_PUBLIC_READ_WRITE(2) |
Enum |
resp_headers |
Returns the HTTP response headers |
Struct |
Response description
Response Parameter |
Description |
Type |
code |
Error code |
Int |
error_code |
Error code content |
String |
error_msg |
Error code description |
String |
req_id |
Request message ID |
String |
Sample
#include "cos_http_io.h"
#include "cos_api.h"
#include "cos_log.h"
#include <unistd.h>
static char TEST_COS_ENDPOINT[] = "cos.ap-guangzhou.myqcloud.com";
static char *TEST_ACCESS_KEY_ID;
static char *TEST_ACCESS_KEY_SECRET;
static char TEST_APPID[] = "<APPID>";
static char TEST_BUCKET_NAME[] = "<bucketname-appid>";
void log_status(cos_status_t *s)
{
cos_warn_log("status->code: %d", s->code);
if (s->error_code) cos_warn_log("status->error_code: %s", s->error_code);
if (s->error_msg) cos_warn_log("status->error_msg: %s", s->error_msg);
if (s->req_id) cos_warn_log("status->req_id: %s", s->req_id);
}
void init_test_config(cos_config_t *config, int is_cname)
{
cos_str_set(&config->endpoint, TEST_COS_ENDPOINT);
cos_str_set(&config->access_key_id, TEST_ACCESS_KEY_ID);
cos_str_set(&config->access_key_secret, TEST_ACCESS_KEY_SECRET);
cos_str_set(&config->appid, TEST_APPID);
config->is_cname = is_cname;
}
void init_test_request_options(cos_request_options_t *options, int is_cname)
{
options->config = cos_config_create(options->pool);
init_test_config(options->config, is_cname);
options->ctl = cos_http_controller_create(options->pool, 0);
}
void test_create_bucket()
{
cos_pool_t *p = NULL;
int is_cname = 0;
cos_status_t *s = NULL;
cos_request_options_t *options = NULL;
cos_acl_e cos_acl = COS_ACL_PRIVATE;
cos_string_t bucket;
cos_table_t *resp_headers;
cos_pool_create(&p, NULL);
options = cos_request_options_create(p);
init_test_request_options(options, is_cname);
cos_str_set(&bucket, TEST_BUCKET_NAME);
s = cos_create_bucket(options, &bucket, cos_acl, &resp_headers);
if (cos_status_is_ok(s)) {
printf("create bucket succeeded\n");
} else {
printf("create bucket failed\n");
}
cos_pool_destroy(p);
}
int main(int argc, char *argv[])
{
TEST_ACCESS_KEY_ID = getenv("COS_SECRETID");
TEST_ACCESS_KEY_SECRET = getenv("COS_SECRETKEY");
if (cos_http_io_initialize(NULL, 0) != COSE_OK) {
exit(1);
}
cos_log_set_level(COS_LOG_WARN);
cos_log_set_output(NULL);
test_create_bucket();
cos_http_io_deinitialize();
return 0;
}
Deleting a bucket
Description
This API is used to delete an empty bucket under a specified account.
Method prototype
cos_status_t *cos_delete_bucket(const cos_request_options_t *options,
const cos_string_t *bucket,
cos_table_t **resp_headers);
Parameter description
Parameter |
Description |
Type |
options |
COS request options |
Struct |
bucket |
Bucket name in the format: BucketName-APPID |
String |
resp_headers |
Returns the HTTP response headers |
Struct |
Response description
Response Parameter |
Description |
Type |
code |
Error code |
Int |
error_code |
Error code content |
String |
error_msg |
Error code description |
String |
req_id |
Request message ID |
String |
Sample
#include "cos_http_io.h"
#include "cos_api.h"
#include "cos_log.h"
#include <unistd.h>
static char TEST_COS_ENDPOINT[] = "cos.ap-guangzhou.myqcloud.com";
static char *TEST_ACCESS_KEY_ID;
static char *TEST_ACCESS_KEY_SECRET;
static char TEST_APPID[] = "<APPID>";
static char TEST_BUCKET_NAME[] = "<bucketname-appid>";
void log_status(cos_status_t *s)
{
cos_warn_log("status->code: %d", s->code);
if (s->error_code) cos_warn_log("status->error_code: %s", s->error_code);
if (s->error_msg) cos_warn_log("status->error_msg: %s", s->error_msg);
if (s->req_id) cos_warn_log("status->req_id: %s", s->req_id);
}
void init_test_config(cos_config_t *config, int is_cname)
{
cos_str_set(&config->endpoint, TEST_COS_ENDPOINT);
cos_str_set(&config->access_key_id, TEST_ACCESS_KEY_ID);
cos_str_set(&config->access_key_secret, TEST_ACCESS_KEY_SECRET);
cos_str_set(&config->appid, TEST_APPID);
config->is_cname = is_cname;
}
void init_test_request_options(cos_request_options_t *options, int is_cname)
{
options->config = cos_config_create(options->pool);
init_test_config(options->config, is_cname);
options->ctl = cos_http_controller_create(options->pool, 0);
}
void test_delete_bucket()
{
cos_pool_t *p = NULL;
int is_cname = 0;
cos_status_t *s = NULL;
cos_request_options_t *options = NULL;
cos_string_t bucket;
cos_table_t *resp_headers;
cos_pool_create(&p, NULL);
options = cos_request_options_create(p);
init_test_request_options(options, is_cname);
cos_str_set(&bucket, TEST_BUCKET_NAME);
s = cos_delete_bucket(options, &bucket, &resp_headers);
if (cos_status_is_ok(s)) {
printf("create bucket succeeded\n");
} else {
printf("create bucket failed\n");
}
cos_pool_destroy(p);
}
int main(int argc, char *argv[])
{
TEST_ACCESS_KEY_ID = getenv("COS_SECRETID");
TEST_ACCESS_KEY_SECRET = getenv("COS_SECRETKEY");
if (cos_http_io_initialize(NULL, 0) != COSE_OK) {
exit(1);
}
cos_log_set_level(COS_LOG_WARN);
cos_log_set_output(NULL);
test_delete_bucket();
cos_http_io_deinitialize();
return 0;
}
Checking whether a bucket exists
Description
This API is used to check whether a bucket exists. It actually calls the HEAD Bucket
API to perform the action.
Method prototype
cos_status_t *cos_check_bucket_exist(const cos_request_options_t *options,
const cos_string_t *bucket,
cos_bucket_exist_status_e *bucket_exist,
cos_table_t **resp_headers)
Parameter description
Parameter |
Description |
Type |
options |
COS request options |
Struct |
bucket |
Bucket name in the format: BucketName-APPID |
String |
bucket_exist |
Whether a bucket exists. Enumerated values: exist , non exist , unknown (no explicit state is obtained) |
Enum |
resp_headers |
Returns the HTTP response headers |
Struct |
Response description
Response Parameter |
Description |
Type |
code |
Error code |
Int |
error_code |
Error code content |
String |
error_msg |
Error code description |
String |
req_id |
Request message ID |
String |
Sample
#include "cos_http_io.h"
#include "cos_api.h"
#include "cos_log.h"
#include <unistd.h>
static char TEST_COS_ENDPOINT[] = "cos.ap-guangzhou.myqcloud.com";
static char *TEST_ACCESS_KEY_ID;
static char *TEST_ACCESS_KEY_SECRET;
static char TEST_APPID[] = "<APPID>";
static char TEST_BUCKET_NAME[] = "<bucketname-appid>";
void log_status(cos_status_t *s)
{
cos_warn_log("status->code: %d", s->code);
if (s->error_code) cos_warn_log("status->error_code: %s", s->error_code);
if (s->error_msg) cos_warn_log("status->error_msg: %s", s->error_msg);
if (s->req_id) cos_warn_log("status->req_id: %s", s->req_id);
}
void init_test_config(cos_config_t *config, int is_cname)
{
cos_str_set(&config->endpoint, TEST_COS_ENDPOINT);
cos_str_set(&config->access_key_id, TEST_ACCESS_KEY_ID);
cos_str_set(&config->access_key_secret, TEST_ACCESS_KEY_SECRET);
cos_str_set(&config->appid, TEST_APPID);
config->is_cname = is_cname;
}
void init_test_request_options(cos_request_options_t *options, int is_cname)
{
options->config = cos_config_create(options->pool);
init_test_config(options->config, is_cname);
options->ctl = cos_http_controller_create(options->pool, 0);
}
void test_check_bucket_exist()
{
cos_pool_t *pool = NULL;
int is_cname = 0;
cos_status_t *status = NULL;
cos_request_options_t *options = NULL;
cos_string_t bucket;
cos_table_t *resp_headers = NULL;
cos_bucket_exist_status_e bucket_exist;
cos_pool_create(&pool, NULL);
options = cos_request_options_create(pool);
init_test_request_options(options, is_cname);
cos_str_set(&bucket, TEST_BUCKET_NAME);
status = cos_check_bucket_exist(options, &bucket, &bucket_exist, &resp_headers);
if (bucket_exist == COS_BUCKET_NON_EXIST) {
printf("bucket: %.*s non exist.\n", bucket.len, bucket.data);
} else if (bucket_exist == COS_BUCKET_EXIST) {
printf("bucket: %.*s exist.\n", bucket.len, bucket.data);
} else {
printf("bucket: %.*s unknown status.\n", bucket.len, bucket.data);
log_status(status);
}
cos_pool_destroy(pool);
}
int main(int argc, char *argv[])
{
TEST_ACCESS_KEY_ID = getenv("COS_SECRETID");
TEST_ACCESS_KEY_SECRET = getenv("COS_SECRETKEY");
if (cos_http_io_initialize(NULL, 0) != COSE_OK) {
exit(1);
}
cos_log_set_level(COS_LOG_WARN);
cos_log_set_output(NULL);
test_check_bucket_exist();
cos_http_io_deinitialize();
return 0;
}
Was this page helpful?