Quick start

Last Updated: Aug 09, 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. }
  7. /* Call the OSS SDK interface to upload or download an object */
  8. /* ... The user logic code. Skipped. */
  9. /* Before the project ends, call the aos_http_io_deinitialize method to release the previously allocated global resources */
  10. aos_http_io_deinitialize();
  11. return 0;
  12. }

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:

  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;
  4. /* Re-create a new memory pool. The second parameter is NULL, indicating that it does not inherit from any other memory pool */
  5. aos_pool_create(&pool, NULL);
  6. /* 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
  7. * 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
  8. */
  9. options = oss_request_options_create(pool);
  10. options->config = oss_config_create(options->pool);
  11. /* aos_str_set is to initialize the aos_string_t data type with a char* string*/
  12. aos_str_set(&options->config->endpoint, "<Your endpoint>");
  13. aos_str_set(&options->config->access_key_id, "<Your AccessKeyId>");
  14. aos_str_set(&options->config->access_key_secret, "<Your AccessKeySecret>");
  15. /* Is CNAME used? */
  16. options->config->is_cname = 0;
  17. /* Used to set network-related parameters, such as the timeout value*/
  18. 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;
  8. aos_pool_create(&p, NULL);
  9. options = oss_request_options_create(p);
  10. init_options(options);
  11. /* Assign a char* to the aos_string_t bucket */
  12. aos_str_set(&bucket, bucket_name);
  13. s = oss_create_bucket(options, &bucket, oss_acl, &resp_headers);
  14. /* Identify whether the request succeeds */
  15. if (aos_status_is_ok(s)) {
  16. printf("create bucket succeeded\n");
  17. } else {
  18. printf("create bucket failed\n");
  19. }
  20. /* After a request is executed, releasing the memory pool will actually release memory allocated to various parts used during the request process */
  21. 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:

  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;
  13. aos_pool_create(&p, NULL);
  14. /* Create and initialize options */
  15. options = oss_request_options_create(p);
  16. init_options(options);
  17. /* Initialize parameters */
  18. aos_str_set(&object, object_name);
  19. aos_str_set(&bucket, bucket_name);
  20. headers = aos_table_make(p, 0);
  21. /* Convert char* data to aos_list_t as required by the oss_put_object_from_buffer interface */
  22. aos_list_init(&buffer);
  23. content = aos_buf_pack(options->pool, data, strlen(data));
  24. aos_list_add_tail(&content->node, &buffer);
  25. /* Upload the object */
  26. s = oss_put_object_from_buffer(options, &bucket, &object, &buffer, headers, &resp_headers);
  27. /* Identify whether the request succeeds */
  28. if (aos_status_is_ok(s)) {
  29. printf("put file succeeded\n");
  30. } else {
  31. printf("put file failed\n");
  32. }
  33. /* Release the resources */
  34. 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;
  11. aos_pool_create(&p, NULL);
  12. /* Create and initialize options */
  13. options = oss_request_options_create(p);
  14. init_options(options);
  15. /* Initialize parameters */
  16. aos_str_set(&bucket, bucket_name);
  17. params = oss_create_list_object_params(p);
  18. params->max_ret = max_ret;
  19. aos_str_set(&params->prefix, "<prefix>");
  20. aos_str_set(&params->delimiter, "<delimiter>");
  21. aos_str_set(&params->marker, "<marker>");
  22. s = oss_list_object(options, &bucket, params, &resp_headers);
  23. /* Identify whether the request succeeds */
  24. if (aos_status_is_ok(s)) {
  25. printf("list file succeeded\n");
  26. } else {
  27. printf("list file failed\n");
  28. }
  29. /* Get the name of each object */
  30. aos_list_for_each_entry(content, &params->object_list, node) {
  31. key = apr_psprintf(p, "%.*s", content->key.len, content->key.data);
  32. }
  33. /* Release the resources */
  34. 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;
  16. aos_pool_create(&p, NULL);
  17. /* Create and initialize options */
  18. options = oss_request_options_create(p);
  19. 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, 1);
  24. /* Download the object to the buffer */
  25. aos_list_init(&buffer);
  26. s = oss_get_object_to_buffer(options, &bucket, &object, headers, &buffer, &resp_headers);
  27. /* Identify whether the request succeeds */
  28. if (aos_status_is_ok(s)) {
  29. printf("get file succeeded\n");
  30. } else {
  31. printf("get file failed\n");
  32. }
  33. /* Convert the aos_list_t in the buffer to char* and calculate the total length of the object read */
  34. len = aos_buf_list_len(&buffer);
  35. buf = aos_pcalloc(p, len + 1);
  36. buf[len] = '\0';
  37. aos_list_for_each_entry(content, &buffer, node) {
  38. size = aos_buf_size(content);
  39. memcpy(buf + pos, content->pos, size);
  40. pos += size;
  41. }
  42. /* Release the resources */
  43. aos_pool_destroy(p);

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

Thank you! We've received your feedback.