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 with 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

/**
 * Metadata of the OSS MEDIA FILE, including file length, location, and type
 */
typedef struct {
    int64_t length;
    int64_t pos;
    char    *type;
} oss_media_file_stat_t;


/**
 * Attributes of the OSS MEDIA FILE
 */
typedef struct oss_media_file_s {
    void   *ipc;
    char   *endpoint;
    int8_t is_cname; 
    char   *bucket_name;  
    char   *object_key;
    char   *access_key_id;
    char   *access_key_secret;
    char   *token;
    char   *mode;
    oss_media_file_stat_t _stat;

    time_t expiration;
    auth_fn_t auth_func;
} oss_media_file_t;
Note
  • 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

/**
 *  @brief  Initialize the OSS media
 *  @note   This interface should be called first when the program starts to initialize the OSS MEDIA C SDK.
 *  @return:
 *      If 0 is returned, it indicates the operation was successful.
 *      Otherwise, it indicates an error has occured. Possible causes include: insufficient memory, or the APR or CURL versions are too low.
 */
int oss_media_init(aos_log_level_e log_level);
Note For the complete code, see GitHub.

Destruction

/**
 *  @brief  Destroy the OSS meida
 *  @note   This interface should be called at last when the program ends to destroy the OSS MEDIA C SDK.
 */
void oss_media_destroy();
Note For the complete code, see GitHub.

Open an object

/**
 *  @brief  Open an OSS object
 *  @param[in]  Name of the bucket that stores objects in bucket_name oss
 *  @param[in]  Name of the object in object_key  oss
 *  @param[in]  mode:
 *      'r': Read mode
 *      'w': Overwrite mode
 *      'a': Append write mode
 *      notes: Not allowed to be used in combination
 *  @param[in]  auth_func    The authorization function to set access_key_id/access_key_secret
 *  @return:
 *      If NULL is returned, it indicates success. Otherwise, it indicates failure.
 */
oss_media_file_t* oss_media_file_open(char *bucket_name,
                                      char *object_key,
                                      char *mode,
                                      auth_fn_t auth_func);
Note
  • 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.
  • For the complete code, see GitHub.

Close an object

/**
 *  @brief  Close the OSS object
 */
void oss_media_file_close(oss_media_file_t *file);
Note For the complete code, see GitHub.

Write an object

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

Example project:

/* Authorization function */
static void auth_func(oss_media_file_t *file) {
    file->endpoint = "your endpoint";
    file->is_cname = 0;
    file->access_key_id = "Access key ID or temporary access key ID provided by Alibaba Cloud";
    file->access_key_secret = "Access key secret or temporary access key secret provided by Alibaba Cloud";
    file->token = "Get the temporary token through the get_token interface";

    /* Effective time of this authorization */
    file->expiration = time(NULL) + 300;
}

static void write_file() {
    oss_clean(g_filename);

    int64_t write_size;
    oss_media_file_t *file;
    char *bucket_name = "<your bucket name>";
    char *key = "<your object key>";
    char *content = "aliyun oss media c sdk";

    /* Open an object */
    file = oss_media_file_open(bucket_name, key, "w", auth_func);
    if (! file) {
        printf("open media file failed\n");
        return;
    }

    /* Write an object */
    write_size = oss_media_file_write(file, content, strlen(content));
    if (-1 ! = write_size) {
         printf("write %" PRId64 " bytes succeeded\n", write_size);
    } else {
        oss_media_file_close(file);
        printf("write failed\n");
        return;
    }

    /* Close the object and release the resource */
    oss_media_file_close(file);
}
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 the complete code, see GitHub.

Read an object

/**
 *  @brief  Read the data of a fixed number of nbytes.
 *  @note   The size of buf should be greater than or equal to nbyte + 1.
 *  @return:
 *      If 0 is returned, it indicates the operation is successful.
 *      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.
 */
int64_t oss_media_file_read(oss_media_file_t *file, void *buf, int64_t nbyte);

Example project:

    int ntotal, nread, nbuf = 16;
    char buf[nbuf];
    char *content;
    char *bucket_name = "<your bucket name>";
    char *key = "<your object key>";

    oss_media_file_t *file;

    /* Open the object */
    file = oss_media_file_open(bucket_name, key, "r", auth_func);
    if (! file) {
        printf("open media file failed\n");
        return;
    }

    /* Read the object */
    content = malloc(stat.length + 1);
    ntotal = 0;
    while ((nread = oss_media_file_read(file, buf, nbuf)) > 0) {
        memcpy(content + ntotal, buf, nread);
        ntotal += nread;
    }
    content[ntotal] = '\0';

    /* Close the object */
    oss_media_file_close(file);
    free(content);

    printf("oss media c sdk read object succeeded\n");
}
Note For the complete code, see GitHub.

Manage objects

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

/**
 *  @brief  Get the location of the OSS MEDIA FILE
 *  @return:
 *      If 0 is returned, it indicates the operation is successful.
 *      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.
 */
int64_t oss_media_file_tell(oss_media_file_t *file);

/**
 *  @brief  Set the OSS MEDIA FILE pointer to the specified location.
 *  @return:
 *      If 0 is returned, it indicates the operation is successful.
 *      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.
 */
int64_t oss_media_file_seek(oss_media_file_t *file, int64_t offset);

/**
 *  @brief Get the metadata of the OSS MEDIA FILE.
 *  @return:
 *      If 0 is returned, it indicates the operation is successful.
 *      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.
 */
int oss_media_file_stat(oss_media_file_t *file, oss_media_file_stat_t *stat);

Example project:

static void seek_tell_stat_file() {
    int ntotal, nread, nbuf = 16;
    char buf[nbuf];
    char *bucket_name = "<your bucket name>";
    char *key = "<your object key>";

    oss_media_file_t *file;

    /* Open the object */
    file = oss_media_file_open(bucket_name, key, "r", auth_func);
    if (! file) {
        printf("open media file failed\n");
        return;
    }

    /* Get the meta information of the object */
    oss_media_file_stat_t stat;
    if (0 ! = oss_media_file_stat(file, &stat)) {
        oss_media_file_close(file);
        oss_media_file_free(file);

        printf("stat media file[%s] failed\n", file->object_key);
        return;
    }

    printf("file [name=%s, length=%ld, type=%s]", 
           file->object_key, stat.length, stat.type);

    /* tell */
    printf("file [position=%" PRId64 "]", oss_media_file_tell(file));

    /* seek */
    oss_media_file_seek(file, stat.length / 2);

    /* Close the object */
    oss_media_file_close(file);

    printf("oss media c sdk seek object succeeded\n");
}
Note For the complete code, see GitHub.