edit-icon download-icon

Client operations

Last Updated: Nov 21, 2017

OSS MEDIA C SDK is divided into three parts: the client, the server, and the HLS. We mainly cover operations related to the client. For other operations, see the following documents:

Interface

Operation interfaces related to the client are all placed in oss_media_file.h. The following interfaces are currently provided:

  • oss_media_file_open
  • oss_media_file_stat
  • oss_media_file_tell
  • oss_media_file_seek
  • oss_media_file_read
  • oss_media_file_write
  • oss_media_file_close

Next, the functions and use notes for various interfaces are provided in detail.

Basic structs

  1. /**
  2. * Metadata of the OSS MEDIA FILE, including file length, location, and type
  3. */
  4. typedef struct {
  5. int64_t length;
  6. int64_t pos;
  7. char *type;
  8. } oss_media_file_stat_t;
  9. /**
  10. * Attributes of the OSS MEDIA FILE
  11. */
  12. typedef struct oss_media_file_s {
  13. void *ipc;
  14. char *endpoint;
  15. int8_t is_cname;
  16. char *bucket_name;
  17. char *object_key;
  18. char *access_key_id;
  19. char *access_key_secret;
  20. char *token;
  21. char *mode;
  22. oss_media_file_stat_t _stat;
  23. time_t expiration;
  24. auth_fn_t auth_func;
  25. } oss_media_file_t;
  • type: The file type: normal or appendable.

  • ipc: Set the unique identifier of the device. This attribute can be used in auth func as per requirement, and ignored if it is not used.

  • endpoint: Such as oss-cn-hangzhou.aliyuncs.com.

  • is_cname: Whether CNAME has been enabled.

  • bucket_name: Name of the OSS bucket.

  • object_key: Name of the OSS object.

  • access_key_id: The AccessKey ID provided by Alibaba Cloud for access control. Here two modes are available: 1. The AccessKey ID of the master account or the subaccount. In this case, the token that follows must be set to NULL. 2. The temporary AccessKey ID obtained through get_token.

  • access_key_secret: The AccessKey Secret provided by Alibaba Cloud for access control. The two available modes are: 1. The permanent AccessKey Secret of the master account or the subaccount. In this case, the token that follows must be set to NULL. 2. The temporary AccessKey Secret obtained through get_token. The access_key_id and access_key_secret must use the same mode at the same time.

  • token: If the permanent AccessKey ID and AccessKey Secret of the master account or the subaccount are used at the same time, this attribute must be set to NULL. If you use a terminal device to upload or download resources, the app server needs to grant the temporary access permission to the terminal device. You can get the temporary access_key_id, access_key_secret and token through the get_token on the server. If you set token to a non-NULL value, the system expects you to use a temporary AccessKey ID, a temporary AccessKey Secret and a temporary token. If you do not want to use a temporary token, please set this attribute to NULL.

  • expiration: The time when the authorization fails. After the first authorization, the next authorization is performed only after the expiration time has passed.

  • auth: The authorization function. You must implement a function and grant values to the host, bucket, and token values within the function.

  • mode: The read-write mode.

Initialization

  1. /**
  2. * @brief Initialize the OSS media
  3. * @note This interface must be called first when the program starts to initialize the OSS MEDIA C SDK.
  4. * @return:
  5. * If 0 is returned, it indicates the operation was successful.
  6. * Otherwise, it indicates an error has occured. Possible causes include: insufficient memory, or the APR or CURL versions are too low.
  7. */
  8. int oss_media_init(aos_log_level_e log_level);

Note:For complete code, see GitHub.

Destroy

  1. /**
  2. * @brief Destroy the OSS meida
  3. * @note This interface must be called last when the program ends to destroy the OSS MEDIA C SDK.
  4. */
  5. void oss_media_destroy();

Note: For complete code, see GitHub.

Open an object

  1. /**
  2. * @brief Open an OSS object
  3. * @param[in] Name of the bucket that stores objects in bucket_name oss
  4. * @param[in] Name of the object in object_key oss
  5. * @param[in] mode:
  6. * 'r': Read mode
  7. * 'w': Overwrite mode
  8. * 'a': Append write mode
  9. * notes: Not allowed to be used in combination
  10. * @param[in] auth_func The authorization function to set access_key_id/access_key_secret
  11. * @return:
  12. * If NULL is returned, it indicates success. Otherwise, it indicates failure.
  13. */
  14. oss_media_file_t* oss_media_file_open(char *bucket_name,
  15. char *object_key,
  16. char *mode,
  17. auth_fn_t auth_func);
  • mode: Read-only, overwrite, and append write modes are supported. Combination mode is not supported.
  • Read mode: Once you open the object, part of the object content is read-only once. Multiple reads are generally required to read the full content.

  • Overwrite mode: After you open the object, the object content is written at a time, in full. Multiple writes are supported, but the latest content overwrites the earlier content.

  • Append write: After the object is opened, you can write content to the object in the append mode multiple times.

Note: For complete code, see GitHub.

Closes an object

  1. /**
  2. * @brief Close the OSS object
  3. */
  4. void oss_media_file_close(oss_media_file_t *file);

Note: For complete code, see GitHub.

Write an object

  1. /**
  2. * @brief Write an object to the OSS
  3. * @return:
  4. * If the request is successful, the size of the written data is returned. If "-1" is returned, it indicates the data write failed
  5. */
  6. int64_t oss_media_file_write(oss_media_file_t *file, const void *buf, int64_t nbyte);

Example project:

  1. /* Authorization function */
  2. static void auth_func(oss_media_file_t *file) {
  3. file->endpoint = "your endpoint";
  4. file->is_cname = 0;
  5. file->access_key_id = "AccessKey ID or temporary AccessKey ID provided by Alibaba Cloud";
  6. file->access_key_secret = "AccessKey Secret or temporary AccessKey Secret provided by Alibaba Cloud";
  7. file->token = "Get the temporary token through the get_token interface";
  8. /* Effective time of this authorization */
  9. file->expiration = time(NULL) + 300;
  10. }
  11. static void write_file() {
  12. oss_clean(g_filename);
  13. int64_t write_size;
  14. oss_media_file_t *file;
  15. char *bucket_name = "<your bucket name>";
  16. char *key = "<your object key>";
  17. char *content = "aliyun oss media c sdk";
  18. /* Open an object */
  19. file = oss_media_file_open(bucket_name, key, "w", auth_func);
  20. if (!file) {
  21. printf("open media file failed\n");
  22. return;
  23. }
  24. /* Write an object */
  25. write_size = oss_media_file_write(file, content, strlen(content));
  26. if (-1 != write_size) {
  27. printf("write %" PRId64 " bytes succeeded\n", write_size);
  28. } else {
  29. oss_media_file_close(file);
  30. printf("write failed\n");
  31. return;
  32. }
  33. /* Close the object and release the resource */
  34. oss_media_file_close(file);
  35. }

Note:

  • In the example, the overwrite ("w") mode is used to open an object. If multiple writes are performed, the later write overwrites the previous write. If you want to activate append write, specify the append write ("a") mode for opening the object.

  • For complete code, see GitHub.

Read an object

  1. /**
  2. * @brief Read the data of a fixed number of nbytes
  3. * @note The size of buf must be greater than or equal to nbyte + 1
  4. * @return:
  5. * If 0 is returned, it indicates the operation is successful.
  6. * Otherwise, if "-1" is returned, it indicates an error may have occurred. Possible causes of the failure include: the object was not opened in the "read-only" mode, the object cannot connect to the OSS, or the object has no permission to read the OSS.
  7. */
  8. int64_t oss_media_file_read(oss_media_file_t *file, void *buf, int64_t nbyte);

Example project:

  1. int ntotal, nread, nbuf = 16;
  2. char buf[nbuf];
  3. char *content;
  4. char *bucket_name = "<your bucket name>";
  5. char *key = "<your object key>";
  6. oss_media_file_t *file;
  7. /* Open the object */
  8. file = oss_media_file_open(bucket_name, key, "r", auth_func);
  9. if (!file) {
  10. printf("open media file failed\n");
  11. return;
  12. }
  13. /* Read the object */
  14. content = malloc(stat.length + 1);
  15. ntotal = 0;
  16. while ((nread = oss_media_file_read(file, buf, nbuf)) > 0) {
  17. memcpy(content + ntotal, buf, nread);
  18. ntotal += nread;
  19. }
  20. content[ntotal] = '\0';
  21. /* Close the object */
  22. oss_media_file_close(file);
  23. free(content);
  24. printf("oss media c sdk read object succeeded\n");
  25. }

Note: For complete code, see GitHub.

Manage objects

OSS MEDIA FILE also supports tell, seek, and stat operations.

  1. /**
  2. * @brief Get the location of the OSS MEDIA FILE
  3. * @return:
  4. * If 0 is returned, it indicates the operation is successful.
  5. * Otherwise, if "-1" is returned, it indicates an error may have occurred. Possible causes of the failure include: the object was not opened in the "read-only" mode, the object cannot connect to the OSS, or the object has no permission to read the OSS.
  6. */
  7. int64_t oss_media_file_tell(oss_media_file_t *file);
  8. /**
  9. * @brief Set the OSS MEDIA FILE pointer to the specified location
  10. * @return:
  11. * If 0 is returned, it indicates the operation is successful.
  12. * Otherwise, if "-1" is returned, it indicates an error may have occurred. Possible causes of the failure include: the object was not opened in the "read-only" mode, the object cannot connect to the OSS, or the object has no permission to read the OSS.
  13. */
  14. int64_t oss_media_file_seek(oss_media_file_t *file, int64_t offset);
  15. /**
  16. * @brief Get the metadata of the OSS MEDIA FILE
  17. * @return:
  18. * If 0 is returned, it indicates the operation is successful.
  19. * Otherwise, if "-1" is returned, it indicates an error may have occurred. Possible causes of the failure include: the object cannot connect to the OSS, or the object has no permission to read the OSS.
  20. */
  21. int oss_media_file_stat(oss_media_file_t *file, oss_media_file_stat_t *stat);

Example project:

  1. static void seek_tell_stat_file() {
  2. int ntotal, nread, nbuf = 16;
  3. char buf[nbuf];
  4. char *bucket_name = "<your bucket name>";
  5. char *key = "<your object key>";
  6. oss_media_file_t *file;
  7. /* Open the object */
  8. file = oss_media_file_open(bucket_name, key, "r", auth_func);
  9. if (!file) {
  10. printf("open media file failed\n");
  11. return;
  12. }
  13. /* Get the meta information of the object */
  14. oss_media_file_stat_t stat;
  15. if (0 != oss_media_file_stat(file, &stat)) {
  16. oss_media_file_close(file);
  17. oss_media_file_free(file);
  18. printf("stat media file[%s] failed\n", file->object_key);
  19. return;
  20. }
  21. printf("file [name=%s, length=%ld, type=%s]",
  22. file->object_key, stat.length, stat.type);
  23. /* tell */
  24. printf("file [position=%" PRId64 "]", oss_media_file_tell(file));
  25. /* seek */
  26. oss_media_file_seek(file, stat.length / 2);
  27. /* Close the object */
  28. oss_media_file_close(file);
  29. printf("oss media c sdk seek object succeeded\n");
  30. }

Note: For complete code, see GitHub.

Thank you! We've received your feedback.