Configuring WORM Retention for an Object (SDK for C)

If you have any questions during development, post them on the Issues page of GitHub.

Function

This API is used to configure or update the retention period for objects uploaded to a bucket with WORM enabled.

If you did not configure a retention period or apply the default bucket-level retention policy when uploading an object, you can call this API to configure a retention period for the object.
If you already configured a retention period or applied the default bucket-level retention policy when uploading an object, you can call this API to prolong the retention period for the object.
The retention period of an object can only be modified, but not deleted.

Restrictions

To call this API, you must be the bucket owner or have the permission (obs:bucket:PutBucketObjectLockConfiguration granted using IAM or PutBucketObjectLockConfiguration granted using a bucket policy) to set a bucket-level WORM retention policy. For details, see Introduction to OBS Access Control, IAM Custom Policies, and Creating a Custom Bucket Policy.
The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.

Method

void set_object_retention(const obs_options *options, const char *key,
    obs_object_retention *retention, const char *version_id,
    obs_response_handler *handler, void *callback_data);

Request Parameters

**Table 1** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
options	const obs_options*	Yes	Explanation: Context of the requested bucket. You can set the AK, SK, endpoint, bucket, timeout interval, and temporary credentials through obs_options. Restrictions: None Value range: None Default value: None
key	const char *	Yes	Explanation: Object name. An object name uniquely identifies an object in a bucket. Restrictions: None Value range: The value can contain 1 to 1,024 characters. Default value: None
retention	Table 2*	Yes	Explanation: Structure of an object WORM retention policy. Restrictions: None Value range: None Default value: None
version_id	const char *	No	Explanation: Object version ID. If versioning is enabled, you can specify the version ID of an object. Restrictions: None Value range: None Default value: None. By default, the latest version of the object is operated.
handler	obs_response_handler *	Yes	Explanation: A callback structure where all members are pointers to callback functions, used to set the callback functions that handle response data. You can set a callback function to copy the response data from the server to callback_data (custom callback data). Restrictions: None Value range: None Default value: None
callback_data	void *	No	Explanation: Custom callback data. Restrictions: None Value range: None Default value: None

**Table 2** obs_object_retention
Parameter	Type	Mandatory (Yes/No)	Description
mode	char *	Yes	Explanation: Retention mode. Restrictions: None Value range: COMPLIANCE: In compliance mode, no user can delete protected objects during the retention period. Default value: None
retain_until_date	int64_t	Yes	Explanation: Retention expiration timestamp, in milliseconds. After the retention period expires, the object is no longer protected by WORM. Restrictions: In compliance mode, the retention period can only be prolonged, not shortened. Value range: A timestamp later than the current time, in milliseconds Default value: None

Sample Code

This example configures a WORM retention policy for an object.

     #include "eSDKOBS.h"
#include <stdio.h>
#include <time.h>
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data);
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
int main()
{
    obs_initialize(OBS_INIT_ALL);
    obs_options options;
    init_obs_options(&options);
    // Enter the endpoint corresponding to the bucket for host_name. CN-Hong Kong is used here as an example. Replace it with the one currently in use.
    options.bucket_options.host_name = "obs.ap-southeast-1.myhuaweicloud.com";
    // Hard-coded or plaintext AK and SK are risky. For security purposes, encrypt your AK and SK and store them in the configuration file or environment variables.
    // In this example, the AK and SK are stored in environment variables for identity authentication. Before running the code in this example, configure local environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    options.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    options.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    options.bucket_options.bucket_name = "example-bucket-name";
    // Configure a WORM retention policy for an object. Use compliance mode and set the retention period to one day.
    time_t now = time(NULL);
    int64_t retain_until_date = (int64_t)now * 1000 + (1 * 24 * 60 * 60 * 1000LL);
    obs_object_retention retention = {0};
    retention.mode = "COMPLIANCE";
    retention.retain_until_date = retain_until_date;
    obs_response_handler response_handler = {&response_properties_callback, &response_complete_callback};
    obs_status ret_status = OBS_STATUS_BUTT;
    set_object_retention(&options, "objectname", &retention, NULL, &response_handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("set object retention successfully.\n");
    } else {
        printf("set object retention failed(%s).\n", obs_get_status_name(ret_status));
    }
    obs_deinitialize();
}
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data)
{
    (void)properties; (void)callback_data;
    return OBS_STATUS_OK;
}
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
{
    if (callback_data) { *(obs_status*)callback_data = status; }
    if (error && error->message) { printf("Error: %s\n", error->message); }
}
 
 
  