Document Center

Quick start

Last Updated: Sep 27, 2017

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: 

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

Note:

  • 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: 

  1.     /* Equivalent to apr_pool_t. It is used for the memory pool of memory management and the implementation code is in the apr library */
  2.     aos_pool_t *pool;
  3.     oss_request_options_t *options;
  5.     /* Re-create a new memory pool. The second parameter is NULL, indicating that it does not inherit from any other memory pool */
  6.     aos_pool_create(&pool, NULL);
  8.     /* 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
  9.      * 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
  10.      */ 
  11.     options = oss_request_options_create(pool);
  12.     options->config = oss_config_create(options->pool);
  14.     /* aos_str_set is to initialize the aos_string_t data type with a char* string*/
  15.     aos_str_set(&options->config->endpoint, "<Your endpoint>");
  16.     aos_str_set(&options->config->access_key_id, "<Your AccessKeyId>");
  17.     aos_str_set(&options->config->access_key_secret, "<Your AccessKeySecret>");
  19.     /* Is CNAME used? */
  20.     options->config->is_cname = 0;
  22.     /* Used to set network-related parameters, such as the timeout value*/
  23.     options->ctl = aos_http_controller_create(options->pool, 0);

Step 3. Create a bucket

You can create a bucket with the following code:

  1.     aos_pool_t *p;
  2.     oss_request_options_t *options;
  3.     aos_status_t *s; 
  4.     aos_table_t *resp_headers;
  5.     oss_acl_e oss_acl = OSS_ACL_PRIVATE;
  6.     char *bucket_name = "<Name of your bucket>";
  7.     aos_string_t bucket;
  9.     aos_pool_create(&p, NULL);
  11.     options = oss_request_options_create(p);
  12.     init_options(options);
  14.     /* Assign a char* to the aos_string_t bucket */
  15.     aos_str_set(&bucket, bucket_name);
  16.     s = oss_create_bucket(options, &bucket, oss_acl, &resp_headers);
  18.     /* Identify whether the request succeeds */
  19.     if (aos_status_is_ok(s)) {
  20.         printf("create bucket succeeded\n");
  21.     } else {
  22.         printf("create bucket failed\n");
  23.     }
  25.     /* After a request is executed, releasing the memory pool will actually release memory allocated to various parts used during the request process */
  26.     aos_pool_destroy(p);

Note:

  • 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:

  1.     aos_pool_t *p;
  2.     oss_request_options_t *options;
  3.     aos_status_t *s;
  4.     aos_table_t *headers;
  5.     aos_table_t *resp_headers;
  6.     char *bucket_name = "<Name of your bucket>";
  7.     char *object_name = "<Name of your object>";
  8.     aos_string_t bucket;
  9.     aos_string_t object;
  10.     char *data = "object content";
  11.     aos_list_t buffer;
  12.     aos_buf_t *content;
  14.     aos_pool_create(&p, NULL);
  16.     /* Create and initialize options */
  17.     options = oss_request_options_create(p);
  18.     init_options(options);
  20.     /* Initialize parameters */
  21.     aos_str_set(&object, object_name);
  22.     aos_str_set(&bucket, bucket_name);
  23.     headers = aos_table_make(p, 0);
  25.     /* Convert char* data to aos_list_t as required by the oss_put_object_from_buffer interface */
  26.     aos_list_init(&buffer);
  27.     content = aos_buf_pack(options->pool, data, strlen(data));
  28.     aos_list_add_tail(&content->node, &buffer);
  30.     /* Upload the object */
  31.     s = oss_put_object_from_buffer(options, &bucket, &object, &buffer, headers, &resp_headers);
  33.     /* Identify whether the request succeeds */
  34.     if (aos_status_is_ok(s)) {
  35.         printf("put file succeeded\n");
  36.     } else {
  37.         printf("put file failed\n");
  38.     }
  40.     /* Release the resources */
  41.     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:

  1.     aos_pool_t *p;
  2.     oss_request_options_t *options;
  3.     aos_status_t *s;
  4.     aos_table_t *resp_headers;
  5.     char *bucket_name = "<Name of your bucket>";
  6.     aos_string_t bucket;
  7.     oss_list_object_params_t *params;
  8.     oss_list_object_content_t *content;
  9.     int max_ret = 1000;
  10.     char *key;
  12.     aos_pool_create(&p, NULL);
  14.     /* Create and initialize options */
  15.     options = oss_request_options_create(p);
  16.     init_options(options);
  18.     /* Initialize parameters */
  19.     aos_str_set(&bucket, bucket_name);
  20.     params = oss_create_list_object_params(p);
  21.     params->max_ret = max_ret;
  22.     aos_str_set(&params->prefix, "<prefix>");
  23.     aos_str_set(&params->delimiter, "<delimiter>");
  24.     aos_str_set(&params->marker, "<marker>");
  26.     s = oss_list_object(options, &bucket, params, &resp_headers);
  28.     /* Identify whether the request succeeds */
  29.     if (aos_status_is_ok(s)) {
  30.         printf("list file succeeded\n");
  31.     } else {
  32.         printf("list file failed\n");
  33.     }
  35.     /* Get the name of each object  */
  36.     aos_list_for_each_entry(content, &params->object_list, node) {
  37.         key = apr_psprintf(p, "%.*s", content->key.len, content->key.data);
  38.     }
  40.     /* Release the resources */
  41.     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:

  1.     aos_pool_t *p;
  2.     oss_request_options_t *options;
  3.     aos_status_t *s;
  4.     aos_table_t *headers;
  5.     aos_table_t *resp_headers;
  6.     char *bucket_name = "<Name of your bucket>";
  7.     char *object_name = "<Name of your object>";
  8.     aos_string_t bucket;
  9.     aos_string_t object;
  10.     aos_list_t buffer;
  11.     aos_buf_t *content;
  12.     char *buf;
  13.     int64_t len = 0;
  14.     int64_t size = 0;
  15.     int64_t pos = 0;
  17.     aos_pool_create(&p, NULL);
  19.     /* Create and initialize options */
  20.     options = oss_request_options_create(p);
  21.     init_options(options);
  23.     /* Initialize parameters */
  24.     aos_str_set(&object, object_name);
  25.     aos_str_set(&bucket, bucket_name);
  26.     headers = aos_table_make(p, 1);
  28.     /* Download the object to the buffer */
  29.     aos_list_init(&buffer);
  30.     s = oss_get_object_to_buffer(options, &bucket, &object, headers, &buffer, &resp_headers);
  32.     /* Identify whether the request succeeds */
  33.     if (aos_status_is_ok(s)) {
  34.         printf("get file succeeded\n");
  35.     } else {
  36.         printf("get file failed\n");
  37.     }
  39.     /* Convert the aos_list_t in the buffer to char*  and calculate the total length of the object read */
  40.     len = aos_buf_list_len(&buffer);
  41.     buf = aos_pcalloc(p, len + 1);
  42.     buf[len] = '\0';
  43.     aos_list_for_each_entry(content, &buffer, node) {
  44.         size = aos_buf_size(content);
  45.             memcpy(buf + pos, content->pos, size);
  46.             pos += size;
  47.     }
  49.     /* Release the resources */
  50.     aos_pool_destroy(p);

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

Thank you! We've received your feedback.