Download objects

Last Updated: Sep 08, 2017

OSS C SDK provides a variety of object downloading interfaces. You can download an object from OSS through any of the following methods:

  • Download an object to the memory
  • Download an object to a local file
  • Multipart download

Download an object to the memory

You can download an object to the memory using the oss_get_object_to_buffer interface:

  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 *params;
  6. aos_table_t *resp_headers;
  7. char *bucket_name = "<Name of your bucket>";
  8. char *object_name = "<Name of your object>";
  9. aos_string_t bucket;
  10. aos_string_t object;
  11. aos_list_t buffer;
  12. aos_buf_t *content;
  13. char *buf;
  14. int64_t len = 0;
  15. int64_t size = 0;
  16. int64_t pos = 0;
  17. aos_pool_create(&p, NULL);
  18. /* Create and initialize options */
  19. options = oss_request_options_create(p);
  20. init_options(options);
  21. /* Initialize parameters */
  22. aos_str_set(&object, object_name);
  23. aos_str_set(&bucket, bucket_name);
  24. headers = aos_table_make(p, 0);
  25. params = aos_table_make(p, 0);
  26. /* Download objects */
  27. aos_list_init(&buffer);
  28. s = oss_get_object_to_buffer(options, &bucket, &object, &buffer, headers, params, &resp_headers);
  29. if (aos_status_is_ok(s)) {
  30. printf("get object succeeded\n");
  31. /* Copy the downloaded content to the buffer*/
  32. len = aos_buf_list_len(&buffer);
  33. buf = aos_pcalloc(p, len + 1);
  34. buf[len] = '\0';
  35. aos_list_for_each_entry(content, &buffer, node) {
  36. size = aos_buf_size(content);
  37. memcpy(buf + pos, content->pos, size);
  38. pos += size;
  39. }
  40. } else {
  41. printf("get object failed\n");
  42. }
  43. aos_pool_destroy(p);

Notice:

  • Compared with Version 1.0.0, Version 2.0.0 adds the params parameter for the oss_get_object_to_buffer interface, and allows the headers and params parameters to be NULL, which is not supported in Version 1.0.0 and earlier versions.
  • The params parameter is also added for the oss_get_object_to_buffer_by_url and oss_get_object_to_file_by_url parameters.
  • Complete code can be found at GitHub.

Download an object to a local file

You can use the oss_get_object_to_file interface to download the object to a specified file.

  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 *params;
  6. aos_table_t *resp_headers;
  7. char *bucket_name = "<Name of your bucket>";
  8. char *object_name = "<Name of your object>";
  9. char *filepath = "<Path of the local file>";
  10. aos_string_t bucket;
  11. aos_string_t object;
  12. aos_string_t file;
  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(&bucket, bucket_name);
  19. aos_str_set(&object, object_name);
  20. aos_str_set(&file, filepath);
  21. headers = aos_table_make(p, 0);
  22. params = aos_table_make(p, 0);
  23. /* Download objects */
  24. s = oss_get_object_to_file(options, &bucket, &object, &file, headers, params, &resp_headers);
  25. if (aos_status_is_ok(s)) {
  26. printf("get object succeeded\n");
  27. } else {
  28. printf("get object failed\n");
  29. }
  30. aos_pool_destroy(p);

Notice:

  • Compared with Version 1.0.0, Version 2.0.0 adds the params parameter for the oss_get_object_to_file interface, and allows the headers and params parameters to be NULL, which is not supported in Version 1.0.0 and earlier versions.
  • If a local file with the name filepath already exists, the local file will be overwritten.
  • Complete code can be found at GitHub.

Multipart download

You can set the Range parameter to specify the transmission range of the returned object to download the object in the multipart mode.The following code downloads an object to the memory in the multipart mode:

  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 *params;
  6. aos_table_t *resp_headers;
  7. char *bucket_name = "<Name of your bucket>";
  8. char *object_name = "<Name of your object>";
  9. aos_string_t bucket;
  10. aos_string_t object;
  11. aos_list_t buffer;
  12. aos_pool_create(&p, NULL);
  13. /* Create and initialize options */
  14. options = oss_request_options_create(p);
  15. init_options(options);
  16. /* Initialize parameters */
  17. aos_str_set(&bucket, bucket_name);
  18. aos_str_set(&object, object_name);
  19. params = NULL;
  20. headers = aos_table_make(p, 1);
  21. /* Set the Range, the specified range for reading the object. A range of "bytes=20-100" covers the 20th and the 100th characters */
  22. apr_table_set(headers, "Range", "bytes=20-100");
  23. aos_list_init(&buffer);
  24. /* Download objects in multiple parts */
  25. s = oss_get_object_to_buffer(options, &bucket, &object, headers, params, &buffer, &resp_headers);
  26. if (aos_status_is_ok(s)) {
  27. printf("get object succeeded\n");
  28. } else {
  29. printf("get object failed\n");
  30. }
  31. aos_pool_destroy(p);

Resumable download

When the network is unstable or other exceptions occur as a large object is being downloaded, the whole download operation will fail. You have to re-download the objects, wasting resources. When the network is unstable, you may need to try multiple times. Resumable download supports concurrent downloads and resuming downloading from interruptions. Resumable download controls downloading resumption behavior through oss_resumable_clt_params_t. It has the following parameters:

  • part_size: The size of each part to be downloaded. The size ranges from 1 B to 5 GB. Unit: Byte.
  • thread_num: The number of concurrent threads. The default value is 1.
  • enable_checkpoint: Whether to enable resumable downloads. This option is disabled by default.
  • checkpoint_path: The path of the checkpoint object. It is by default stored under the upload object directory {upload_file_path}.cp.

The principle of resumable download is to divide the object to be downloaded into multiple parts and download them separately. When all the parts are downloaded, the download of the entire object will be completed. The progress of the current download will be recorded during the downloading process (in the checkpoint object). If the download of any part fails during the process, the next download attempt will start from the recorded position in the checkpoint object. This requires that the same checkpoint object with the previous download be used in the next call. When the download is complete, the checkpoint object will be deleted.

  1. void resumable_download_with_resumable()
  2. {
  3. aos_pool_t *p = NULL;
  4. aos_string_t bucket;
  5. aos_string_t object;
  6. aos_string_t filename;
  7. aos_status_t *s = NULL;
  8. int is_cname = 0;
  9. aos_table_t *headers = NULL;
  10. aos_table_t *resp_headers = NULL;
  11. oss_request_options_t *options = NULL;
  12. oss_resumable_clt_params_t *clt_params;
  13. aos_pool_create(&p, NULL);
  14. options = oss_request_options_create(p);
  15. init_sample_request_options(options, is_cname);
  16. headers = aos_table_make(p, 0);
  17. aos_str_set(&bucket, BUCKET_NAME);
  18. aos_str_set(&object, "my_key_2.zip");
  19. aos_str_set(&filename, "local_big_file_2.zip");
  20. // download
  21. clt_params = oss_create_resumable_clt_params_content(p, 1024 * 100, 3, AOS_TRUE, NULL);
  22. s = oss_resumable_download_file(options, &bucket, &object, &filename, headers, NULL,
  23. clt_params, NULL, &resp_headers);
  24. if (aos_status_is_ok(s)) {
  25. printf("download succeeded\n");
  26. } else {
  27. printf("download failed\n");
  28. }
  29. aos_pool_destroy(p);
  30. }

Notice:

  • Resumable download supports the progress bar feature.
  • Complete code can be found at GitHub.

Progress bar

The OSS C SDK supports the progress bar feature to indicate the uploading/downloading progress. The following code uses GetObject as an example to demonstrate the usage of the progress bar feature.

  1. void percentage(int64_t consumed_bytes, int64_t total_bytes)
  2. {
  3. assert(total_bytes >= consumed_bytes);
  4. printf("%%%" APR_INT64_T_FMT "\n", consumed_bytes * 100 / total_bytes);
  5. }
  6. void put_and_get_from_file_with_progress()
  7. {
  8. aos_pool_t *p = NULL;
  9. aos_status_t *s = NULL;
  10. int is_cname = 0;
  11. aos_string_t bucket;
  12. aos_string_t object;
  13. aos_string_t filename;
  14. oss_request_options_t *options = NULL;
  15. aos_table_t *resp_headers = NULL;
  16. aos_list_t resp_body;
  17. char *download_filename = "get_object_to_local_file.txt";
  18. /* init test*/
  19. aos_pool_create(&p, NULL);
  20. options = oss_request_options_create(p);
  21. init_sample_request_options(options, is_cname);
  22. aos_str_set(&bucket, BUCKET_NAME);
  23. aos_str_set(&object, OBJECT_NAME);
  24. aos_str_set(&filename, __FILE__);
  25. aos_list_init(&resp_body);
  26. /* put object */
  27. s = oss_do_put_object_from_file(options, &bucket, &object, &filename, NULL, NULL, percentage, &resp_headers, &resp_body);
  28. if (aos_status_is_ok(s)) {
  29. printf("put object from file succeeded\n");
  30. } else {
  31. printf("put object from file failed\n");
  32. aos_pool_destroy(p);
  33. return;
  34. }
  35. aos_pool_destroy(p);
  36. /* get object */
  37. aos_pool_create(&p, NULL);
  38. options = oss_request_options_create(p);
  39. init_sample_request_options(options, is_cname);
  40. aos_str_set(&filename, download_filename);
  41. s = oss_do_get_object_to_file(options, &bucket, &object, NULL, NULL, &filename, percentage, NULL);
  42. if (aos_status_is_ok(s)) {
  43. printf("get object to file succeeded\n");
  44. } else {
  45. printf("get object to file failed\n");
  46. }
  47. aos_pool_destroy(p);
  48. }

Notice: The oss_do_get_object_to_buffer and oss_do_put_object_from_file support the progress bar feature. For code details, see GitHub.

Thank you! We've received your feedback.