Getting Started

Last updated: 2019-09-24 17:35:40

PDF

Download and Installation

Relevant Resources

Environment Requirements

Required library: libcurl apr apr-util minixml.

Installing the SDK

  1. Download the CMake tool (v2.6.0 and higher recommended) here and install it as shown below:
    ./configure
    make
    make install
  2. Download libcurl (v7.32.0 and higher recommended) here and install it as shown below:
    ./configure
    make
    make install
  3. Download apr (v1.5.2 and higher recommended) here and install it as shown below:
    ./configure
    make
    make install
  4. Download apr-util (v1.5.4 and higher recommended) here and install it as shown below. You need to specify the --with-apr option during installation:
    ./configure --with-apr=/your/apr/install/path
    make
    make install
  5. Download minixml (v2.8 - 2.12 recommended) here and install it as shown below:
    ./configure
    make
    make install
  6. Compile the COS C SDK. Download the XML C SDK source code and run the following compiling commands:
    cmake .
    make
    make install

Getting Started

Below is the general process of using COS XML C SDK.

  1. Initialize the SDK.
  2. Set the request option parameters. For the definitions of parameters such as APPID, SecretId, SecretKey, and Bucket, see COS Glossary.
    • APPID is one of the account IDs assigned by the system after you register for a Tencent Cloud account.
    • “access_key_id” and “access_key_secret” are account API keys.
    • “endpoint” is the COS access domain name. For more information, see Regions and Access Domain Names. For example, the endpoint of Guangzhou region is cos.ap-guangzhou.myqcloud.com.
  3. Set the parameters required for APIs.
  4. Call the SDK API to initiate a request and get the response.

Initialization

int main(int argc, char *argv[])
{
    /* Call the cos_http_io_initialize method at the program entry to perform certain global resource initialization tasks internally covering network, memory, etc. */
    if (cos_http_io_initialize(NULL, 0) != COSE_OK) {
        exit(1);
    }

    /* Call the COS SDK API to upload or download a file */
    /* ... user logic code which is omitted here */

    /* Call the cos_http_io_deinitialize method to release global resources allocated previously before the program ends */
    cos_http_io_deinitialize();
    return 0;
}

Initializing Request Options

/* Equivalent to apr_pool_t, the memory pool for memory management. The implementation code can be found in apr library */
cos_pool_t *pool;
cos_request_options_t *options;

/* Create a new memory pool. The second parameter is NULL, indicating that it is not inherited from other memory pools */
cos_pool_create(&pool, NULL);

/* Create and initialize `options`. This parameter contains global configuration information such as endpoint, access_key_id, acces_key_secret, is_cname, and curl
 * The memory of `options` is allocated by the pool, and will be released upon pool release, so there is no need to release the memory separately.
 */ 
options = cos_request_options_create(pool);
options->config = cos_config_create(options->pool);

/* cos_str_set is a cos_string_t type initialized with a char* string */
cos_str_set(&options->config->endpoint, "<user’s endpoint>");              // Enter the endpoint based on the COS service domain name of your region
cos_str_set(&options->config->access_key_id, "<user’s SecretId>");         // This is the SecretId obtained after you register for the COS service
cos_str_set(&options->config->access_key_secret, "<user’s SecretKey>");    // This is the SecretKey obtained after you register for the COS service
cos_str_set(&options->config->appid, "<user’s AppId>");                    // This is the AppId obtained after you register for the COS service

/* You can use a temporary key by setting sts_token. When you use a temporary key, you need to set access_key_id and access_key_secret to its SecretId and SecretKey */
//cos_str_set(&options->config->sts_token, "MyTokenString");
/* Whether CNAME is used */
options->config->is_cname = 0;

/* Used to set network-related parameters, such as timeout period */
options->ctl = cos_http_controller_create(options->pool, 0);

/* Used to set whether to add Content-MD5 header automatically to the upload request. If `enable` is COS_FALSE, the header will not be automatically added; if `enable` is COS_TRUE, the header will be automatically added. If this parameter is not set, the header will be added by default */
cos_set_content_md5_enable(options->ctl, COS_FALSE);

/* Used to set the request routing address and port. Normally, you do not need to set this parameter. The request will be routed according to the result of domain name resolution */
//cos_set_request_route(options->ctl, "192.168.12.34", 80);

Creating a 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 = NULL;

/* Create a new memory pool. The second parameter is NULL, indicating that it is not inherited from other memory pools */
cos_pool_create(&p, NULL);

/* Create and initialize `options`. This parameter contains global configuration information such as endpoint, access_key_id, acces_key_secret, is_cname, and curl
 * The memory of `options` is allocated by the pool, and will be released upon pool release, so there is no need to release the memory separately.
 */
options = cos_request_options_create(p);
options->config = cos_config_create(options->pool);
init_test_config(options->config, is_cname);

/* Set configuration information such as appid, endpoint, access_key_id, acces_key_secret, is_cname, and curl parameters */
cos_str_set(&options->config->endpoint, TEST_COS_ENDPOINT);
cos_str_set(&options->config->access_key_id, TEST_ACCESS_KEY_ID);
cos_str_set(&options->config->access_key_secret, TEST_ACCESS_KEY_SECRET);
cos_str_set(&options->config->appid, TEST_APPID);
options->config->is_cname = is_cname;
options->ctl = cos_http_controller_create(options->pool, 0);
/* Enter the bucket name in the format of BucketName-APPID.  */
cos_str_set(&bucket, TEST_BUCKET_NAME);

/* Call an API to create a bucket */
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");
}

//destroy memory pool
cos_pool_destroy(p); 

Querying the Object List

cos_pool_t *p = NULL;
int is_cname = 0;
cos_status_t *s = NULL;
cos_request_options_t *options = NULL;
cos_list_object_params_t *list_params = NULL;
cos_string_t bucket;
cos_table_t *resp_headers = NULL;

/* Create a new memory pool. The second parameter is NULL, indicating that it is not inherited from other memory pools */
cos_pool_create(&p, NULL);

/* Create and initialize `options`. This parameter contains global configuration information such as endpoint, access_key_id, acces_key_secret, is_cname, and curl
 * The memory of `options` is allocated by the pool, and will be released upon pool release, so there is no need to release the memory separately.
 */
options = cos_request_options_create(p);
options->config = cos_config_create(options->pool);
init_test_config(options->config, is_cname);

/* Set configuration information such as appid, endpoint, access_key_id, acces_key_secret, is_cname, and curl parameters */
cos_str_set(&options->config->endpoint, TEST_COS_ENDPOINT);
cos_str_set(&options->config->access_key_id, TEST_ACCESS_KEY_ID);
cos_str_set(&options->config->access_key_secret, TEST_ACCESS_KEY_SECRET);
cos_str_set(&options->config->appid, TEST_APPID);
options->config->is_cname = is_cname;
options->ctl = cos_http_controller_create(options->pool, 0);
/* The bucket name entered here must be in the format of BucketName-APPID. */
cos_str_set(&bucket, TEST_BUCKET_NAME);

/* Call an API to query object list */
list_params = cos_create_list_object_params(p);
cos_str_set(&list_params->encoding_type, "url");
s = cos_list_object(options, &bucket, list_params, &resp_headers);
if (cos_status_is_ok(s)) {
        printf("list object succeeded\n");
} else {
        printf("list object failed\n");
}

//destroy memory pool
cos_pool_destroy(p); 

Uploading an Object

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_string_t object;
cos_string_t file;
cos_table_t *resp_headers = NULL;

/* Create a new memory pool. The second parameter is NULL, indicating that it is not inherited from other memory pools */
cos_pool_create(&p, NULL);

/* Create and initialize `options`. This parameter contains global configuration information such as endpoint, access_key_id, acces_key_secret, is_cname, and curl
 * The memory of `options` is allocated by the pool, and will be released upon pool release, so there is no need to release the memory separately.
 */
options = cos_request_options_create(p);
options->config = cos_config_create(options->pool);
init_test_config(options->config, is_cname);

/* Set configuration information such as appid, endpoint, access_key_id, acces_key_secret, is_cname, and curl parameters */
cos_str_set(&options->config->endpoint, TEST_COS_ENDPOINT);
cos_str_set(&options->config->access_key_id, TEST_ACCESS_KEY_ID);
cos_str_set(&options->config->access_key_secret, TEST_ACCESS_KEY_SECRET);
cos_str_set(&options->config->appid, TEST_APPID);
options->config->is_cname = is_cname;
options->ctl = cos_http_controller_create(options->pool, 0);
/* The bucket name entered here must be in the format of BucketName-APPID. */
cos_str_set(&bucket, TEST_BUCKET_NAME);

/* Call an API to upload an object */
cos_str_set(&file, TEST_DOWNLOAD_NAME);
cos_str_set(&object, TEST_OBJECT_NAME);
s = cos_put_object_from_file(options, &bucket, &object, &file, NULL, &resp_headers);
if (cos_status_is_ok(s)) {
        printf("put object succeeded\n");
} else {
        printf("put object failed\n");
}

//destroy memory pool
cos_pool_destroy(p); 

Downloading an Object

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_string_t object;
cos_string_t file;
cos_table_t *resp_headers = NULL;

/* Create a new memory pool. The second parameter is NULL, indicating that it is not inherited from other memory pools */
cos_pool_create(&p, NULL);

/* Create and initialize `options`. This parameter contains global configuration information such as endpoint, access_key_id, acces_key_secret, is_cname, and curl
 * The memory of `options` is allocated by the pool, and will be released upon pool release, so there is no need to release the memory separately.
 */
options = cos_request_options_create(p);
options->config = cos_config_create(options->pool);
init_test_config(options->config, is_cname);

/* Set configuration information such as appid, endpoint, access_key_id, acces_key_secret, is_cname, and curl parameters */
cos_str_set(&options->config->endpoint, TEST_COS_ENDPOINT);
cos_str_set(&options->config->access_key_id, TEST_ACCESS_KEY_ID);
cos_str_set(&options->config->access_key_secret, TEST_ACCESS_KEY_SECRET);
cos_str_set(&options->config->appid, TEST_APPID);
options->config->is_cname = is_cname;
options->ctl = cos_http_controller_create(options->pool, 0);
/* The bucket name entered here must be in the format of BucketName-APPID. */
cos_str_set(&bucket, TEST_BUCKET_NAME);

/* Call an API to download an object */
cos_str_set(&file, TEST_DOWNLOAD_NAME);
cos_str_set(&object, TEST_OBJECT_NAME);
s = cos_get_object_to_file(options, &bucket, &object, NULL, NULL, &file, &resp_headers);
if (cos_status_is_ok(s)) {
        printf("get object succeeded\n");
} else {
        printf("get object failed\n");
}

//destroy memory pool
cos_pool_destroy(p); 

Deleting an Object

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_string_t object;
cos_table_t *resp_headers = NULL;

/* Create a new memory pool. The second parameter is NULL, indicating that it is not inherited from other memory pools */
cos_pool_create(&p, NULL);

/* Create and initialize `options`. This parameter contains global configuration information such as endpoint, access_key_id, access_key_secret, is_cname, and curl
 * The memory of `options` is allocated by the pool, and will be released upon pool release, so there is no need to release the memory separately.
 */
options = cos_request_options_create(p);
options->config = cos_config_create(options->pool);
init_test_config(options->config, is_cname);

/* Set configuration information such as appid, endpoint, access_key_id, acces_key_secret, is_cname, and curl parameters */
cos_str_set(&options->config->endpoint, TEST_COS_ENDPOINT);
cos_str_set(&options->config->access_key_id, TEST_ACCESS_KEY_ID);
cos_str_set(&options->config->access_key_secret, TEST_ACCESS_KEY_SECRET);
cos_str_set(&options->config->appid, TEST_APPID);
options->config->is_cname = is_cname;
options->ctl = cos_http_controller_create(options->pool, 0);
/* The bucket name entered here must be in the format of BucketName-APPID. */
cos_str_set(&bucket, TEST_BUCKET_NAME);

/* Call an API to delete an object */
cos_str_set(&object, TEST_OBJECT_NAME);
s = cos_delete_object(options, &bucket, &object, &resp_headers);
if (cos_status_is_ok(s)) {
        printf("delete object succeeded\n");
} else {
        printf("delete object failed\n");
}

//destroy memory pool
cos_pool_destroy(p);