Obtaining Bucket Metadata (SDK for C)

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

Function

This API returns information about a bucket, including the storage class, region, CORS rules, and redundancy policy.

Restrictions

To determine whether a bucket exists, you must be the bucket owner or have the required permission (obs:bucket:HeadBucket in IAM or HeadBucket in a bucket 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 obs_head_bucket(const obs_options *options, 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
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
callback_data	void *	No	Explanation: Custom callback data. Restrictions: None Value range: None Default value: None

Sample code

This example obtains the metadata of a bucket.

     #include "eSDKOBS.h"
#include <stdio.h>
#include <string.h>
// The response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data);
// The callback function for the completed response. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
typedef struct BucketMetadata
{
    char bucket_location[256];
    char storage_class[64];
    char obs_version[64];
    char obs_head_epid[256];
    obs_status ret_status;
} BucketMetadata;
int main()
{
    // The following example shows how to use obs_head_bucket to obtain bucket metadata:
    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
    obs_status ret_status = obs_initialize(OBS_INIT_ALL);
    if (OBS_STATUS_OK != ret_status)
    {
        printf("obs_initialize failed(%s).\n", obs_get_status_name(ret_status));
        return -1;
    }
    obs_options options;
    // Create and initialize options, including the access domain name (host_name), access keys (access_key_id and access_key_secret), bucket name (bucket_name), and bucket storage class (storage_class).
    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");
    // Specify the bucket name, for example, example-bucket-name.
    char * bucketName = "example-bucket-name";
    options.bucket_options.bucket_name = bucketName;
    obs_response_handler response_handler = { &response_properties_callback, &response_complete_callback };
    // Create callback data.
    BucketMetadata metadata;
    memset(&metadata, 0, sizeof(BucketMetadata));
    metadata.ret_status = OBS_STATUS_BUTT;
    // Obtain the bucket metadata.
    obs_head_bucket(&options, &response_handler, &metadata);
    if (OBS_STATUS_OK == metadata.ret_status) {
        printf("get bucket metadata successfully.\n");
        printf("bucket_location: %s\n", metadata.bucket_location);
        printf("storage_class: %s\n", metadata.storage_class);
        printf("obs_version: %s\n", metadata.obs_version);
        printf("obs_head_epid: %s\n", metadata.obs_head_epid);
    }
    else
    {
        printf("get bucket metadata failed(%s).\n", obs_get_status_name(metadata.ret_status));
    }
    // Release the allocated global resources.
    obs_deinitialize();
}
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data)
{
    BucketMetadata *metadata = (BucketMetadata *)callback_data;
    if (properties == NULL)
    {
        return OBS_STATUS_OK;
    }
    //Record the bucket metadata in callback_data.
    if (properties->bucket_location) {
        strncpy(metadata->bucket_location, properties->bucket_location, sizeof(metadata->bucket_location) - 1);
    }
    if (properties->storage_class) {
        strncpy(metadata->storage_class, properties->storage_class, sizeof(metadata->storage_class) - 1);
    }
    if (properties->obs_version) {
        strncpy(metadata->obs_version, properties->obs_version, sizeof(metadata->obs_version) - 1);
    }
    if (properties->obs_head_epid) {
        strncpy(metadata->obs_head_epid, properties->obs_head_epid, sizeof(metadata->obs_head_epid) - 1);
    }
    return OBS_STATUS_OK;
}
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
{
    if (callback_data) {
        BucketMetadata *metadata = (BucketMetadata *)callback_data;
        metadata->ret_status = status;
    }
    if (error && error->message) {
        printf("Error: %s\n", error->message);
    }
}
 
 
  