OSS MEDIA C SDK has three parts: the client, the server, and the HLS. Next we introduce the operations related to the server. For other operations, see the following chapters.

Interface

Operation interfaces related to the server are all placed in oss_media.h. Currently the following interfaces are provided:

  • oss_media_create_bucket
  • oss_media_delete_bucket
  • oss_media_create_bucket_lifecycle
  • oss_media_get_bucket_lifecycle
  • oss_media_delete_bucket_lifecycle
  • oss_media_delete_file
  • oss_media_list_files
  • oss_media_get_token
  • oss_media_get_token_from_policy

The Functions and notes of usage of various interfaces are as follows:

Basic structs

typedef struct oss_media_config_s {
    char *endpoint;
    int is_cname;
    char *access_key_id;
    char *access_key_secret;
    char *role_arn;
} oss_media_config_t;

typedef struct oss_media_files_s {
    char *path;
    char *marker;
    int  max_size;

    char *next_marker;
    int  size;
    char **file_names;
} oss_media_files_t;

Note
  • endpoint: For example, oss-cn-hangzhou.aliyuncs.com.
  • is_cname: Whether CNAME has been enabled.
  • access_key_id: The AccessKey ID for access control provided by Alibaba Cloud.
  • access_key_secret: The AccessKey Secret for access control provided by Alibaba Cloud.
  • role_arn: The ARN of the role created in Alibaba Cloud RAM. The value is available in RAM console > Manage Roles > click the name of a role > Basic Information > ARN. The value format is similar to: acs:ram::xxxxxx:role/yyyy. If no role is available, you must create a new role and grant the AliyunOSSFullAccess and AliyunSTSAssumeRoleAccess permissions to the role.
  • marker: Set the returned results to begin from the first entry after the Marker in alphabetical order.
  • max_size: Set the maximum number returned. The value cannot exceed 1,000.
  • next_marker: The start position of the next execution.

Initialization

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

Destruction

/**
 *  @brief  Destroy the OSS meida
 *  @note   This interface must 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.

Create a bucket

/**
 *  @brief  Create a new bucket
 *  @paramp[in] oss_media_acl_t
 *     OSS_ACL_PUBLIC_READ     Public read and private write
 *     OSS_ACL_PUBLIC_READ	 Public read and private write
 *     OSS_ACL_PUBLIC_READ_WRITE Public read-write
 * @ Return:
 *      If 0 is returned, it indicates the operation is successful.
 *      Otherwise, if "-1" is returned, it indicates an error may occur. Possible causes of the failure include: the object cannot connect to the OSS, or the object has no permission.
 */
int oss_media_create_bucket(oss_media_config_t *config, const char *bucket_name, oss_media_acl_t acl);

Example project:

static void init_media_config(oss_media_config_t *config) {
    config->endpoint = "your endpoint";
    config->access_key_id = "The access key ID provided by Alibaba Cloud";
    config->access_key_secret = "The access key secret provided by Alibaba Cloud";
    config->role_arn = "The role ARN provided by Alibaba Cloud RAM"; 
    config->is_cname = 0;
}

void create_bucket() {
    int ret;
    char *bucket_name;
    oss_media_config_t config;

    /* Initialize the variable */    
    bucket_name = "<your bucket name>";
    init_media_config(&config);

    /* Create the bucket */
    ret = oss_media_create_bucket(&config, bucket_name, OSS_ACL_PRIVATE);
    
    if (0 == ret) {
        printf("create bucket[%s] succeeded.\n", bucket_name);
    } else {
        printf("create bucket[%s] failed.\n", bucket_name);
    }
}

Note For the complete code, see GitHub.

Delete a bucket

/*
 *  @brief  Delete the bucket
 * @return
 *      If 0 is returned, it indicates the operation is successful.
 *      Otherwise, if "-1" is returned, it indicates an error may occur. Possible causes of the failure include: the object cannot connect to the OSS, or the object has no permission.
 */
int oss_media_delete_bucket(oss_media_config_t *config, const char *bucket_name);

Example project:

void delete_bucket() {
    int ret;
    char *bucket_name;
    oss_media_config_t config;
    
    /* Initialize the variable */
    bucket_name = "<your bucket name>";
    init_media_config(&config);

    /* Delete the bucket */
    ret = oss_media_delete_bucket(&config, bucket_name);

    if (0 == ret) {
        printf("delete bucket[%s] succeeded.\n", bucket_name);
    } else {
        printf("delete bucket[%s] failed.\n", bucket_name);
    }    
}
Note For the complete code, see GitHub.

Create lifecycle rules for a bucket

/**
 *  @brief  Create lifecycle rules for the bucket.
 *  @note   These rules can control the time for automatically deleting objects.
 * @return
 *      If 0 is returned, it indicates the operation is successful.
 *      Otherwise, if "-1" is returned, it indicates an error may occur. Possible causes of the failure include: the object cannot connect to the OSS, or the object has no permission.
 */
int oss_media_create_bucket_lifecycle(oss_media_config_t *config, const char *bucket_name, oss_media_lifecycle_rules_t *rules);

Example project:

void create_bucket_lifecycle() {
    int ret;
    char *bucket_name;
    oss_media_lifecycle_rules_t *rules;
    oss_media_config_t config;
    
    /* Initialize the variable */
    bucket_name = "<your bucket name>";
    init_media_config(&config);

    /* Create lifecycle rules */
    rules = oss_media_create_lifecycle_rules(2);
    oss_media_lifecycle_rule_t rule1;
    rule1.name = "example-1";
    rule1.path = "/example/1";
    rule1.status = "Enabled";
    rule1.days = 1;
    oss_media_lifecycle_rule_t rule2;
    rule2.name = "example-2";
    rule2.path = "/example/2";
    rule2.status = "Disabled";
    rule2.days = 2;

    rules->rules[0] = &rule1;
    rules->rules[1] = &rule2;

    /* Set lifecycle rules of the bucket */
    ret = oss_media_create_bucket_lifecycle(&config, 
            bucket_name, rules);

    if (0 == ret) {
        printf("create bucket[%s] lifecycle succeeded.\n", bucket_name);
    } else {
        printf("create bucket[%s] lifecycle failed.\n", bucket_name);
    }

    /* Release the resources. */
    oss_media_free_lifecycle_rules(rules);
}
Note Example code can be found at GitHub.

Get lifecycle rules for the bucket

/**
 *  @brief  Get lifecycle rules for the bucket
 * @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.
 */
int oss_media_get_bucket_lifecycle(oss_media_config_t *config, const char *bucket_name, oss_media_lifecycle_rules_t *rules);

Example project:

void get_bucket_lifecycle() {
    int ret, i;
    char *bucket_name;
    oss_media_lifecycle_rules_t *rules;
    oss_media_config_t config;
    
    /* Initialize the variable */
    bucket_name = "<your bucket name>";
    init_media_config(&config);

    /* Get lifecycle rules */
    rules = oss_media_create_lifecycle_rules(0);
    ret = oss_media_get_bucket_lifecycle(&config, bucket_name, rules);

    if (0 == ret) {
        printf("get bucket[%s] lifecycle succeeded.\n", bucket_name);
    } else {
        printf("get bucket[%s] lifecycle failed.\n", bucket_name);
    }

    for (i = 0; i < rules->size; i++) {
        printf(">>>> rule: [name:%s, path:%s, status=%s, days=%d]\n",
               rules->rules[i]->name, rules->rules[i]->path, 
               rules->rules[i]->status, rules->rules[i]->days);
    }

    /* Release the resources. */
    oss_media_free_lifecycle_rules(rules);
}
Note For the complete code, see GitHub.

Delete lifecycle rules for a bucket

/**
 *  @brief  Delete the bucket lifecycle rules
 *  @return:
 *      If 0 is returned, it indicates the operation is successful.
 *      Otherwise, if "-1" is returned, it indicates an error may occur. Possible causes of the failure include: the object cannot connect to the OSS, or the object has no permission.
 */
int oss_media_delete_bucket_lifecycle(oss_media_config_t *config, const char *bucket_name);

Example project:

void delete_bucket_lifecycle() 
{
    int ret;
    char *bucket_name;
    oss_media_config_t config;
    
    /* Initialize the variable */
    bucket_name = "<your bucket name>";
    init_media_config(&config);

    /* Delete lifecycle rules */
    ret = oss_media_delete_bucket_lifecycle(&config, bucket_name);

    if (0 == ret) {
        printf("delete bucket[%s] lifecycle succeeded.\n", bucket_name);
    } else {
        printf("delete bucket[%s] lifecycle failed.\n", bucket_name);
    }
}
Note For the complete code, see GitHub.

Delete an object

/**
 *  @brief  Delete a specific object in the bucket
 *  @return:
 *      If 0 is returned, it indicates the operation is successful.
 *      Otherwise, if "-1" is returned, it indicates an error may occur. Possible causes of the failure include: the object cannot connect to the OSS, or the object has no permission.
 */
int oss_media_delete_file(oss_media_config_t *config, const char *bucket_name, const char *key);

Example project:

void delete_file() {
    int ret;
    oss_media_config_t config;
    char *file;
    char *bucket_name;

    /* Initialize the variable */
    file = "oss_media_file";
    bucket_name = "<your bucket name>";
    init_media_config(&config);

    /* Delete an object */
    ret = oss_media_delete_file(&config, bucket_name, file);

    if (0 == ret) {
        printf("delete file[%s] succeeded.\n", file);
    } else {
        printf("delete file[%s] lifecycle failed.\n", file);
    }
}
Note For the complete code, see GitHub.

List objects

/**
 *  @brief  List objects in a specific bucket
 *  @return:
 *      If 0 is returned, it indicates the operation is successful.
 *      Otherwise, if "-1" is returned, it indicates an error may occur. Possible causes of the failure include: the object cannot connect to the OSS, or the object has no permission.
 */
int oss_media_list_files(oss_media_config_t *config, const char *bucket_name, oss_media_files_t *files);

Example project:

void list_files() {
    int ret, i;
    char *bucket_name;
    oss_media_files_t *files;
    oss_media_config_t config;
    
    /* Initialize the variable */
    bucket_name = "<your bucket name>>";
    init_media_config(&config);

    files = oss_media_create_files();
    files->max_size = 50;

    /* List objects */
    ret = oss_media_list_files(&config, bucket_name, files);

    if (0 == ret) {
        printf("list files succeeded.\n");
    } else {
        printf("list files lifecycle failed.\n");
    }

    for (i = 0; i < files->size; i++) {
        printf(">>>>file name: %s\n", files->file_names[i]);
    }

    /* Release the resources */
    oss_media_free_files(files);
}
Note For the complete code, see GitHub.

Get the temporary token

/*
 *  @brief  Get the temporary token
 *  @param[in]:
      mode:
 *      'r': Read mode
 *      'w': Overwrite mode
 *      'a': Append write mode
 *    expiration: The valid period of the temporary token. The value ranges from 15 minutes to one hour. The unit is seconds.
 *  @return:
 *      If 0 is returned, it indicates the operation is successful.
 *      Otherwise, if "-1" is returned, it indicates an error may occur. Possible causes of the failure include: the object cannot connect to the Alibaba Cloud STS, the RAM or STS is not activated, no role is created and the parameter is invalid.
 */
int oss_media_get_token(oss_media_config_t *config, 
                        const char *bucket_name, 
                        const char *path, 
                        const char *mode, 
                        int64_t expiration,
                        oss_media_token_t *token);

Example project:

void get_token() {
    int ret;
    char *bucket_name;
    oss_media_token_t token;
    oss_media_config_t config;
    
    /* Initialize the variable */
    bucket_name = "<your bucket name>";
    init_media_config(&config);

    /* Get the temporary token */
    ret = oss_media_get_token(&config, bucket_name, "/*", "rwa", 
                            3600, &token);

    if (0 == ret) {
        printf("get token succeeded, access_key_id=%s, access_key_secret=%s, token=%s\n", 
               token.tmpAccessKeyId, token.tmpAccessKeySecret, token.securityToken);
    } else {
        printf("get token failed.\n");
    }
}
Note For the complete code, see GitHub.

Get the token through a custom policy

/**
 *  @brief  Get the token through the specific custom policy
 *  @param[in]:
 *      expiration:  The valid period of the temporary token. The value ranges from 15 minutes to one hour. The unit is second.
 *  @return:
 *      If 0 is returned, it indicates the operation is successful.
 *      Otherwise, if "-1" is returned, it indicates an error may occur. Possible causes of the failure include: the object cannot connect to the Alibaba Cloud STS, the RAM or STS is not activated, no role is created and the parameter is invalid.
 */
int oss_media_get_token_from_policy(oss_media_config_t *config, 
                                    const char *policy, 
                                    int64_t expiration,
                                    oss_media_token_t *token);

Example project:

void get_token_from_policy() {
    int ret;
    oss_media_token_t token;
    char *policy;
    oss_media_config_t config;
    
    /* Initialize the variable */
    init_media_config(&config);

    /* Set the custom policy */
    policy = "{\"Version\":\"1\",\"Statement\":[{\"Effect\":\"Allow\", "
             "\"Action\":\"*\", \"Resource\":\"*\"}]}";

    /* Get the token */
    ret = oss_media_get_token_from_policy(&config, policy, 3600, &token);

    if (0 == ret) {
        printf("get token succeeded, access_key_id=%s, access_key_secret=%s, token=%s\n", 
               token.tmpAccessKeyId, token.tmpAccessKeySecret, token.securityToken);
    } else {
        printf("get token failed.\n");
    }
}
Note For the complete code, see GitHub.