Quick start

Last Updated: Nov 02, 2017

This document describes 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 initializes 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. }

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 must initialized. 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. /* Recreate 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. This means you do not 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 time-out 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 actually releases the memory allocated to various parts used during the request process */
  21. aos_pool_destroy(p);

Note:

  • For more information about bucket naming conventions, see Basic OSS concepts.

  • The bucket name cannot be the same as the existing bucket names of other users in OSS. To create a bucket successfully, you must 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 also returns aos_status_t* values if not 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 information, see Upload objects.

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, see Manage objects.

Step 6. Download a specified object

See the following code to download a specified 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. 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 information, see Download objects.

Thank you! We've received your feedback.