In this chapter, you will learn how to complete some basic operations of the OSS C SDK.

Step 1. Initialize the runtime environment of OSS C SDK

When using the OSS C SDK, you must first initialize the runtime environment, and clear the runtime environment before you stop using it. The following code demonstrates the initialization of the OSS C SDK runtime environment:

int main(int argc, char *argv[])
{
    /* Call the aos_http_io_initialize method at the project entry. This method will initialize global resources involving the network and memory */
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        exit(1);
    }
    /* Call the OSS SDK interface to upload or download an object */
    /* ... The user logic code. Skipped. */
    /* Before the project ends, call the aos_http_io_deinitialize method to release the previously allocated global resources  */
    aos_http_io_deinitialize();
    return 0;
}

Notice:

• The aos_http_io_initialize method initializes the OSS C SDK runtime environment. The first parameter can be used to customize the user agent content for statistics in the future.
• The aos_http_io_deinitialize method clears the OSS C SDK runtime environment.

Step 2. Initialize the request options

Request options for all operations of OSS C SDK should be initialized. You can use the following code to initialize the request options:

    /* Equivalent to apr_pool_t. It is used for the memory pool of memory management and the implementation code is in the apr library */
    aos_pool_t *pool;
    oss_request_options_t *options;
    /* Re-create a new memory pool. The second parameter is NULL, indicating that it does not inherit from any other memory pool */
    aos_pool_create(&pool, NULL);
    /* Create and initialize options. This parameter mainly includes endpoint, access_key_id, acces_key_secret, is_cname, and curl parameters among other global configuration information
     * The options memory is allocated by the pool. After the pool is released, the options memory is also released meaning you don't need to release the memory separately
     */ 
    options = oss_request_options_create(pool);
    options->config = oss_config_create(options->pool);
    /* aos_str_set is to initialize the aos_string_t data type with a char* string*/
    aos_str_set(&options->config->endpoint, "<Your endpoint>");
    aos_str_set(&options->config->access_key_id, "<Your AccessKeyId>");
    aos_str_set(&options->config->access_key_secret, "<Your AccessKeySecret>");
    /* Is CNAME used? */
    options->config->is_cname = 0;
    /* Used to set network-related parameters, such as the timeout value*/
    options->ctl = aos_http_controller_create(options->pool, 0);

Step 3. Create a bucket

You can create a bucket with the following code:

    aos_pool_t *p;
    oss_request_options_t *options;
    aos_status_t *s; 
    aos_table_t *resp_headers;
    oss_acl_e oss_acl = OSS_ACL_PRIVATE;
    char *bucket_name = "<Name of your bucket>";
    aos_string_t bucket;
    aos_pool_create(&p, NULL);
    options = oss_request_options_create(p);
    init_options(options);
    /* Assign a char* to the aos_string_t bucket */
    aos_str_set(&bucket, bucket_name);
    s = oss_create_bucket(options, &bucket, oss_acl, &resp_headers);
    /* Identify whether the request succeeds */
    if (aos_status_is_ok(s)) {
        printf("create bucket succeeded\n");
    } else {
        printf("create bucket failed\n");
    }
    /* After a request is executed, releasing the memory pool will actually release memory allocated to various parts used during the request process */
    aos_pool_destroy(p);

Notice:

• For bucket naming conventions, refer to OSS Basic Concepts.
• The bucket name cannot be the same with existing bucket names of other users in OSS. To create a bucket successfully, you need to select a unique bucket name.
• The returned value of oss_create_bucket is of the aos_status_t* type, including code(http code), error_code, error_msg and req_id. The req_id can assist in troubleshooting. Other interfaces will also return aos_status_t* values unless otherwise specified.

Step 4. Upload an object

Objects are the most basic data units in OSS. You can use the following code to upload an object:

    aos_pool_t *p;
    oss_request_options_t *options;
    aos_status_t *s;
    aos_table_t *headers;
    aos_table_t *resp_headers;
    char *bucket_name = "<Name of your bucket>";
    char *object_name = "<Name of your object>";
    aos_string_t bucket;
    aos_string_t object;
    char *data = "object content";
    aos_list_t buffer;
    aos_buf_t *content;
    aos_pool_create(&p, NULL);
    /* Create and initialize options */
    options = oss_request_options_create(p);
    init_options(options);
    /* Initialize parameters */
    aos_str_set(&object, object_name);
    aos_str_set(&bucket, bucket_name);
    headers = aos_table_make(p, 0);
    /* Convert char* data to aos_list_t as required by the oss_put_object_from_buffer interface */
    aos_list_init(&buffer);
    content = aos_buf_pack(options->pool, data, strlen(data));
    aos_list_add_tail(&content->node, &buffer);
    /* Upload the object */
    s = oss_put_object_from_buffer(options, &bucket, &object, &buffer, headers, &resp_headers);
    /* Identify whether the request succeeds */
    if (aos_status_is_ok(s)) {
        printf("put file succeeded\n");
    } else {
        printf("put file failed\n");
    }
    /* Release the resources */
    aos_pool_destroy(p);

Note: For more details about object uploading, see Object Uploading.

Step 5. List all objects in the bucket

The following code checks objects in a bucket after you upload objects to the bucket:

    aos_pool_t *p;
    oss_request_options_t *options;
    aos_status_t *s;
    aos_table_t *resp_headers;
    char *bucket_name = "<Name of your bucket>";
    aos_string_t bucket;
    oss_list_object_params_t *params;
    oss_list_object_content_t *content;
    int max_ret = 1000;
    char *key;
    aos_pool_create(&p, NULL);
    /* Create and initialize options */
    options = oss_request_options_create(p);
    init_options(options);
    /* Initialize parameters */
    aos_str_set(&bucket, bucket_name);
    params = oss_create_list_object_params(p);
    params->max_ret = max_ret;
    aos_str_set(&params->prefix, "<prefix>");
    aos_str_set(&params->delimiter, "<delimiter>");
    aos_str_set(&params->marker, "<marker>");
    s = oss_list_object(options, &bucket, params, &resp_headers);
    /* Identify whether the request succeeds */
    if (aos_status_is_ok(s)) {
        printf("list file succeeded\n");
    } else {
        printf("list file failed\n");
    }
    /* Get the name of each object  */
    aos_list_for_each_entry(content, &params->object_list, node) {
        key = apr_psprintf(p, "%.*s", content->key.len, content->key.data);
    }
    /* Release the resources */
    aos_pool_destroy(p);

Note: For more information on flexible parameter configuration, refer to Object Management.

Step 6. Download a specified object

You can refer to the following code to download a specified object in a simple way:

    aos_pool_t *p;
    oss_request_options_t *options;
    aos_status_t *s;
    aos_table_t *headers;
    aos_table_t *resp_headers;
    char *bucket_name = "<Name of your bucket>";
    char *object_name = "<Name of your object>";
    aos_string_t bucket;
    aos_string_t object;
    aos_list_t buffer;
    aos_buf_t *content;
    char *buf;
    int64_t len = 0;
    int64_t size = 0;
    int64_t pos = 0;
    aos_pool_create(&p, NULL);
    /* Create and initialize options */
    options = oss_request_options_create(p);
    init_options(options);
    /* Initialize parameters */
    aos_str_set(&object, object_name);
    aos_str_set(&bucket, bucket_name);
    headers = aos_table_make(p, 1);
    /* Download the object to the buffer */
    aos_list_init(&buffer);
    s = oss_get_object_to_buffer(options, &bucket, &object, headers, &buffer, &resp_headers);
    /* Identify whether the request succeeds */
    if (aos_status_is_ok(s)) {
        printf("get file succeeded\n");
    } else {
        printf("get file failed\n");
    }
    /* Convert the aos_list_t in the buffer to char*  and calculate the total length of the object read */
    len = aos_buf_list_len(&buffer);
    buf = aos_pcalloc(p, len + 1);
    buf[len] = '\0';
    aos_list_for_each_entry(content, &buffer, node) {
        size = aos_buf_size(content);
            memcpy(buf + pos, content->pos, size);
            pos += size;
    }
    /* Release the resources */
    aos_pool_destroy(p);

Note: For more details about object downloading, see Object Downloading.