diff --git a/docs/obs_3rd_party/c_sdk/ALL_META.TXT.json b/docs/obs_3rd_party/c_sdk/ALL_META.TXT.json new file mode 100644 index 000000000..098397fe5 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/ALL_META.TXT.json @@ -0,0 +1,1895 @@ +[ + { + "dockw":"C SDK Developer Guide" + }, + { + "uri":"obs_20_0101.html", + "node_id":"obs_20_0101.xml", + "product_code":"obs", + "code":"1", + "des":"This section describes the version compatibility and important notes about the C SDK of Object Storage Service (OBS).3.*.* is compatible with 3.0.0.3.*.* is incompatible ", + "doc_type":"sdk-c-devg", + "kw":"Before You Start,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Before You Start", + "githuburl":"" + }, + { + "uri":"obs_20_0004.html", + "node_id":"obs_20_0004.xml", + "product_code":"obs", + "code":"2", + "des":"This section provides the download and compilation methods for the OBS SDK for C.Latest version of OBS C SDK source code: Click here to download.You can compile the SDK b", + "doc_type":"sdk-c-devg", + "kw":"Downloading and Installing the SDK,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Downloading and Installing the SDK", + "githuburl":"" + }, + { + "uri":"obs_20_0100.html", + "node_id":"obs_20_0100.xml", + "product_code":"obs", + "code":"3", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Getting Started", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Getting Started", + "githuburl":"" + }, + { + "uri":"obs_20_0103.html", + "node_id":"obs_20_0103.xml", + "product_code":"obs", + "code":"4", + "des":"OBS uses the AK and SK in a user account for signature verification to make sure that only authorized accounts can access specified OBS resources. Detailed explanations a", + "doc_type":"sdk-c-devg", + "kw":"Creating Access Keys,Getting Started,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Creating Access Keys", + "githuburl":"" + }, + { + "uri":"obs_20_0104.html", + "node_id":"obs_20_0104.xml", + "product_code":"obs", + "code":"5", + "des":"You can click here to view the endpoints and regions enabled for OBS.", + "doc_type":"sdk-c-devg", + "kw":"Obtaining Endpoints,Getting Started,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining Endpoints", + "githuburl":"" + }, + { + "uri":"obs_20_1805.html", + "node_id":"obs_20_1805.xml", + "product_code":"obs", + "code":"6", + "des":"ObsClient functions as the C client for accessing OBS. It offers callers a series of APIs for interaction with OBS. These APIs are used for managing and operating resourc", + "doc_type":"sdk-c-devg", + "kw":"Initializing the SDK,Getting Started,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Initializing the SDK", + "githuburl":"" + }, + { + "uri":"obs_20_0105.html", + "node_id":"obs_20_0105.xml", + "product_code":"obs", + "code":"7", + "des":"When the function of SDK for C is called, the option parameter must be passed. You can use function init_obs_options to initialize the option configuration, including the", + "doc_type":"sdk-c-devg", + "kw":"Initializing option,Getting Started,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Initializing option", + "githuburl":"" + }, + { + "uri":"obs_20_0106.html", + "node_id":"obs_20_0106.xml", + "product_code":"obs", + "code":"8", + "des":"A bucket is a global namespace of OBS and is a data container. It functions as a root directory of a file system and can store objects.Sample code:static void test_create", + "doc_type":"sdk-c-devg", + "kw":"Creating a Bucket,Getting Started,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Creating a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0107.html", + "node_id":"obs_20_0107.xml", + "product_code":"obs", + "code":"9", + "des":"The data flow is saved to callback_data (see the callback_data definition in Uploading an Object - Streaming). Use the callback function put_object_data_callback defined ", + "doc_type":"sdk-c-devg", + "kw":"Uploading an Object,Getting Started,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Uploading an Object", + "githuburl":"" + }, + { + "uri":"obs_20_0108.html", + "node_id":"obs_20_0108.xml", + "product_code":"obs", + "code":"10", + "des":"This example shows how to download an object from a bucket to a directory and save the object as test.Sample code:For more information, see Downloading an Object.", + "doc_type":"sdk-c-devg", + "kw":"Downloading an Object,Getting Started,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Downloading an Object", + "githuburl":"" + }, + { + "uri":"obs_20_0109.html", + "node_id":"obs_20_0109.xml", + "product_code":"obs", + "code":"11", + "des":"This example shows how to list all objects in a bucket.Sample code:For more information, see Listing Objects in a Bucket.", + "doc_type":"sdk-c-devg", + "kw":"Listing Objects,Getting Started,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Listing Objects", + "githuburl":"" + }, + { + "uri":"obs_20_0110.html", + "node_id":"obs_20_0110.xml", + "product_code":"obs", + "code":"12", + "des":"This example shows how to delete an object from a bucket.Sample code:For more information, see Deleting an Object.", + "doc_type":"sdk-c-devg", + "kw":"Deleting an Object,Getting Started,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Deleting an Object", + "githuburl":"" + }, + { + "uri":"obs_20_0200.html", + "node_id":"obs_20_0200.xml", + "product_code":"obs", + "code":"13", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Initialization", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Initialization", + "githuburl":"" + }, + { + "uri":"obs_20_0201.html", + "node_id":"obs_20_0201.xml", + "product_code":"obs", + "code":"14", + "des":"To use OBS, you need a valid pair of AK and SK for signature authentication. For details, see Creating Access Keys.After obtaining the AK and SK, you can start initializa", + "doc_type":"sdk-c-devg", + "kw":"Configuring Access Keys,Initialization,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Configuring Access Keys", + "githuburl":"" + }, + { + "uri":"obs_20_0202.html", + "node_id":"obs_20_0202.xml", + "product_code":"obs", + "code":"15", + "des":"ObsClient functions as the C client for accessing OBS. It offers callers a series of APIs for interaction with OBS. These APIs are used for managing and operating resourc", + "doc_type":"sdk-c-devg", + "kw":"Initializing the SDK,Initialization,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Initializing the SDK", + "githuburl":"" + }, + { + "uri":"obs_20_0203.html", + "node_id":"obs_20_0203.xml", + "product_code":"obs", + "code":"16", + "des":"When the function of SDK for C is called, the obs_options parameter must be passed. You can use function init_obs_options to initialize the obs_options configuration, inc", + "doc_type":"sdk-c-devg", + "kw":"Configuring option,Initialization,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Configuring option", + "githuburl":"" + }, + { + "uri":"obs_20_0204.html", + "node_id":"obs_20_0204.xml", + "product_code":"obs", + "code":"17", + "des":"The OBS C SDK log path is specified by the LogPath field in OBS.ini. By default, logs are stored in the logs directory at the same level as the lib directory of the C SDK", + "doc_type":"sdk-c-devg", + "kw":"Configuring SDK Logging,Initialization,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Configuring SDK Logging", + "githuburl":"" + }, + { + "uri":"obs_20_0300.html", + "node_id":"obs_20_0300.xml", + "product_code":"obs", + "code":"18", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Bucket Management", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Bucket Management", + "githuburl":"" + }, + { + "uri":"obs_20_0301.html", + "node_id":"obs_20_0301.xml", + "product_code":"obs", + "code":"19", + "des":"OBS buckets are containers for storing objects you upload to OBS. This API creates a bucket.When creating a bucket, you can also configure parameters such as the storage ", + "doc_type":"sdk-c-devg", + "kw":"Creating a Bucket,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Creating a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0302.html", + "node_id":"obs_20_0302.xml", + "product_code":"obs", + "code":"20", + "des":"OBS buckets are containers for storing objects you upload to OBS. This API returns a list of all buckets that meet the specified conditions in all regions of the current ", + "doc_type":"sdk-c-devg", + "kw":"Listing Buckets,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Listing Buckets", + "githuburl":"" + }, + { + "uri":"obs_20_0303.html", + "node_id":"obs_20_0303.xml", + "product_code":"obs", + "code":"21", + "des":"This API deletes an empty bucket. You can delete buckets you no longer use to free up space. The name of a deleted bucket can be reused for another bucket at least 30 min", + "doc_type":"sdk-c-devg", + "kw":"Deleting a Bucket,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Deleting a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0304.html", + "node_id":"obs_20_0304.xml", + "product_code":"obs", + "code":"22", + "des":"This API checks whether a bucket exists. If an HTTP status code 200 is returned, the bucket exists. If 404 is returned, the bucket does not exist.To determine whether a b", + "doc_type":"sdk-c-devg", + "kw":"Checking Whether a Bucket Exists,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Checking Whether a Bucket Exists", + "githuburl":"" + }, + { + "uri":"obs_20_0305.html", + "node_id":"obs_20_0305.xml", + "product_code":"obs", + "code":"23", + "des":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "doc_type":"sdk-c-devg", + "kw":"Configuring a Bucket ACL,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Configuring a Bucket ACL", + "githuburl":"" + }, + { + "uri":"obs_20_0311.html", + "node_id":"obs_20_0311.xml", + "product_code":"obs", + "code":"24", + "des":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "doc_type":"sdk-c-devg", + "kw":"Obtaining a Bucket ACL,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining a Bucket ACL", + "githuburl":"" + }, + { + "uri":"obs_20_0306.html", + "node_id":"obs_20_0306.xml", + "product_code":"obs", + "code":"25", + "des":"This API returns the storage information on a bucket, including the number of objects and the space occupied by the objects in the bucket.OBS measures bucket storage stat", + "doc_type":"sdk-c-devg", + "kw":"Obtaining Bucket Storage Information,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining Bucket Storage Information", + "githuburl":"" + }, + { + "uri":"obs_20_0307.html", + "node_id":"obs_20_0307.xml", + "product_code":"obs", + "code":"26", + "des":"A quota limits the maximum capacity allowed in a bucket. By default, there is no limit on the storage capacity of the entire OBS system or a single bucket, and any number", + "doc_type":"sdk-c-devg", + "kw":"Setting a Bucket Quota,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Setting a Bucket Quota", + "githuburl":"" + }, + { + "uri":"obs_20_0310.html", + "node_id":"obs_20_0310.xml", + "product_code":"obs", + "code":"27", + "des":"This API returns the storage quota (upper limit of the storage capacity) of a bucket. If the quota is 0, there is no upper limit on the bucket capacity.A bucket storage q", + "doc_type":"sdk-c-devg", + "kw":"Obtaining the Storage Quota of a Bucket,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining the Storage Quota of a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0308.html", + "node_id":"obs_20_0308.xml", + "product_code":"obs", + "code":"28", + "des":"This API configures a storage class for a bucket. If you do not specify a storage class when uploading or copying an object, or initiating a multipart upload, the object ", + "doc_type":"sdk-c-devg", + "kw":"Configuring a Storage Class for a Bucket,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Configuring a Storage Class for a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0309.html", + "node_id":"obs_20_0309.xml", + "product_code":"obs", + "code":"29", + "des":"This API returns the storage class of a bucket.To obtain a bucket's storage class, you must be the bucket owner or have the required permission (obs:bucket:GetBucketStora", + "doc_type":"sdk-c-devg", + "kw":"Obtaining the Storage Class of a Bucket,Bucket Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining the Storage Class of a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0400.html", + "node_id":"obs_20_0400.xml", + "product_code":"obs", + "code":"30", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Object Upload", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Object Upload", + "githuburl":"" + }, + { + "uri":"obs_20_0401.html", + "node_id":"obs_20_0401.xml", + "product_code":"obs", + "code":"31", + "des":"This API uploads a local fileto OBS over the Internet. You can upload text, pictures, videos, or any other types of files.You can upload texts, images, videos, or any oth", + "doc_type":"sdk-c-devg", + "kw":"Uploading an Object - Streaming,Object Upload,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Uploading an Object - Streaming", + "githuburl":"" + }, + { + "uri":"obs_20_0402.html", + "node_id":"obs_20_0402.xml", + "product_code":"obs", + "code":"32", + "des":"This API uploads local filesto OBS over the Internet. You can upload text, pictures, videos, or any other types of files.This API uploads an object in text to a bucket.To", + "doc_type":"sdk-c-devg", + "kw":"Uploading an Object - File-Based,Object Upload,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Uploading an Object - File-Based", + "githuburl":"" + }, + { + "uri":"obs_20_0403.html", + "node_id":"obs_20_0403.xml", + "product_code":"obs", + "code":"33", + "des":"This API creates a folder in an existing bucket to manage data in OBS.OBS does not involve folders like in a file system. All elements in buckets are objects. To create a", + "doc_type":"sdk-c-devg", + "kw":"Creating a Folder,Object Upload,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Creating a Folder", + "githuburl":"" + }, + { + "uri":"obs_20_0407.html", + "node_id":"obs_20_0407.xml", + "product_code":"obs", + "code":"34", + "des":"The resumable upload is an encapsulated and enhanced version of the multipart upload used for dealing with possible upload failures of large files when the network connec", + "doc_type":"sdk-c-devg", + "kw":"Uploading an Object - Resumable,Object Upload,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Uploading an Object - Resumable", + "githuburl":"" + }, + { + "uri":"obs_20_0408.html", + "node_id":"obs_20_0408.xml", + "product_code":"obs", + "code":"35", + "des":"This API uploads a file or folder to an existing OBS bucket. You can upload text, pictures, videos, or any other types of files.This API adds data to the end of a specifi", + "doc_type":"sdk-c-devg", + "kw":"Uploading an Object - Append,Object Upload,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Uploading an Object - Append", + "githuburl":"" + }, + { + "uri":"obs_20_0500.html", + "node_id":"obs_20_0500.xml", + "product_code":"obs", + "code":"36", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Object Download", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Object Download", + "githuburl":"" + }, + { + "uri":"obs_20_0501.html", + "node_id":"obs_20_0501.xml", + "product_code":"obs", + "code":"37", + "des":"This API downloads an object as text from OBS to your local computer.To download an object, you must be the bucket owner or have the required permission (obs:object:GetOb", + "doc_type":"sdk-c-devg", + "kw":"Downloading an Object,Object Download,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Downloading an Object", + "githuburl":"" + }, + { + "uri":"obs_20_0502.html", + "node_id":"obs_20_0502.xml", + "product_code":"obs", + "code":"38", + "des":"This API returns the objects that meet one or more conditions. If there are no objects that meet the specified conditions, an error is returned.To download an object, you", + "doc_type":"sdk-c-devg", + "kw":"Downloading an Object - Conditional,Object Download,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Downloading an Object - Conditional", + "githuburl":"" + }, + { + "uri":"obs_20_0503.html", + "node_id":"obs_20_0503.xml", + "product_code":"obs", + "code":"39", + "des":"To obtain the content of an object in the Cold storage class, you need to restore the object first and then you can download it. After an object is restored, a copy of th", + "doc_type":"sdk-c-devg", + "kw":"Restoring a Cold Object,Object Download,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Restoring a Cold Object", + "githuburl":"" + }, + { + "uri":"obs_20_0504.html", + "node_id":"obs_20_0504.xml", + "product_code":"obs", + "code":"40", + "des":"Downloading large files often fails due to an unstable network or program breakdown. It is a waste of resources to download files again. Moreover, the restarted download ", + "doc_type":"sdk-c-devg", + "kw":"Downloading an Object - Resumable,Object Download,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Downloading an Object - Resumable", + "githuburl":"" + }, + { + "uri":"obs_20_0600.html", + "node_id":"obs_20_0600.xml", + "product_code":"obs", + "code":"41", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Object Management", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Object Management", + "githuburl":"" + }, + { + "uri":"obs_20_0404.html", + "node_id":"obs_20_0404.xml", + "product_code":"obs", + "code":"42", + "des":"This API sets properties for an object when uploading it. Object properties include the object length, MIME type, MD5 value (for verification), storage class, and custom ", + "doc_type":"sdk-c-devg", + "kw":"Setting Object Properties,Object Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Setting Object Properties", + "githuburl":"" + }, + { + "uri":"obs_20_0601.html", + "node_id":"obs_20_0601.xml", + "product_code":"obs", + "code":"43", + "des":"Object metadata contains a set of name-value pairs that are used for describing and managing objects.Currently, only the system-defined metadata is supported. System-defi", + "doc_type":"sdk-c-devg", + "kw":"Obtaining Object Properties,Object Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining Object Properties", + "githuburl":"" + }, + { + "uri":"obs_20_0602.html", + "node_id":"obs_20_0602.xml", + "product_code":"obs", + "code":"44", + "des":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "doc_type":"sdk-c-devg", + "kw":"Setting a Pre-defined ACL During Object Upload,Object Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Setting a Pre-defined ACL During Object Upload", + "githuburl":"" + }, + { + "uri":"obs_20_0314.html", + "node_id":"obs_20_0314.xml", + "product_code":"obs", + "code":"45", + "des":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "doc_type":"sdk-c-devg", + "kw":"Setting a Pre-defined ACL for an Object,Object Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Setting a Pre-defined ACL for an Object", + "githuburl":"" + }, + { + "uri":"obs_20_0315.html", + "node_id":"obs_20_0315.xml", + "product_code":"obs", + "code":"46", + "des":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "doc_type":"sdk-c-devg", + "kw":"Setting a User-defined Object ACL,Object Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Setting a User-defined Object ACL", + "githuburl":"" + }, + { + "uri":"obs_20_0316.html", + "node_id":"obs_20_0316.xml", + "product_code":"obs", + "code":"47", + "des":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "doc_type":"sdk-c-devg", + "kw":"Obtaining the ACL of an Object,Object Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining the ACL of an Object", + "githuburl":"" + }, + { + "uri":"obs_20_0603.html", + "node_id":"obs_20_0603.xml", + "product_code":"obs", + "code":"48", + "des":"This API lists some or all of the objects in a bucket. You can use parameters such as the prefix, number of returned objects, and start position to list objects that meet", + "doc_type":"sdk-c-devg", + "kw":"Listing Objects in a Bucket,Object Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Listing Objects in a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0604.html", + "node_id":"obs_20_0604.xml", + "product_code":"obs", + "code":"49", + "des":"This API deletes an object in the specified bucket to save space and costs.To delete an object, you must be the bucket owner or have the required permission (obs:object:D", + "doc_type":"sdk-c-devg", + "kw":"Deleting an Object,Object Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Deleting an Object", + "githuburl":"" + }, + { + "uri":"obs_20_1813.html", + "node_id":"obs_20_1813.xml", + "product_code":"obs", + "code":"50", + "des":"This API deletes objects in a batch from a specific bucket. Deleted objects cannot be restored.In a batch deletion, OBS concurrently deletes the specified objects and ret", + "doc_type":"sdk-c-devg", + "kw":"Batch Deleting Objects,Object Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Batch Deleting Objects", + "githuburl":"" + }, + { + "uri":"obs_20_0605.html", + "node_id":"obs_20_0605.xml", + "product_code":"obs", + "code":"51", + "des":"This API copies an object stored in a specified bucket to another path by creating a copy of the object. You can copy an object of up to 5 GB in a single operation.To cop", + "doc_type":"sdk-c-devg", + "kw":"Copying an Object,Object Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Copying an Object", + "githuburl":"" + }, + { + "uri":"obs_20_1812.html", + "node_id":"obs_20_1812.xml", + "product_code":"obs", + "code":"52", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Multipart Upload APIs", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Multipart Upload APIs", + "githuburl":"" + }, + { + "uri":"obs_20_1811.html", + "node_id":"obs_20_1811.xml", + "product_code":"obs", + "code":"53", + "des":"You can upload a large file using multipart upload. Multipart upload is applicable to many scenarios. Below are some examples.A file to be uploaded is larger than 100 MB.", + "doc_type":"sdk-c-devg", + "kw":"Multipart Upload APIs,Multipart Upload APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Multipart Upload APIs", + "githuburl":"" + }, + { + "uri":"obs_20_0405.html", + "node_id":"obs_20_0405.xml", + "product_code":"obs", + "code":"54", + "des":"This API initiates a multipart upload and returns a globally unique upload ID. You can use this upload ID in your subsequent requests for uploading, assembling, and listi", + "doc_type":"sdk-c-devg", + "kw":"Initiating a Multipart Upload,Multipart Upload APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Initiating a Multipart Upload", + "githuburl":"" + }, + { + "uri":"obs_20_1810.html", + "node_id":"obs_20_1810.xml", + "product_code":"obs", + "code":"55", + "des":"After a multipart upload is initiated, this API uploads a part to a specified bucket. In the upload request, the multipart upload ID must be included. The last part uploa", + "doc_type":"sdk-c-devg", + "kw":"Uploading a Part,Multipart Upload APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Uploading a Part", + "githuburl":"" + }, + { + "uri":"obs_20_1809.html", + "node_id":"obs_20_1809.xml", + "product_code":"obs", + "code":"56", + "des":"This API assembles the uploaded parts to complete the multipart upload. Before performing this operation, you cannot download the uploaded data. When assembling parts, yo", + "doc_type":"sdk-c-devg", + "kw":"Assembling Parts,Multipart Upload APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Assembling Parts", + "githuburl":"" + }, + { + "uri":"obs_20_1808.html", + "node_id":"obs_20_1808.xml", + "product_code":"obs", + "code":"57", + "des":"This API lists multipart uploads that have been initiated but not completed or cancelled.For each listing request, OBS can list a maximum of 1,000 multipart upload tasks.", + "doc_type":"sdk-c-devg", + "kw":"Listing Multipart Uploads,Multipart Upload APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Listing Multipart Uploads", + "githuburl":"" + }, + { + "uri":"obs_20_1807.html", + "node_id":"obs_20_1807.xml", + "product_code":"obs", + "code":"58", + "des":"This API lists the uploaded parts in a specified bucket. This request must contain the multipart upload ID.You can list the uploaded parts of a specified multipart upload", + "doc_type":"sdk-c-devg", + "kw":"Listing Uploaded Parts,Multipart Upload APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Listing Uploaded Parts", + "githuburl":"" + }, + { + "uri":"obs_20_0406.html", + "node_id":"obs_20_0406.xml", + "product_code":"obs", + "code":"59", + "des":"This API uploads a part for a specified multipart upload by copying data to a specified bucket.After initiating a multipart upload task, you can add parts for this task b", + "doc_type":"sdk-c-devg", + "kw":"Copying a Part,Multipart Upload APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Copying a Part", + "githuburl":"" + }, + { + "uri":"obs_20_1806.html", + "node_id":"obs_20_1806.xml", + "product_code":"obs", + "code":"60", + "des":"This API aborts a multipart upload, which is specified by its ID.After a multipart upload is aborted, its upload ID cannot be used to upload any part. And the space occup", + "doc_type":"sdk-c-devg", + "kw":"Aborting a Multipart Upload,Multipart Upload APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Aborting a Multipart Upload", + "githuburl":"" + }, + { + "uri":"obs_20_0800.html", + "node_id":"obs_20_0800.xml", + "product_code":"obs", + "code":"61", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Versioning", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Versioning", + "githuburl":"" + }, + { + "uri":"obs_20_0802.html", + "node_id":"obs_20_0802.xml", + "product_code":"obs", + "code":"62", + "des":"You can enable versioning to automatically maintain previous versions of an object. When versioning is enabled, you can access earlier versions of an object to recover yo", + "doc_type":"sdk-c-devg", + "kw":"Configuring Versioning for a Bucket,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Configuring Versioning for a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0803.html", + "node_id":"obs_20_0803.xml", + "product_code":"obs", + "code":"63", + "des":"You can enable versioning to automatically maintain previous versions of an object. When versioning is enabled, you can access earlier versions of an object to recover yo", + "doc_type":"sdk-c-devg", + "kw":"Obtaining the Versioning Status of a Bucket,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining the Versioning Status of a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0804.html", + "node_id":"obs_20_0804.xml", + "product_code":"obs", + "code":"64", + "des":"You can call get_object to obtain an object version by specifying the version ID (obs_object_info.version_id).If the version ID is not specified, the object of the latest", + "doc_type":"sdk-c-devg", + "kw":"Obtaining an Object Version,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining an Object Version", + "githuburl":"" + }, + { + "uri":"obs_20_0805.html", + "node_id":"obs_20_0805.xml", + "product_code":"obs", + "code":"65", + "des":"This API copies an object version in a specified bucket. You can create a copy up to 5 GB for a versioned object in a single operation.To copy a versioned object, you mus", + "doc_type":"sdk-c-devg", + "kw":"Copying an Object Version,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Copying an Object Version", + "githuburl":"" + }, + { + "uri":"obs_20_0806.html", + "node_id":"obs_20_0806.xml", + "product_code":"obs", + "code":"66", + "des":"To obtain the content of an object version in the Cold storage class, you need to restore the object version first and then you can download it. After an object version i", + "doc_type":"sdk-c-devg", + "kw":"Restoring a Specific Cold Object Version,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Restoring a Specific Cold Object Version", + "githuburl":"" + }, + { + "uri":"obs_20_0807.html", + "node_id":"obs_20_0807.xml", + "product_code":"obs", + "code":"67", + "des":"This API lists some or all of the object versions in a bucket. You can use parameters such as the prefix, number of returned object versions, and start position to list t", + "doc_type":"sdk-c-devg", + "kw":"Listing Object Versions in a Bucket,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Listing Object Versions in a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0317.html", + "node_id":"obs_20_0317.xml", + "product_code":"obs", + "code":"68", + "des":"OBS allows you to control access to versioned objects. By default, only the versioned object creator has the read and write permissions on the object. You can set access ", + "doc_type":"sdk-c-devg", + "kw":"Setting a Pre-defined ACL for an Object Version,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Setting a Pre-defined ACL for an Object Version", + "githuburl":"" + }, + { + "uri":"obs_20_0318.html", + "node_id":"obs_20_0318.xml", + "product_code":"obs", + "code":"69", + "des":"OBS allows you to control access to versioned objects. By default, only the versioned object creator has the read and write permissions on the object. You can set access ", + "doc_type":"sdk-c-devg", + "kw":"Setting an Object Version ACL Directly,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Setting an Object Version ACL Directly", + "githuburl":"" + }, + { + "uri":"obs_20_0319.html", + "node_id":"obs_20_0319.xml", + "product_code":"obs", + "code":"70", + "des":"OBS provides access control over buckets. You can use an access policy to define whether a user can perform certain operations on a specific bucket. OBS access control ca", + "doc_type":"sdk-c-devg", + "kw":"Obtaining the ACL of an Object Version,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining the ACL of an Object Version", + "githuburl":"" + }, + { + "uri":"obs_20_0809.html", + "node_id":"obs_20_0809.xml", + "product_code":"obs", + "code":"71", + "des":"This API deletes an object version in the specified bucket to save space and costs.To delete an object version, you must be the bucket owner or have the required permissi", + "doc_type":"sdk-c-devg", + "kw":"Deleting an Object Version,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Deleting an Object Version", + "githuburl":"" + }, + { + "uri":"obs_23_1713.html", + "node_id":"obs_23_1713.xml", + "product_code":"obs", + "code":"72", + "des":"This API deletes object versions in a batch in the specified bucket to save space and costs.To delete object versions, you must be the bucket owner or have the required p", + "doc_type":"sdk-c-devg", + "kw":"Batch Deleting Object Versions,Versioning,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Batch Deleting Object Versions", + "githuburl":"" + }, + { + "uri":"obs_20_0900.html", + "node_id":"obs_20_0900.xml", + "product_code":"obs", + "code":"73", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Lifecycle Management", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Lifecycle Management", + "githuburl":"" + }, + { + "uri":"obs_20_0901.html", + "node_id":"obs_20_0901.xml", + "product_code":"obs", + "code":"74", + "des":"OBS allows you to set lifecycle rules for buckets to automatically transition the storage class of an object or delete expired objects, to effectively use storage feature", + "doc_type":"sdk-c-devg", + "kw":"Overview,Lifecycle Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Overview", + "githuburl":"" + }, + { + "uri":"obs_20_0902.html", + "node_id":"obs_20_0902.xml", + "product_code":"obs", + "code":"75", + "des":"You can configure lifecycle rules to periodically delete objects or transition objects between storage classes.This API configures lifecycle rules for a bucket.There is n", + "doc_type":"sdk-c-devg", + "kw":"Configuring Lifecycle Rules for a Bucket,Lifecycle Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Configuring Lifecycle Rules for a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0903.html", + "node_id":"obs_20_0903.xml", + "product_code":"obs", + "code":"76", + "des":"You can configure lifecycle rules to periodically delete objects or transition objects between storage classes.This API returns the lifecycle rules of a bucket.To obtain ", + "doc_type":"sdk-c-devg", + "kw":"Obtaining the Lifecycle Rules of a Bucket,Lifecycle Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining the Lifecycle Rules of a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_0904.html", + "node_id":"obs_20_0904.xml", + "product_code":"obs", + "code":"77", + "des":"You can configure lifecycle rules to periodically delete objects or transition objects between storage classes.This API deletes the lifecycle rules of a bucket.To delete ", + "doc_type":"sdk-c-devg", + "kw":"Deleting the Lifecycle Rules of a Bucket,Lifecycle Management,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Deleting the Lifecycle Rules of a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_1000.html", + "node_id":"obs_20_1000.xml", + "product_code":"obs", + "code":"78", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Cross-Origin Resource Sharing", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Cross-Origin Resource Sharing", + "githuburl":"" + }, + { + "uri":"obs_20_1002.html", + "node_id":"obs_20_1002.xml", + "product_code":"obs", + "code":"79", + "des":"Cross-origin resource sharing (CORS) is a mechanism defined by the World Wide Web Consortium (W3C) that allows a web application program in one domain to access resources", + "doc_type":"sdk-c-devg", + "kw":"Configuring CORS for a Bucket,Cross-Origin Resource Sharing,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Configuring CORS for a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_1003.html", + "node_id":"obs_20_1003.xml", + "product_code":"obs", + "code":"80", + "des":"Cross-origin resource sharing (CORS) is a mechanism defined by the World Wide Web Consortium (W3C) that allows a web application program in one domain to access resources", + "doc_type":"sdk-c-devg", + "kw":"Obtaining the CORS Configuration of a Bucket,Cross-Origin Resource Sharing,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining the CORS Configuration of a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_1004.html", + "node_id":"obs_20_1004.xml", + "product_code":"obs", + "code":"81", + "des":"Cross-origin resource sharing (CORS) is a mechanism defined by the World Wide Web Consortium (W3C) that allows a web application program in one domain to access resources", + "doc_type":"sdk-c-devg", + "kw":"Deleting the CORS Configuration of a Bucket,Cross-Origin Resource Sharing,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Deleting the CORS Configuration of a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_1100.html", + "node_id":"obs_20_1100.xml", + "product_code":"obs", + "code":"82", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Logging", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Logging", + "githuburl":"" + }, + { + "uri":"obs_20_1102.html", + "node_id":"obs_20_1102.xml", + "product_code":"obs", + "code":"83", + "des":"This API enables logging for a bucket (source) and configures another bucket (target) to store the log files. When a bucket is created, logging is not enabled by default.", + "doc_type":"sdk-c-devg", + "kw":"Configuring Logging for a Bucket,Logging,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Configuring Logging for a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_1103.html", + "node_id":"obs_20_1103.xml", + "product_code":"obs", + "code":"84", + "des":"This API returns the logging configuration of a bucket.To obtain the logging configuration of a bucket, you must be the bucket owner or have the required permission (obs:", + "doc_type":"sdk-c-devg", + "kw":"Obtaining the Logging Configuration of a Bucket,Logging,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining the Logging Configuration of a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_1200.html", + "node_id":"obs_20_1200.xml", + "product_code":"obs", + "code":"85", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Static Website Hosting", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Static Website Hosting", + "githuburl":"" + }, + { + "uri":"obs_20_1202.html", + "node_id":"obs_20_1202.xml", + "product_code":"obs", + "code":"86", + "des":"You can perform the following to implement website file hosting:This example implements website file hosting.#include \"eSDKOBS.h\"\n#include \n#include ", + "doc_type":"sdk-c-devg", + "kw":"Hosting Website Files in a Bucket,Static Website Hosting,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Hosting Website Files in a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_1203.html", + "node_id":"obs_20_1203.xml", + "product_code":"obs", + "code":"87", + "des":"You can host static website resources such as HTML web pages, flash files, or audio and video files in an OBS bucket, so that you can provide these hosted resources using", + "doc_type":"sdk-c-devg", + "kw":"Configuring Static Website Hosting for a Bucket,Static Website Hosting,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Configuring Static Website Hosting for a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_1204.html", + "node_id":"obs_20_1204.xml", + "product_code":"obs", + "code":"88", + "des":"You can host static website resources such as HTML web pages, flash files, or audio and video files in an OBS bucket, so that you can provide these hosted resources using", + "doc_type":"sdk-c-devg", + "kw":"Obtaining the Static Website Hosting Configuration of a Bucket,Static Website Hosting,C SDK Develope", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining the Static Website Hosting Configuration of a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_1205.html", + "node_id":"obs_20_1205.xml", + "product_code":"obs", + "code":"89", + "des":"You can host static website resources such as HTML web pages, flash files, or audio and video files in an OBS bucket, so that you can provide these hosted resources using", + "doc_type":"sdk-c-devg", + "kw":"Deleting the Static Website Hosting Configuration of a Bucket,Static Website Hosting,C SDK Developer", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Deleting the Static Website Hosting Configuration of a Bucket", + "githuburl":"" + }, + { + "uri":"obs_20_1300.html", + "node_id":"obs_20_1300.xml", + "product_code":"obs", + "code":"90", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Tagging", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Tagging", + "githuburl":"" + }, + { + "uri":"obs_20_1302.html", + "node_id":"obs_20_1302.xml", + "product_code":"obs", + "code":"91", + "des":"If you add tags to a bucket, SDRs generated for the requests sent to this bucket will include these tags, so you can use the tags to classify SDRs for detailed cost analy", + "doc_type":"sdk-c-devg", + "kw":"Adding Bucket Tags,Tagging,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Adding Bucket Tags", + "githuburl":"" + }, + { + "uri":"obs_20_1303.html", + "node_id":"obs_20_1303.xml", + "product_code":"obs", + "code":"92", + "des":"If you add tags to a bucket, SDRs generated for the requests sent to this bucket will include these tags, so you can use the tags to classify SDRs for detailed cost analy", + "doc_type":"sdk-c-devg", + "kw":"Obtaining Bucket Tags,Tagging,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Obtaining Bucket Tags", + "githuburl":"" + }, + { + "uri":"obs_20_1304.html", + "node_id":"obs_20_1304.xml", + "product_code":"obs", + "code":"93", + "des":"If you add tags to a bucket, SDRs generated for the requests sent to this bucket will include these tags, so you can use the tags to classify SDRs for detailed cost analy", + "doc_type":"sdk-c-devg", + "kw":"Deleting Bucket Tags,Tagging,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Deleting Bucket Tags", + "githuburl":"" + }, + { + "uri":"obs_20_1500.html", + "node_id":"obs_20_1500.xml", + "product_code":"obs", + "code":"94", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Other APIs", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Other APIs", + "githuburl":"" + }, + { + "uri":"obs_20_1501.html", + "node_id":"obs_20_1501.xml", + "product_code":"obs", + "code":"95", + "des":"This API configures server-side encryption for objects, so that they will be encrypted or decrypted when you upload them to or download them from a bucket.The encryption ", + "doc_type":"sdk-c-devg", + "kw":"Server-Side Encryption,Other APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Server-Side Encryption", + "githuburl":"" + }, + { + "uri":"obs_20_0700.html", + "node_id":"obs_20_0700.xml", + "product_code":"obs", + "code":"96", + "des":"This API creates a temporary URL to grant temporary permissions for operating OBS. This URL contains the information about the AK and SK, request method, and related para", + "doc_type":"sdk-c-devg", + "kw":"Using a Temporary URL for Authorized Access,Other APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Using a Temporary URL for Authorized Access", + "githuburl":"" + }, + { + "uri":"en-us_topic_0000001833016268.html", + "node_id":"en-us_topic_0000001833016268.xml", + "product_code":"obs", + "code":"97", + "des":"To access OBS through a user-defined domain name, you need to first configure a domain name on the Console.When using a user-defined domain name to access OBS, you can ca", + "doc_type":"sdk-c-devg", + "kw":"Using a User-Defined Domain Name to Access OBS,Other APIs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Using a User-Defined Domain Name to Access OBS", + "githuburl":"" + }, + { + "uri":"obs_20_1600.html", + "node_id":"obs_20_1600.xml", + "product_code":"obs", + "code":"98", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Troubleshooting", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Troubleshooting", + "githuburl":"" + }, + { + "uri":"obs_20_1601.html", + "node_id":"obs_20_1601.xml", + "product_code":"obs", + "code":"99", + "des":"If the OBS server encounters an error when processing a request, a response containing the error code and error description is returned. The following table lists details", + "doc_type":"sdk-c-devg", + "kw":"OBS Server-Side Error Codes,Troubleshooting,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"OBS Server-Side Error Codes", + "githuburl":"" + }, + { + "uri":"obs_20_1602.html", + "node_id":"obs_20_1602.xml", + "product_code":"obs", + "code":"100", + "des":"SDK errors include the errors returned during the check of function parameters and those returned by the OBS server.SDK error handling information:obs_status: Error codeo", + "doc_type":"sdk-c-devg", + "kw":"SDK Error Handling,Troubleshooting,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"SDK Error Handling", + "githuburl":"" + }, + { + "uri":"obs_20_1603.html", + "node_id":"obs_20_1603.xml", + "product_code":"obs", + "code":"101", + "des":"The OBS C SDK log path is specified by the LogPath field in OBS.ini. By default, logs are stored in the logs directory at the same level as the lib directory of the C SDK", + "doc_type":"sdk-c-devg", + "kw":"Log Analysis,Troubleshooting,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Log Analysis", + "githuburl":"" + }, + { + "uri":"obs_20_1800.html", + "node_id":"obs_20_1800.xml", + "product_code":"obs", + "code":"102", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"FAQs", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"FAQs", + "githuburl":"" + }, + { + "uri":"obs_20_1804.html", + "node_id":"obs_20_1804.xml", + "product_code":"obs", + "code":"103", + "des":"When the proxy is configured in a Windows SDK demo, the program reports the following error and the proxy configuration fails.Root cause: Due to asynchronous updates, the", + "doc_type":"sdk-c-devg", + "kw":"Invalid Proxy Settings,FAQs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Invalid Proxy Settings", + "githuburl":"" + }, + { + "uri":"obs_23_1712.html", + "node_id":"obs_23_1712.xml", + "product_code":"obs", + "code":"104", + "des":"When calling APIs, you may need to specify the account ID (DomainID) and user ID (UserID) in some requests. You need to obtain them from the console in advance. To obtain", + "doc_type":"sdk-c-devg", + "kw":"How Do I Get My Account ID and User ID?,FAQs,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"How Do I Get My Account ID and User ID?", + "githuburl":"" + }, + { + "uri":"obs_20_1702.html", + "node_id":"obs_20_1702.xml", + "product_code":"obs", + "code":"105", + "des":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "doc_type":"sdk-c-devg", + "kw":"Change History,C SDK Developer Guide", + "search_title":"", + "metedata":[ + { + "prodname":"obs", + "documenttype":"sdk-c-devg" + } + ], + "title":"Change History", + "githuburl":"" + } +] \ No newline at end of file diff --git a/docs/obs_3rd_party/c_sdk/CLASS.TXT.json b/docs/obs_3rd_party/c_sdk/CLASS.TXT.json new file mode 100644 index 000000000..42e73468d --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/CLASS.TXT.json @@ -0,0 +1,947 @@ +[ + { + "desc":"This section describes the version compatibility and important notes about the C SDK of Object Storage Service (OBS).3.*.* is compatible with 3.0.0.3.*.* is incompatible ", + "product_code":"obs", + "title":"Before You Start", + "uri":"obs_20_0101.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"1" + }, + { + "desc":"This section provides the download and compilation methods for the OBS SDK for C.Latest version of OBS C SDK source code: Click here to download.You can compile the SDK b", + "product_code":"obs", + "title":"Downloading and Installing the SDK", + "uri":"obs_20_0004.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"2" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Getting Started", + "uri":"obs_20_0100.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"3" + }, + { + "desc":"OBS uses the AK and SK in a user account for signature verification to make sure that only authorized accounts can access specified OBS resources. Detailed explanations a", + "product_code":"obs", + "title":"Creating Access Keys", + "uri":"obs_20_0103.html", + "doc_type":"sdk-c-devg", + "p_code":"3", + "code":"4" + }, + { + "desc":"You can click here to view the endpoints and regions enabled for OBS.", + "product_code":"obs", + "title":"Obtaining Endpoints", + "uri":"obs_20_0104.html", + "doc_type":"sdk-c-devg", + "p_code":"3", + "code":"5" + }, + { + "desc":"ObsClient functions as the C client for accessing OBS. It offers callers a series of APIs for interaction with OBS. These APIs are used for managing and operating resourc", + "product_code":"obs", + "title":"Initializing the SDK", + "uri":"obs_20_1805.html", + "doc_type":"sdk-c-devg", + "p_code":"3", + "code":"6" + }, + { + "desc":"When the function of SDK for C is called, the option parameter must be passed. You can use function init_obs_options to initialize the option configuration, including the", + "product_code":"obs", + "title":"Initializing option", + "uri":"obs_20_0105.html", + "doc_type":"sdk-c-devg", + "p_code":"3", + "code":"7" + }, + { + "desc":"A bucket is a global namespace of OBS and is a data container. It functions as a root directory of a file system and can store objects.Sample code:static void test_create", + "product_code":"obs", + "title":"Creating a Bucket", + "uri":"obs_20_0106.html", + "doc_type":"sdk-c-devg", + "p_code":"3", + "code":"8" + }, + { + "desc":"The data flow is saved to callback_data (see the callback_data definition in Uploading an Object - Streaming). Use the callback function put_object_data_callback defined ", + "product_code":"obs", + "title":"Uploading an Object", + "uri":"obs_20_0107.html", + "doc_type":"sdk-c-devg", + "p_code":"3", + "code":"9" + }, + { + "desc":"This example shows how to download an object from a bucket to a directory and save the object as test.Sample code:For more information, see Downloading an Object.", + "product_code":"obs", + "title":"Downloading an Object", + "uri":"obs_20_0108.html", + "doc_type":"sdk-c-devg", + "p_code":"3", + "code":"10" + }, + { + "desc":"This example shows how to list all objects in a bucket.Sample code:For more information, see Listing Objects in a Bucket.", + "product_code":"obs", + "title":"Listing Objects", + "uri":"obs_20_0109.html", + "doc_type":"sdk-c-devg", + "p_code":"3", + "code":"11" + }, + { + "desc":"This example shows how to delete an object from a bucket.Sample code:For more information, see Deleting an Object.", + "product_code":"obs", + "title":"Deleting an Object", + "uri":"obs_20_0110.html", + "doc_type":"sdk-c-devg", + "p_code":"3", + "code":"12" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Initialization", + "uri":"obs_20_0200.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"13" + }, + { + "desc":"To use OBS, you need a valid pair of AK and SK for signature authentication. For details, see Creating Access Keys.After obtaining the AK and SK, you can start initializa", + "product_code":"obs", + "title":"Configuring Access Keys", + "uri":"obs_20_0201.html", + "doc_type":"sdk-c-devg", + "p_code":"13", + "code":"14" + }, + { + "desc":"ObsClient functions as the C client for accessing OBS. It offers callers a series of APIs for interaction with OBS. These APIs are used for managing and operating resourc", + "product_code":"obs", + "title":"Initializing the SDK", + "uri":"obs_20_0202.html", + "doc_type":"sdk-c-devg", + "p_code":"13", + "code":"15" + }, + { + "desc":"When the function of SDK for C is called, the obs_options parameter must be passed. You can use function init_obs_options to initialize the obs_options configuration, inc", + "product_code":"obs", + "title":"Configuring option", + "uri":"obs_20_0203.html", + "doc_type":"sdk-c-devg", + "p_code":"13", + "code":"16" + }, + { + "desc":"The OBS C SDK log path is specified by the LogPath field in OBS.ini. By default, logs are stored in the logs directory at the same level as the lib directory of the C SDK", + "product_code":"obs", + "title":"Configuring SDK Logging", + "uri":"obs_20_0204.html", + "doc_type":"sdk-c-devg", + "p_code":"13", + "code":"17" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Bucket Management", + "uri":"obs_20_0300.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"18" + }, + { + "desc":"OBS buckets are containers for storing objects you upload to OBS. This API creates a bucket.When creating a bucket, you can also configure parameters such as the storage ", + "product_code":"obs", + "title":"Creating a Bucket", + "uri":"obs_20_0301.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"19" + }, + { + "desc":"OBS buckets are containers for storing objects you upload to OBS. This API returns a list of all buckets that meet the specified conditions in all regions of the current ", + "product_code":"obs", + "title":"Listing Buckets", + "uri":"obs_20_0302.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"20" + }, + { + "desc":"This API deletes an empty bucket. You can delete buckets you no longer use to free up space. The name of a deleted bucket can be reused for another bucket at least 30 min", + "product_code":"obs", + "title":"Deleting a Bucket", + "uri":"obs_20_0303.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"21" + }, + { + "desc":"This API checks whether a bucket exists. If an HTTP status code 200 is returned, the bucket exists. If 404 is returned, the bucket does not exist.To determine whether a b", + "product_code":"obs", + "title":"Checking Whether a Bucket Exists", + "uri":"obs_20_0304.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"22" + }, + { + "desc":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "product_code":"obs", + "title":"Configuring a Bucket ACL", + "uri":"obs_20_0305.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"23" + }, + { + "desc":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "product_code":"obs", + "title":"Obtaining a Bucket ACL", + "uri":"obs_20_0311.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"24" + }, + { + "desc":"This API returns the storage information on a bucket, including the number of objects and the space occupied by the objects in the bucket.OBS measures bucket storage stat", + "product_code":"obs", + "title":"Obtaining Bucket Storage Information", + "uri":"obs_20_0306.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"25" + }, + { + "desc":"A quota limits the maximum capacity allowed in a bucket. By default, there is no limit on the storage capacity of the entire OBS system or a single bucket, and any number", + "product_code":"obs", + "title":"Setting a Bucket Quota", + "uri":"obs_20_0307.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"26" + }, + { + "desc":"This API returns the storage quota (upper limit of the storage capacity) of a bucket. If the quota is 0, there is no upper limit on the bucket capacity.A bucket storage q", + "product_code":"obs", + "title":"Obtaining the Storage Quota of a Bucket", + "uri":"obs_20_0310.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"27" + }, + { + "desc":"This API configures a storage class for a bucket. If you do not specify a storage class when uploading or copying an object, or initiating a multipart upload, the object ", + "product_code":"obs", + "title":"Configuring a Storage Class for a Bucket", + "uri":"obs_20_0308.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"28" + }, + { + "desc":"This API returns the storage class of a bucket.To obtain a bucket's storage class, you must be the bucket owner or have the required permission (obs:bucket:GetBucketStora", + "product_code":"obs", + "title":"Obtaining the Storage Class of a Bucket", + "uri":"obs_20_0309.html", + "doc_type":"sdk-c-devg", + "p_code":"18", + "code":"29" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Object Upload", + "uri":"obs_20_0400.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"30" + }, + { + "desc":"This API uploads a local fileto OBS over the Internet. You can upload text, pictures, videos, or any other types of files.You can upload texts, images, videos, or any oth", + "product_code":"obs", + "title":"Uploading an Object - Streaming", + "uri":"obs_20_0401.html", + "doc_type":"sdk-c-devg", + "p_code":"30", + "code":"31" + }, + { + "desc":"This API uploads local filesto OBS over the Internet. You can upload text, pictures, videos, or any other types of files.This API uploads an object in text to a bucket.To", + "product_code":"obs", + "title":"Uploading an Object - File-Based", + "uri":"obs_20_0402.html", + "doc_type":"sdk-c-devg", + "p_code":"30", + "code":"32" + }, + { + "desc":"This API creates a folder in an existing bucket to manage data in OBS.OBS does not involve folders like in a file system. All elements in buckets are objects. To create a", + "product_code":"obs", + "title":"Creating a Folder", + "uri":"obs_20_0403.html", + "doc_type":"sdk-c-devg", + "p_code":"30", + "code":"33" + }, + { + "desc":"The resumable upload is an encapsulated and enhanced version of the multipart upload used for dealing with possible upload failures of large files when the network connec", + "product_code":"obs", + "title":"Uploading an Object - Resumable", + "uri":"obs_20_0407.html", + "doc_type":"sdk-c-devg", + "p_code":"30", + "code":"34" + }, + { + "desc":"This API uploads a file or folder to an existing OBS bucket. You can upload text, pictures, videos, or any other types of files.This API adds data to the end of a specifi", + "product_code":"obs", + "title":"Uploading an Object - Append", + "uri":"obs_20_0408.html", + "doc_type":"sdk-c-devg", + "p_code":"30", + "code":"35" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Object Download", + "uri":"obs_20_0500.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"36" + }, + { + "desc":"This API downloads an object as text from OBS to your local computer.To download an object, you must be the bucket owner or have the required permission (obs:object:GetOb", + "product_code":"obs", + "title":"Downloading an Object", + "uri":"obs_20_0501.html", + "doc_type":"sdk-c-devg", + "p_code":"36", + "code":"37" + }, + { + "desc":"This API returns the objects that meet one or more conditions. If there are no objects that meet the specified conditions, an error is returned.To download an object, you", + "product_code":"obs", + "title":"Downloading an Object - Conditional", + "uri":"obs_20_0502.html", + "doc_type":"sdk-c-devg", + "p_code":"36", + "code":"38" + }, + { + "desc":"To obtain the content of an object in the Cold storage class, you need to restore the object first and then you can download it. After an object is restored, a copy of th", + "product_code":"obs", + "title":"Restoring a Cold Object", + "uri":"obs_20_0503.html", + "doc_type":"sdk-c-devg", + "p_code":"36", + "code":"39" + }, + { + "desc":"Downloading large files often fails due to an unstable network or program breakdown. It is a waste of resources to download files again. Moreover, the restarted download ", + "product_code":"obs", + "title":"Downloading an Object - Resumable", + "uri":"obs_20_0504.html", + "doc_type":"sdk-c-devg", + "p_code":"36", + "code":"40" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Object Management", + "uri":"obs_20_0600.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"41" + }, + { + "desc":"This API sets properties for an object when uploading it. Object properties include the object length, MIME type, MD5 value (for verification), storage class, and custom ", + "product_code":"obs", + "title":"Setting Object Properties", + "uri":"obs_20_0404.html", + "doc_type":"sdk-c-devg", + "p_code":"41", + "code":"42" + }, + { + "desc":"Object metadata contains a set of name-value pairs that are used for describing and managing objects.Currently, only the system-defined metadata is supported. System-defi", + "product_code":"obs", + "title":"Obtaining Object Properties", + "uri":"obs_20_0601.html", + "doc_type":"sdk-c-devg", + "p_code":"41", + "code":"43" + }, + { + "desc":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "product_code":"obs", + "title":"Setting a Pre-defined ACL During Object Upload", + "uri":"obs_20_0602.html", + "doc_type":"sdk-c-devg", + "p_code":"41", + "code":"44" + }, + { + "desc":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "product_code":"obs", + "title":"Setting a Pre-defined ACL for an Object", + "uri":"obs_20_0314.html", + "doc_type":"sdk-c-devg", + "p_code":"41", + "code":"45" + }, + { + "desc":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "product_code":"obs", + "title":"Setting a User-defined Object ACL", + "uri":"obs_20_0315.html", + "doc_type":"sdk-c-devg", + "p_code":"41", + "code":"46" + }, + { + "desc":"Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over r", + "product_code":"obs", + "title":"Obtaining the ACL of an Object", + "uri":"obs_20_0316.html", + "doc_type":"sdk-c-devg", + "p_code":"41", + "code":"47" + }, + { + "desc":"This API lists some or all of the objects in a bucket. You can use parameters such as the prefix, number of returned objects, and start position to list objects that meet", + "product_code":"obs", + "title":"Listing Objects in a Bucket", + "uri":"obs_20_0603.html", + "doc_type":"sdk-c-devg", + "p_code":"41", + "code":"48" + }, + { + "desc":"This API deletes an object in the specified bucket to save space and costs.To delete an object, you must be the bucket owner or have the required permission (obs:object:D", + "product_code":"obs", + "title":"Deleting an Object", + "uri":"obs_20_0604.html", + "doc_type":"sdk-c-devg", + "p_code":"41", + "code":"49" + }, + { + "desc":"This API deletes objects in a batch from a specific bucket. Deleted objects cannot be restored.In a batch deletion, OBS concurrently deletes the specified objects and ret", + "product_code":"obs", + "title":"Batch Deleting Objects", + "uri":"obs_20_1813.html", + "doc_type":"sdk-c-devg", + "p_code":"41", + "code":"50" + }, + { + "desc":"This API copies an object stored in a specified bucket to another path by creating a copy of the object. You can copy an object of up to 5 GB in a single operation.To cop", + "product_code":"obs", + "title":"Copying an Object", + "uri":"obs_20_0605.html", + "doc_type":"sdk-c-devg", + "p_code":"41", + "code":"51" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Multipart Upload APIs", + "uri":"obs_20_1812.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"52" + }, + { + "desc":"You can upload a large file using multipart upload. Multipart upload is applicable to many scenarios. Below are some examples.A file to be uploaded is larger than 100 MB.", + "product_code":"obs", + "title":"Multipart Upload APIs", + "uri":"obs_20_1811.html", + "doc_type":"sdk-c-devg", + "p_code":"52", + "code":"53" + }, + { + "desc":"This API initiates a multipart upload and returns a globally unique upload ID. You can use this upload ID in your subsequent requests for uploading, assembling, and listi", + "product_code":"obs", + "title":"Initiating a Multipart Upload", + "uri":"obs_20_0405.html", + "doc_type":"sdk-c-devg", + "p_code":"52", + "code":"54" + }, + { + "desc":"After a multipart upload is initiated, this API uploads a part to a specified bucket. In the upload request, the multipart upload ID must be included. The last part uploa", + "product_code":"obs", + "title":"Uploading a Part", + "uri":"obs_20_1810.html", + "doc_type":"sdk-c-devg", + "p_code":"52", + "code":"55" + }, + { + "desc":"This API assembles the uploaded parts to complete the multipart upload. Before performing this operation, you cannot download the uploaded data. When assembling parts, yo", + "product_code":"obs", + "title":"Assembling Parts", + "uri":"obs_20_1809.html", + "doc_type":"sdk-c-devg", + "p_code":"52", + "code":"56" + }, + { + "desc":"This API lists multipart uploads that have been initiated but not completed or cancelled.For each listing request, OBS can list a maximum of 1,000 multipart upload tasks.", + "product_code":"obs", + "title":"Listing Multipart Uploads", + "uri":"obs_20_1808.html", + "doc_type":"sdk-c-devg", + "p_code":"52", + "code":"57" + }, + { + "desc":"This API lists the uploaded parts in a specified bucket. This request must contain the multipart upload ID.You can list the uploaded parts of a specified multipart upload", + "product_code":"obs", + "title":"Listing Uploaded Parts", + "uri":"obs_20_1807.html", + "doc_type":"sdk-c-devg", + "p_code":"52", + "code":"58" + }, + { + "desc":"This API uploads a part for a specified multipart upload by copying data to a specified bucket.After initiating a multipart upload task, you can add parts for this task b", + "product_code":"obs", + "title":"Copying a Part", + "uri":"obs_20_0406.html", + "doc_type":"sdk-c-devg", + "p_code":"52", + "code":"59" + }, + { + "desc":"This API aborts a multipart upload, which is specified by its ID.After a multipart upload is aborted, its upload ID cannot be used to upload any part. And the space occup", + "product_code":"obs", + "title":"Aborting a Multipart Upload", + "uri":"obs_20_1806.html", + "doc_type":"sdk-c-devg", + "p_code":"52", + "code":"60" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Versioning", + "uri":"obs_20_0800.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"61" + }, + { + "desc":"You can enable versioning to automatically maintain previous versions of an object. When versioning is enabled, you can access earlier versions of an object to recover yo", + "product_code":"obs", + "title":"Configuring Versioning for a Bucket", + "uri":"obs_20_0802.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"62" + }, + { + "desc":"You can enable versioning to automatically maintain previous versions of an object. When versioning is enabled, you can access earlier versions of an object to recover yo", + "product_code":"obs", + "title":"Obtaining the Versioning Status of a Bucket", + "uri":"obs_20_0803.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"63" + }, + { + "desc":"You can call get_object to obtain an object version by specifying the version ID (obs_object_info.version_id).If the version ID is not specified, the object of the latest", + "product_code":"obs", + "title":"Obtaining an Object Version", + "uri":"obs_20_0804.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"64" + }, + { + "desc":"This API copies an object version in a specified bucket. You can create a copy up to 5 GB for a versioned object in a single operation.To copy a versioned object, you mus", + "product_code":"obs", + "title":"Copying an Object Version", + "uri":"obs_20_0805.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"65" + }, + { + "desc":"To obtain the content of an object version in the Cold storage class, you need to restore the object version first and then you can download it. After an object version i", + "product_code":"obs", + "title":"Restoring a Specific Cold Object Version", + "uri":"obs_20_0806.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"66" + }, + { + "desc":"This API lists some or all of the object versions in a bucket. You can use parameters such as the prefix, number of returned object versions, and start position to list t", + "product_code":"obs", + "title":"Listing Object Versions in a Bucket", + "uri":"obs_20_0807.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"67" + }, + { + "desc":"OBS allows you to control access to versioned objects. By default, only the versioned object creator has the read and write permissions on the object. You can set access ", + "product_code":"obs", + "title":"Setting a Pre-defined ACL for an Object Version", + "uri":"obs_20_0317.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"68" + }, + { + "desc":"OBS allows you to control access to versioned objects. By default, only the versioned object creator has the read and write permissions on the object. You can set access ", + "product_code":"obs", + "title":"Setting an Object Version ACL Directly", + "uri":"obs_20_0318.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"69" + }, + { + "desc":"OBS provides access control over buckets. You can use an access policy to define whether a user can perform certain operations on a specific bucket. OBS access control ca", + "product_code":"obs", + "title":"Obtaining the ACL of an Object Version", + "uri":"obs_20_0319.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"70" + }, + { + "desc":"This API deletes an object version in the specified bucket to save space and costs.To delete an object version, you must be the bucket owner or have the required permissi", + "product_code":"obs", + "title":"Deleting an Object Version", + "uri":"obs_20_0809.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"71" + }, + { + "desc":"This API deletes object versions in a batch in the specified bucket to save space and costs.To delete object versions, you must be the bucket owner or have the required p", + "product_code":"obs", + "title":"Batch Deleting Object Versions", + "uri":"obs_23_1713.html", + "doc_type":"sdk-c-devg", + "p_code":"61", + "code":"72" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Lifecycle Management", + "uri":"obs_20_0900.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"73" + }, + { + "desc":"OBS allows you to set lifecycle rules for buckets to automatically transition the storage class of an object or delete expired objects, to effectively use storage feature", + "product_code":"obs", + "title":"Overview", + "uri":"obs_20_0901.html", + "doc_type":"sdk-c-devg", + "p_code":"73", + "code":"74" + }, + { + "desc":"You can configure lifecycle rules to periodically delete objects or transition objects between storage classes.This API configures lifecycle rules for a bucket.There is n", + "product_code":"obs", + "title":"Configuring Lifecycle Rules for a Bucket", + "uri":"obs_20_0902.html", + "doc_type":"sdk-c-devg", + "p_code":"73", + "code":"75" + }, + { + "desc":"You can configure lifecycle rules to periodically delete objects or transition objects between storage classes.This API returns the lifecycle rules of a bucket.To obtain ", + "product_code":"obs", + "title":"Obtaining the Lifecycle Rules of a Bucket", + "uri":"obs_20_0903.html", + "doc_type":"sdk-c-devg", + "p_code":"73", + "code":"76" + }, + { + "desc":"You can configure lifecycle rules to periodically delete objects or transition objects between storage classes.This API deletes the lifecycle rules of a bucket.To delete ", + "product_code":"obs", + "title":"Deleting the Lifecycle Rules of a Bucket", + "uri":"obs_20_0904.html", + "doc_type":"sdk-c-devg", + "p_code":"73", + "code":"77" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Cross-Origin Resource Sharing", + "uri":"obs_20_1000.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"78" + }, + { + "desc":"Cross-origin resource sharing (CORS) is a mechanism defined by the World Wide Web Consortium (W3C) that allows a web application program in one domain to access resources", + "product_code":"obs", + "title":"Configuring CORS for a Bucket", + "uri":"obs_20_1002.html", + "doc_type":"sdk-c-devg", + "p_code":"78", + "code":"79" + }, + { + "desc":"Cross-origin resource sharing (CORS) is a mechanism defined by the World Wide Web Consortium (W3C) that allows a web application program in one domain to access resources", + "product_code":"obs", + "title":"Obtaining the CORS Configuration of a Bucket", + "uri":"obs_20_1003.html", + "doc_type":"sdk-c-devg", + "p_code":"78", + "code":"80" + }, + { + "desc":"Cross-origin resource sharing (CORS) is a mechanism defined by the World Wide Web Consortium (W3C) that allows a web application program in one domain to access resources", + "product_code":"obs", + "title":"Deleting the CORS Configuration of a Bucket", + "uri":"obs_20_1004.html", + "doc_type":"sdk-c-devg", + "p_code":"78", + "code":"81" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Logging", + "uri":"obs_20_1100.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"82" + }, + { + "desc":"This API enables logging for a bucket (source) and configures another bucket (target) to store the log files. When a bucket is created, logging is not enabled by default.", + "product_code":"obs", + "title":"Configuring Logging for a Bucket", + "uri":"obs_20_1102.html", + "doc_type":"sdk-c-devg", + "p_code":"82", + "code":"83" + }, + { + "desc":"This API returns the logging configuration of a bucket.To obtain the logging configuration of a bucket, you must be the bucket owner or have the required permission (obs:", + "product_code":"obs", + "title":"Obtaining the Logging Configuration of a Bucket", + "uri":"obs_20_1103.html", + "doc_type":"sdk-c-devg", + "p_code":"82", + "code":"84" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Static Website Hosting", + "uri":"obs_20_1200.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"85" + }, + { + "desc":"You can perform the following to implement website file hosting:This example implements website file hosting.#include \"eSDKOBS.h\"\n#include \n#include ", + "product_code":"obs", + "title":"Hosting Website Files in a Bucket", + "uri":"obs_20_1202.html", + "doc_type":"sdk-c-devg", + "p_code":"85", + "code":"86" + }, + { + "desc":"You can host static website resources such as HTML web pages, flash files, or audio and video files in an OBS bucket, so that you can provide these hosted resources using", + "product_code":"obs", + "title":"Configuring Static Website Hosting for a Bucket", + "uri":"obs_20_1203.html", + "doc_type":"sdk-c-devg", + "p_code":"85", + "code":"87" + }, + { + "desc":"You can host static website resources such as HTML web pages, flash files, or audio and video files in an OBS bucket, so that you can provide these hosted resources using", + "product_code":"obs", + "title":"Obtaining the Static Website Hosting Configuration of a Bucket", + "uri":"obs_20_1204.html", + "doc_type":"sdk-c-devg", + "p_code":"85", + "code":"88" + }, + { + "desc":"You can host static website resources such as HTML web pages, flash files, or audio and video files in an OBS bucket, so that you can provide these hosted resources using", + "product_code":"obs", + "title":"Deleting the Static Website Hosting Configuration of a Bucket", + "uri":"obs_20_1205.html", + "doc_type":"sdk-c-devg", + "p_code":"85", + "code":"89" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Tagging", + "uri":"obs_20_1300.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"90" + }, + { + "desc":"If you add tags to a bucket, SDRs generated for the requests sent to this bucket will include these tags, so you can use the tags to classify SDRs for detailed cost analy", + "product_code":"obs", + "title":"Adding Bucket Tags", + "uri":"obs_20_1302.html", + "doc_type":"sdk-c-devg", + "p_code":"90", + "code":"91" + }, + { + "desc":"If you add tags to a bucket, SDRs generated for the requests sent to this bucket will include these tags, so you can use the tags to classify SDRs for detailed cost analy", + "product_code":"obs", + "title":"Obtaining Bucket Tags", + "uri":"obs_20_1303.html", + "doc_type":"sdk-c-devg", + "p_code":"90", + "code":"92" + }, + { + "desc":"If you add tags to a bucket, SDRs generated for the requests sent to this bucket will include these tags, so you can use the tags to classify SDRs for detailed cost analy", + "product_code":"obs", + "title":"Deleting Bucket Tags", + "uri":"obs_20_1304.html", + "doc_type":"sdk-c-devg", + "p_code":"90", + "code":"93" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Other APIs", + "uri":"obs_20_1500.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"94" + }, + { + "desc":"This API configures server-side encryption for objects, so that they will be encrypted or decrypted when you upload them to or download them from a bucket.The encryption ", + "product_code":"obs", + "title":"Server-Side Encryption", + "uri":"obs_20_1501.html", + "doc_type":"sdk-c-devg", + "p_code":"94", + "code":"95" + }, + { + "desc":"This API creates a temporary URL to grant temporary permissions for operating OBS. This URL contains the information about the AK and SK, request method, and related para", + "product_code":"obs", + "title":"Using a Temporary URL for Authorized Access", + "uri":"obs_20_0700.html", + "doc_type":"sdk-c-devg", + "p_code":"94", + "code":"96" + }, + { + "desc":"To access OBS through a user-defined domain name, you need to first configure a domain name on the Console.When using a user-defined domain name to access OBS, you can ca", + "product_code":"obs", + "title":"Using a User-Defined Domain Name to Access OBS", + "uri":"en-us_topic_0000001833016268.html", + "doc_type":"sdk-c-devg", + "p_code":"94", + "code":"97" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Troubleshooting", + "uri":"obs_20_1600.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"98" + }, + { + "desc":"If the OBS server encounters an error when processing a request, a response containing the error code and error description is returned. The following table lists details", + "product_code":"obs", + "title":"OBS Server-Side Error Codes", + "uri":"obs_20_1601.html", + "doc_type":"sdk-c-devg", + "p_code":"98", + "code":"99" + }, + { + "desc":"SDK errors include the errors returned during the check of function parameters and those returned by the OBS server.SDK error handling information:obs_status: Error codeo", + "product_code":"obs", + "title":"SDK Error Handling", + "uri":"obs_20_1602.html", + "doc_type":"sdk-c-devg", + "p_code":"98", + "code":"100" + }, + { + "desc":"The OBS C SDK log path is specified by the LogPath field in OBS.ini. By default, logs are stored in the logs directory at the same level as the lib directory of the C SDK", + "product_code":"obs", + "title":"Log Analysis", + "uri":"obs_20_1603.html", + "doc_type":"sdk-c-devg", + "p_code":"98", + "code":"101" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"FAQs", + "uri":"obs_20_1800.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"102" + }, + { + "desc":"When the proxy is configured in a Windows SDK demo, the program reports the following error and the proxy configuration fails.Root cause: Due to asynchronous updates, the", + "product_code":"obs", + "title":"Invalid Proxy Settings", + "uri":"obs_20_1804.html", + "doc_type":"sdk-c-devg", + "p_code":"102", + "code":"103" + }, + { + "desc":"When calling APIs, you may need to specify the account ID (DomainID) and user ID (UserID) in some requests. You need to obtain them from the console in advance. To obtain", + "product_code":"obs", + "title":"How Do I Get My Account ID and User ID?", + "uri":"obs_23_1712.html", + "doc_type":"sdk-c-devg", + "p_code":"102", + "code":"104" + }, + { + "desc":"HUAWEI CLOUD Help Center presents technical documents to help you quickly get started with HUAWEI CLOUD services. The technical documents include Service Overview, Price Details, Purchase Guide, User Guide, API Reference, Best Practices, FAQs, and Videos.", + "product_code":"obs", + "title":"Change History", + "uri":"obs_20_1702.html", + "doc_type":"sdk-c-devg", + "p_code":"", + "code":"105" + } +] \ No newline at end of file diff --git a/docs/obs_3rd_party/c_sdk/PARAMETERS.txt b/docs/obs_3rd_party/c_sdk/PARAMETERS.txt new file mode 100644 index 000000000..6da8d5f07 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/PARAMETERS.txt @@ -0,0 +1,3 @@ +version="" +language="en-us" +type="" \ No newline at end of file diff --git a/docs/obs_3rd_party/c_sdk/en-us_image_0000002056116746.png b/docs/obs_3rd_party/c_sdk/en-us_image_0000002056116746.png new file mode 100644 index 000000000..201283997 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/en-us_image_0000002056116746.png differ diff --git a/docs/obs_3rd_party/c_sdk/en-us_image_0000002092274033.png b/docs/obs_3rd_party/c_sdk/en-us_image_0000002092274033.png new file mode 100644 index 000000000..a617a7a31 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/en-us_image_0000002092274033.png differ diff --git a/docs/obs_3rd_party/c_sdk/en-us_image_0000002092648565.png b/docs/obs_3rd_party/c_sdk/en-us_image_0000002092648565.png new file mode 100644 index 000000000..7e1348901 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/en-us_image_0000002092648565.png differ diff --git a/docs/obs_3rd_party/c_sdk/en-us_topic_0000001833016268.html b/docs/obs_3rd_party/c_sdk/en-us_topic_0000001833016268.html new file mode 100644 index 000000000..980ccecb7 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/en-us_topic_0000001833016268.html @@ -0,0 +1,724 @@ + + +

Using a User-Defined Domain Name to Access OBS

+

To access OBS through a user-defined domain name, you need to first configure a domain name on the Console.

+

When using a user-defined domain name to access OBS, you can call APIs as you normally do, except that you need to configure option as shown below:

+
option.bucket_options.useCname = true;
+option.bucket_options.host_name = "yourCustomDomain";
+

Code Examples: Uploading an Object Using a Custom Domain Name

This example uploads an object using a custom domain name:
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data);
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct put_file_object_callback_data
+{
+    FILE *infile;
+    uint64_t content_length;
+    obs_status ret_status;
+} put_file_object_callback_data;
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data);
+int main()
+{
+    // The following code shows how to use the put_object function to upload a local file when a custom domain name is used:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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");
+    char * bucketName = "";
+    options.bucket_options.bucket_name = bucketName;
+    // Set the custom domain name.
+    options.bucket_options.useCname = true;
+    options.bucket_options.host_name = "example.obs.test.cname.com";
+    // Initialize the properties of the object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Name of the object to be uploaded
+    char *key = "example_get_file_test";
+    // Uploaded file
+    char file_name[256] = "./example_local_file_test.txt";
+    uint64_t content_length = 0;
+    // Initialize the structure for storing the uploaded data.
+    put_file_object_callback_data data;
+    memset(&data, 0, sizeof(put_file_object_callback_data));
+    // Open the file and obtain the file length.
+    content_length = open_file_and_get_length(file_name, &data);
+    // Set the callback function.
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_file_complete_callback },
+        &put_file_data_callback
+    };
+    put_object(&options, key, content_length, &put_properties, 0, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from file successfully. \n");
+    }
+    else
+    {
+        printf("put object failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    if (data.infile != NULL) {
+        fclose(data.infile);
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data)
+{
+    put_file_object_callback_data *data =
+        (put_file_object_callback_data *)callback_data;
+    int ret = 0;
+    if (data->content_length) {
+        int toRead = ((data->content_length > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->content_length);
+        ret = fread(buffer, 1, toRead, data->infile);
+    }
+    uint64_t originalContentLength = data->content_length;
+    data->content_length -= ret;
+    if (data->content_length) {
+        printf("%llu bytes remaining ", (unsigned long long)data->content_length);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->content_length) * 100) / originalContentLength));
+    }
+    return ret;
+}
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    put_file_object_callback_data *data = (put_file_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data)
+{
+    uint64_t content_length = 0;
+    const char *body = 0;
+    if (!content_length)
+    {
+        struct stat statbuf;
+        if (stat(localfile, &statbuf) == -1)
+        {
+            fprintf(stderr, "\nERROR: Failed to stat file %s: ",
+                localfile);
+            return 0;
+        }
+        content_length = statbuf.st_size;
+    }
+    if (!(data->infile = fopen(localfile, "rb")))
+    {
+        fprintf(stderr, "\nERROR: Failed to open input file %s: ",
+            localfile);
+        return 0;
+    }
+    data->content_length = content_length;
+    return content_length;
+}
+
+
+
+
+

Code Examples: Downloading an Object Using a Custom Domain Name

This example downloads an object using a custom domain name.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data);
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct get_object_callback_data
+{
+    FILE *outfile;
+    obs_status ret_status;
+}get_object_callback_data;
+FILE * write_to_file(char *localfile);
+int main()
+{
+    // The following code shows how to use the get_object function to download an object to a local file when a custom domain name is used:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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");
+    char * bucketName = "";
+    options.bucket_options.bucket_name = bucketName;
+    // Set a custom domain name.
+    options.bucket_options.useCname = true;
+    options.bucket_options.host_name = "example.obs.test.cname.com";
+    // Set the name of the local file to which the object is downloaded.
+    char *file_name = "./example_get_file_test";
+    obs_object_info object_info;
+    // Set the object to be downloaded.
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "example_get_file_test";
+    object_info.version_id = NULL;
+    //Set the structure for storing the downloaded object data based on service requirements.
+    get_object_callback_data data;
+    data.ret_status = OBS_STATUS_BUTT;
+    data.outfile = write_to_file(file_name);
+    // Define parameters for range-based download.
+    obs_get_conditions getcondition;
+    memset(&getcondition, 0, sizeof(obs_get_conditions));
+    init_get_properties(&getcondition);
+    // Download start position. The default value is 0, indicating that the download starts from byte 0.
+    getcondition.start_byte = 0;
+    // Download length. The default value is 0, indicating that the object is downloaded until the end.
+    // getcondition.byte_count = 0;
+    // Define the download callback function.
+    obs_get_object_handler get_object_handler =
+    {
+        { &response_properties_callback,
+          &get_object_complete_callback},
+        &get_object_data_callback
+    };
+    get_object(&options, &object_info, &getcondition, 0, &get_object_handler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("get object successfully. \n");
+    }
+    else
+    {
+        printf("get object failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    fclose(data.outfile);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    size_t wrote = fwrite(buffer, 1, buffer_size, data->outfile);
+    return ((wrote < (size_t)buffer_size) ?
+        OBS_STATUS_AbortedByCallback : OBS_STATUS_OK);
+}
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+FILE * write_to_file(char *localfile)
+{
+    FILE *outfile = 0;
+    if (localfile) {
+        struct stat buf;
+        if (stat(localfile, &buf) == -1) {
+            outfile = fopen(localfile, "wb");
+        }
+        else {
+            outfile = fopen(localfile, "a");
+        }
+        if (!outfile) {
+            fprintf(stderr, "\nERROR: Failed to open output file %s: ",
+                localfile);
+            return outfile;
+        }
+    } else {
+        fprintf(stderr, "\nERROR: Failed to open output file, it's NULL, write object to stdout.",
+            localfile);
+        outfile = stdout;
+    }
+    return outfile;
+}
+
+
+
+
+
+
+
+
Parent topic: Other APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0004.html b/docs/obs_3rd_party/c_sdk/obs_20_0004.html new file mode 100644 index 000000000..04501fac1 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0004.html @@ -0,0 +1,22 @@ + + +

Downloading and Installing the SDK

+

This section provides the download and compilation methods for the OBS SDK for C.

+

SDK Download

  • Latest version of OBS C SDK source code: Click here to download.
+
+

SDK Compilation

You can compile the SDK based on the platform you are using. Before that, you must obtain the SDK source code.

+
  • In Linux:
+

Go to the source/eSDK_OBS_API/eSDK_OBS_API_C++/ directory and run the following script:

+

export SPDLOG_VERSION=spdlog-1.12.0

+

#On an x86 server, run the following command:

+

bash build.sh sdk

+

#On an Arm server, run the following command:

+

bash build_aarch.sh sdk

+

For details about the parameters, see the comments in the scripts. A sdk.tgz demo package that contains the content shown below is generated.

+

+
  • In Windows:
+

Use Visual Studio to open the sln file in source/eSDK_OBS_API/eSDK_OBS_API_C++/sln/vc100/ and generate the obs project. Then, securec.lib, securec.dll, libeSDKOBS.lib, and libeSDKOBS.dll are generated in the output directory (which can be queried in the project properties).

+
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0100.html b/docs/obs_3rd_party/c_sdk/obs_20_0100.html new file mode 100644 index 000000000..a54a52a28 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0100.html @@ -0,0 +1,27 @@ + + +

Getting Started

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0101.html b/docs/obs_3rd_party/c_sdk/obs_20_0101.html new file mode 100644 index 000000000..b4aaf5770 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0101.html @@ -0,0 +1,42 @@ + + +

Before You Start

+

This section describes the version compatibility and important notes about the C SDK of Object Storage Service (OBS).

+

Compatibility

  • 3.*.* is compatible with 3.0.0.
  • 3.*.* is incompatible with 2.*.*.
  • 3.*.* is incompatible with 1.*.*.
  • Arm compilation environment:
    NAME="EulerOS"
+VERSION="2.0 (SP8)"
+ID="euleros"
+ID_LIKE="rhel fedora centos"
+VERSION_ID="2.0"
+PRETTY_NAME="EulerOS 2.0 (SP8)"
+ANSI_COLOR="0;31"
    +

    Kernel version:

    +
    4.19.36-vhulk1905.1.0.h276.eulerosv2r8.aarch64
    +

    gcc/g++ version:

    +
    gcc (GCC) 10.3.0/g++ (GCC) 10.3.0
    +
  • Linux compilation environment:
    NAME="CentOS Linux"
+VERSION="7 (Core)"
+ID="centos"
+ID_LIKE="rhel fedora"
+VERSION_ID="7"
+PRETTY_NAME="CentOS Linux 7 (Core)"
+ANSI_COLOR="0;31"
+CPE_NAME="cpe:/o:centos:centos:7"
+HOME_URL="https://www.centos.org/"
+BUG_REPORT_URL="https://bugs.centos.org/"
+
+CENTOS_MANTISBT_PROJECT="CentOS-7"
+CENTOS_MANTISBT_PROJECT_VERSION="7"
+REDHAT_SUPPORT_PRODUCT="centos"
+REDHAT_SUPPORT_PRODUCT_VERSION="7"
    +

    Kernel version:

    +
    3.10.0-957.5.1.el7.x86_64
    +

    gcc/g++ version:

    +
    gcc (GCC) 10.3.0/g++ (GCC) 10.3.0
    +

    The required environments for compiling the SDK binary package are listed above. Compatibility is not guaranteed for other kernels and operating systems. If you need to use other operating systems or kernel versions, use the open-source code to compile on your own.

    +
    +
+
+

Important Notes

  • Ensure that you are familiar with OBS basic concepts mentioned in the Help Center, such as bucket, object, region, and AK and SK.
  • After an API call is complete using an instance of ObsClient, view whether an exception is thrown. If no, the API call was successful. If yes, the operation failed. You can check the error information from SDK Error Handling.
  • Some features are available only in some regions. If an API call returns the 405 HTTP status code, check whether the region supports this feature.
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0103.html b/docs/obs_3rd_party/c_sdk/obs_20_0103.html new file mode 100644 index 000000000..9d757ba02 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0103.html @@ -0,0 +1,23 @@ + + +

Creating Access Keys

+

OBS uses the AK and SK in a user account for signature verification to make sure that only authorized accounts can access specified OBS resources. Detailed explanations about AK and SK are as follows:

+
  • An access key ID (AK) defines a user who accesses the OBS system. An AK belongs to only one user, but one user can have multiple AKs. The OBS system recognizes the users who access the system by their access key IDs.
  • A secret access key (SK) is the key used by users to access OBS. It is the authentication information generated based on the AK and the request header. An SK matches an AK, and they group into a pair.
+

Access keys are classified into permanent access keys (AK/SK) and temporary access keys (AK/SK and security token). Each user can create at most two permanent access keys. Temporary access keys must be used within a given validity period. Once expired, they must be requested again. For security purposes, you are advised to use temporary access keys to access OBS. If you want to use permanent access keys, periodically update them. The following describes how to obtain two types of access keys.

+

Permanent Access Keys

  1. Log in to OBS Console.
  2. In the upper right corner of the page, hover the cursor over the username and choose My Credentials.
  3. On the My Credentials page, select Access Keys in the navigation pane on the left.
  4. On the Access Keys page, click Create Access Key.
  5. In the Create Access Key dialog box that is displayed, enter the password and verification code.
    • If you have not bound an email address or mobile number, enter only the password.
    • If you have bound an email address and a mobile number, you can select the verification by either email or mobile phone.
    +
    +
  6. Click OK.
  7. In the Download Access Key dialog box that is displayed, click OK to save the access keys to your browser's default download path.
  8. Open the downloaded credentials.csv file to obtain the access keys (AK and SK).
    • A user can create a maximum of two valid access keys.
    • Keep the access key properly. If you click Cancel in the dialog box, the access keys will not be downloaded, and cannot be obtained later. You can re-create access keys if you need to use them.
    +
    +
+
+

Temporary Access Keys

Temporary access keys are issued by the system and are only valid for 15 minutes to 24 hours. Once expired, they must be requested again. They follow the principle of least privilege. When a temporary AK/SK pair is used for authentication, a security token must be used at the same time.

+

For details about how to obtain temporary access keys, see Obtaining a Temporary AK/SK.

+

For details about how to use temporary access keys, see Initializing option.

+
+
+
+
+
Parent topic: Getting Started
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0104.html b/docs/obs_3rd_party/c_sdk/obs_20_0104.html new file mode 100644 index 000000000..0fac48850 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0104.html @@ -0,0 +1,11 @@ + + +

Obtaining Endpoints

+
  • You can click here to view the endpoints and regions enabled for OBS.
+
+
+
+
Parent topic: Getting Started
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0105.html b/docs/obs_3rd_party/c_sdk/obs_20_0105.html new file mode 100644 index 000000000..ce6051e92 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0105.html @@ -0,0 +1,35 @@ + + +

Initializing option

+

When the function of SDK for C is called, the option parameter must be passed. You can use function init_obs_options to initialize the option configuration, including the AK, SK, endpoint, bucket, timeout, and temporary authentication.

+
  • Sample code for creating and initializing option using permanent access keys (AK/SK):
    // Create and initialize option.
+obs_options option;
+init_obs_options(&option);
+option.bucket_options.host_name = "<your-endpoint>";
+option.bucket_options.bucket_name = "<Your bucketname>";
+
+// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
+// Obtain an AK/SK pair on the management console.
+option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
+option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    +
  • Sample code for creating and initializing option using temporary access keys (AK/SK and SecurityToken):
    // Create and initialize option.
+obs_options option;
+init_obs_options(&option);
+option.bucket_options.host_name = "<your-endpoint>";
+option.bucket_options.bucket_name = "<Your bucketname>";
+
+// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
+// Obtain an AK/SK pair on the management console.
+option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
+option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
+option.bucket_options.token = getenv("SecurityToken");
    +
    • OBS is a global service. When obtaining temporary credentials, set the token scope to domain to make the token applicable to all projects and regions within an account.
    +
    +
+
+
+
+
Parent topic: Getting Started
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0106.html b/docs/obs_3rd_party/c_sdk/obs_20_0106.html new file mode 100644 index 000000000..3d1b9b921 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0106.html @@ -0,0 +1,47 @@ + + +

Creating a Bucket

+

A bucket is a global namespace of OBS and is a data container. It functions as a root directory of a file system and can store objects.

+
Sample code:
static void test_create_bucket(obs_canned_acl canned_acl, char *bucket_name)
+{
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Create and initialize option.
+    obs_options option;
+    init_obs_options(&option);
+    option.bucket_options.host_name = "<your-endpoint>";
+    option.bucket_options.bucket_name = "<Your bucketname>";
+// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
+    // Obtain an AK/SK pair on the management console.
+    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
+    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
+
+
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    { 
+        0, &response_complete_callback
+    };
+
+    // Create a bucket. For details about pre-defined ACLs, see the section "Configuring a Bucket ACL (SDK for C)".
+    create_bucket(&option, "<bucket ACL>", NULL, &response_handler, &ret_status);
+    if (ret_status == OBS_STATUS_OK) {
+        printf("create bucket successfully. \n");
+    }
+    else
+    {
+        printf("create bucket failed(%s).\n", obs_get_status_name(ret_status));
+    }
+}
+
+

Bucket names are globally unique. Ensure that the bucket you create is named differently from any other bucket. A bucket name must comply with the following rules:

+
  • Contains 3 to 63 characters, starts with a digit or letter, and supports only lowercase letters, digits, hyphens (-), and periods (.)
  • Cannot be an IP address.
  • Cannot start or end with a hyphen (-) or period (.).
  • Cannot contain two consecutive periods (..), for example, my..bucket.
  • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you create buckets of the same name, no error will be reported and the bucket properties comply with those set in the first creation request.
+

The example here sets the bucket's ACL to private read and write, storage class to Standard, and location to the default region for the global domain name.

+

For more information, see Creating a Bucket.

+
+
+
+
+
Parent topic: Getting Started
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0107.html b/docs/obs_3rd_party/c_sdk/obs_20_0107.html new file mode 100644 index 000000000..cf6b7d875 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0107.html @@ -0,0 +1,57 @@ + + +

Uploading an Object

+

The data flow is saved to callback_data (see the callback_data definition in Uploading an Object - Streaming). Use the callback function put_object_data_callback defined in obs_put_object_handler to copy the content of the uploaded object to buffer, a character pointer parameter of the callback function.

+

For more information, see Uploading an Object - Streaming.

+

Sample code:

+
static void test_put_object_from_buffer()
+{
+     // Buffer to be uploaded
+    char *buffer = "abcdefg";
+     // Length of the buffer to be uploaded
+    int buffer_size = strlen(buffer);
+     // Name of an object to be uploaded
+    char *key = "put_buffer_test";
+
+    // Initialize option.
+    obs_options option;
+    init_obs_options(&option);
+    option.bucket_options.host_name = "<your-endpoint>";
+    option.bucket_options.bucket_name = "<Your bucket name>";
+// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
+    // Obtain an AK/SK pair on the management console.
+    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
+    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
+
+    // Initialize the properties of an object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Customize the structure for storing uploaded data.
+    put_buffer_object_callback_data data;
+    memset(&data, 0, sizeof(put_buffer_object_callback_data));
+    // Assign the buffer value to the structure.
+    data.put_buffer = buffer;
+    // Set buffersize.
+    data.buffer_size = buffer_size;
+    // Set the callback function. The corresponding callback function needs to be implemented.
+    obs_put_object_handler putobjectHandler =
+    { 
+        { &response_properties_callback, &put_buffer_complete_callback },
+          &put_buffer_data_callback
+    };
+    put_object(&option, key, buffer_size, &put_properties,0,&putobjectHandler,&data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from buffer successfully. \n");
+    }
+    else
+    {
+        printf("put object from buffer failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+}
+
+
+
+
Parent topic: Getting Started
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0108.html b/docs/obs_3rd_party/c_sdk/obs_20_0108.html new file mode 100644 index 000000000..9fda4dbfa --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0108.html @@ -0,0 +1,55 @@ + + +

Downloading an Object

+

This example shows how to download an object from a bucket to a directory and save the object as test.

+

Sample code:

+
static void test_get_object()
+{
+    char *file_name = "./test";
+    obs_object_info object_info;
+    // Initialize option.
+    obs_options option;
+    init_obs_options(&option);
+    option.bucket_options.host_name = "<your-endpoint>";
+    option.bucket_options.bucket_name = "<Your bucketname>";
+// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
+    // Obtain an AK/SK pair on the management console.
+    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
+    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
+    // Set the object to be downloaded.
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "<object key>";
+    object_info.version_id = "<object version ID>";
+    // Customize the structure for storing downloaded object data based on service requirements.
+    get_object_callback_data data;
+    data.ret_status = OBS_STATUS_BUTT;
+    data.outfile = write_to_file(file_name);
+    // Define range download parameters.
+    obs_get_conditions getcondition;
+    memset(&getcondition, 0, sizeof(obs_get_conditions));
+    init_get_properties(&getcondition);
+    // Customize callback function for download.
+    obs_get_object_handler get_object_handler =
+    { 
+        { &response_properties_callback, &get_object_complete_callback},
+        &get_object_data_callback
+    };
+    get_object(&option, &object_info, &getcondition, 0, &get_object_handler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("get object successfully. \n");
+    }
+    else
+    {
+        printf("get object failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    fclose(data.outfile);
+}
+

For more information, see Downloading an Object.

+
+
+
+
+
Parent topic: Getting Started
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0109.html b/docs/obs_3rd_party/c_sdk/obs_20_0109.html new file mode 100644 index 000000000..9ad100f92 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0109.html @@ -0,0 +1,48 @@ + + +

Listing Objects

+

This example shows how to list all objects in a bucket.

+

Sample code:

+
static void test_list_bucket_objects()
+{
+    // Create and initialize option.
+    obs_options option;
+    init_obs_options(&option);
+    option.bucket_options.host_name = "<your-endpoint>";
+    option.bucket_options.bucket_name = "<Your bucketname>";
+
+// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
+    // Obtain an AK/SK pair on the management console.
+    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
+    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
+
+    // Set response callback function.
+    obs_list_objects_handler list_bucket_objects_handler =
+    {
+        { &response_properties_callback, &list_objects_complete_callback },
+        &list_objects_callback
+    };
+    
+    // Customize callback data.
+    list_bucket_callback_data data;
+    memset(&data, 0, sizeof(list_bucket_callback_data)); 
+    // List objects.
+    list_bucket_objects(&option, "<prefix>", "<marker>", "<delimiter>", "<maxkeys>", &list_bucket_objects_handler, &data); 
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("list bucket objects successfully. \n");
+    }
+    else
+    {
+        printf("list bucket objects failed(%s).\n", 
+            obs_get_status_name(data.ret_status));
+    }
+}
+
+
+
+
+
+
Parent topic: Getting Started
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0110.html b/docs/obs_3rd_party/c_sdk/obs_20_0110.html new file mode 100644 index 000000000..79c2cbd7a --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0110.html @@ -0,0 +1,48 @@ + + +

Deleting an Object

+

This example shows how to delete an object from a bucket.

+

Sample code:

+
static void test_delete_object()
+{
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Create and initialize object information.
+    obs_object_info object_info;
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "<Your Key>";
+    // Create and initialize option.
+    obs_options option;
+    init_obs_options(&option);
+    option.bucket_options.host_name = "<your-endpoint>";
+    option.bucket_options.bucket_name = "<Your bucketname>";
+
+// Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
+    // Obtain an AK/SK pair on the management console.
+    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
+    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
+    // Set response callback function.
+    obs_response_handler responseHandler =
+    { 
+        &response_properties_callback,
+        &response_complete_callback 
+    };
+    // Delete an object.
+    delete_object(&option,&object_info,&responseHandler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) 
+    {
+        printf("delete object successfully. \n");
+    }
+    else
+    {
+        printf("delete object failed(%s).\n", obs_get_status_name(ret_status));
+    }
+}
+
+
+
+
+
+
Parent topic: Getting Started
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0200.html b/docs/obs_3rd_party/c_sdk/obs_20_0200.html new file mode 100644 index 000000000..bef0f00b8 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0200.html @@ -0,0 +1,17 @@ + + +

Initialization

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0201.html b/docs/obs_3rd_party/c_sdk/obs_20_0201.html new file mode 100644 index 000000000..8a43fd9fd --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0201.html @@ -0,0 +1,13 @@ + + +

Configuring Access Keys

+

To use OBS, you need a valid pair of AK and SK for signature authentication. For details, see Creating Access Keys.

+

After obtaining the AK and SK, you can start initialization.

+ +
+
+
+
Parent topic: Initialization
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0202.html b/docs/obs_3rd_party/c_sdk/obs_20_0202.html new file mode 100644 index 000000000..46aae48c5 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0202.html @@ -0,0 +1,22 @@ + + +

Initializing the SDK

+

ObsClient functions as the C client for accessing OBS. It offers callers a series of APIs for interaction with OBS. These APIs are used for managing and operating resources, such as buckets and objects, stored in OBS.

+

Before using the OBS C SDK to initiate an OBS request, you need to call the initialization API. When you are exiting the process, you need to call the initialization cancellation API to release resources.

+

Before using the C SDK, you must first call obs_initialize to complete the initialization. This API only needs to called once in a process.

+
obs_status  ret_status = OBS_STATUS_BUTT;
+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 ret_status;
+}
+obs_deinitialize();
+// Do not repeatedly call obs_initialize or obs_deinitialize, because these operations may lead to invalid memory access.
+
+
+
+
Parent topic: Initialization
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0203.html b/docs/obs_3rd_party/c_sdk/obs_20_0203.html new file mode 100644 index 000000000..ae577e0e2 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0203.html @@ -0,0 +1,140 @@ + + +

Configuring option

+

When the function of SDK for C is called, the obs_options parameter must be passed. You can use function init_obs_options to initialize the obs_options configuration, including the AK, SK, endpoint, bucket, timeout, and temporary authentication. obs_options consists of obs_bucket_context and obs_http_request_option. The following table describes the parameters that can be set.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1 obs_options.obs_bucket_context parameters

Parameter

+

Description

+

Default Value

+

Recommended Value

+

host_name

+

The requested host name, which is the domain name (the endpoint) of the server where the requested resource is stored.

+

NULL

+

-

+

bucket_name

+

Name of the bucket where the operation is performed

+

NULL

+

-

+

protocol

+

The protocol used for sending requests. Possible values include HTTP and HTTPS. For security purposes, you are advised to use HTTPS.

+

HTTPS protocol: OBS_PROTOCOL_HTTPS

+

OBS_PROTOCOL_HTTPS

+

access_key

+

AK of OBS

+

NULL

+

-

+

secret_access_key

+

SK used for authentication. It can be used to sign a character string.

+

NULL

+

-

+

obs_storage_class

+

Set this parameter when the storage class needs to be configured in the PUT or POST request.

+

OBS Standard: OBS_STORAGE_CLASS_STANDARD

+

Default value

+

token

+

Security token of the temporary access key

+

NULL

+

-

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options.obs_http_request_option parameters

Parameter

+

Description

+

Default Value

+

Recommended Value

+

connect_time

+

Timeout period for establishing an HTTP/HTTPS connection, in ms. The default value is 60,000.

+

60000

+

10000 to 60000

+

max_connected_time

+

Timeout period (in seconds) of an HTTP/HTTPS request. The value 0 indicates that there is never disconnection.

+

0

+

0

+

proxy_auth

+

Proxy authentication information, in the format username:password

+

NULL

+

-

+

proxy_host

+

Proxy server

+

NULL

+

-

+
+
+

If the network is unstable, you are advised to set larger values for connect_time and max_connected_time.

+
+
+
+
+
Parent topic: Initialization
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0204.html b/docs/obs_3rd_party/c_sdk/obs_20_0204.html new file mode 100644 index 000000000..6fbaa4fd3 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0204.html @@ -0,0 +1,14 @@ + + +

Configuring SDK Logging

+

The OBS C SDK log path is specified by the LogPath field in OBS.ini. By default, logs are stored in the logs directory at the same level as the lib directory of the C SDK dynamic library. OBS.ini must be in the same directory as libeSDKLogAPI.so.

+

The OBS C SDK allows you to use set_obs_log_path to specify a log path. This method has two parameters. The first parameter specifies a path and the second determines what to do under the path. If the second parameter is set to True, the SDK searches for OBS.ini in the path specified by the first parameter for log configuration. If the second parameter is set to False, the SDK generates OBS.ini and log files in the path specified by the first parameter.

+
+
+
+
+
+
Parent topic: Initialization
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0300.html b/docs/obs_3rd_party/c_sdk/obs_20_0300.html new file mode 100644 index 000000000..3cc1353de --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0300.html @@ -0,0 +1,31 @@ + + +

Bucket Management

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0301.html b/docs/obs_3rd_party/c_sdk/obs_20_0301.html new file mode 100644 index 000000000..1a8fcc55c --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0301.html @@ -0,0 +1,2093 @@ + + +

Creating a Bucket

+

Function

OBS buckets are containers for storing objects you upload to OBS. This API creates a bucket.

+

When creating a bucket, you can also configure parameters such as the storage class, region, and access control list (ACL) as needed.

+
+

Restrictions

  • To create a bucket, you must have the obs:bucket:CreateBucket permission.
  • A maximum of 100 buckets (regardless of regions) can be created for an account. There is no limit on the number and size of objects in a bucket.
  • A bucket name must be unique in OBS. If you repeatedly create buckets with the same name in the same region, an HTTP status code 200 will be returned. In other cases, creating a bucket with the same name as an existing bucket will have an HTTP status code 409 returned, indicating that such a bucket already exists.
  • The name of a deleted bucket can be reused for another bucket or a parallel file system at least 30 minutes after the deletion.
+
+

Method

void create_bucket(const obs_options *options, obs_canned_acl canned_acl,
+            const char *location_constraint, 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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

canned_acl

+

obs_canned_acl

+

Yes

+

Explanation:

+

ACL of the bucket.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

location_constraint

+

const char *

+

Yes

+

Explanation:

+

Where a bucket is located.

+

Value range:

+

To learn about valid regions and endpoints, see Regions and Endpoints. An endpoint is the request address for calling an API. Endpoints vary depending on services and regions. To obtain the regions and endpoints, contact the enterprise administrator.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 4 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of obs_response_properties in the callback can be recorded into callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 6 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 8 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 9 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 11 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Default value:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

The algorithm used for decryption.

+

Restrictions:

+

Returned in the event of SSE-C server-side encryption.

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

The MD5 value of the key used for decryption.

+

Restrictions:

+
  • Returned in the event of SSE-C server-side encryption.
  • Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==
+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Creating an Object Bucket

This example creates an object bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // This example creates an object bucket.
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+
+    // 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";
+    // Set host_name to the endpoint of the region where the bucket is located. bucketLocation must match the endpoint.
+    char * bucketLocation = "your-location";
+    options.bucket_options.bucket_name = bucketName;
+    obs_response_handler response_handler = { &response_properties_callback, &response_complete_callback };
+    // Set the storage class of the bucket. The Standard class is used in this example.
+    options.bucket_options.storage_class = OBS_STORAGE_CLASS_STANDARD;
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Create a bucket and set the ACL for the bucket. The following uses a private bucket as an example.
+    create_bucket(&options, OBS_CANNED_ACL_PRIVATE, bucketLocation,
+                  &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("create bucket %s successfully. \n", bucketName);
+    } else {
+        printf("create bucket %s failed(%s).\n", bucketName, obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+

Code Examples: Creating a Bucket with Complex Configurations

This example specifies the ACL, storage class, and location when creating a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+int main()
+{
+    // The following example shows how to specify the ACL, storage class, and location when creating a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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";
+    // Set host_name to the endpoint of the region where the bucket is located. bucketLocation must match the endpoint.
+    char * bucketLocation = "your-location";
+
+    options.bucket_options.bucket_name = bucketName;
+    obs_response_handler response_handler = { &response_properties_callback, &response_complete_callback };
+    // Set the storage class of the bucket. The Standard class is used in this example.
+    options.bucket_options.storage_class = OBS_STORAGE_CLASS_STANDARD;
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Create a bucket. Set the bucket ACL (OBS_CANNED_ACL_PRIVATE), storage class (OBS_STORAGE_CLASS_STANDARD), and location (bucketLocation).
+    create_bucket(&options, OBS_CANNED_ACL_PRIVATE, bucketLocation,
+                  &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("create bucket %s successfully. \n", bucketName);
+    } else {
+        printf("create bucket %s failed(%s).\n", bucketName, obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0302.html b/docs/obs_3rd_party/c_sdk/obs_20_0302.html new file mode 100644 index 000000000..4bf114d41 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0302.html @@ -0,0 +1,1987 @@ + + +

Listing Buckets

+

Function

OBS buckets are containers for storing objects you upload to OBS. This API returns a list of all buckets that meet the specified conditions in all regions of the current account. Bucket names are returned in the lexicographical order.

+
+

Restrictions

  • To list buckets, you must have the obs:bucket:ListAllMyBuckets permission.
+
+

Method

void list_bucket_obs(const obs_options *options, obs_list_service_obs_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

handler

+

obs_list_service_obs_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 3 obs_list_service_obs_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

listServiceCallback

+

obs_list_service_obs_callback *

+

Yes

+

Explanation:

+

The pointer to the callback function, where the callback parameters can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 4 obs_list_service_obs_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

owner_id

+

const char *

+

Yes

+

Explanation:

+

Account (domain) ID of the bucket owner.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the account ID of the bucket owner, see How Do I Get My Account ID and User ID?

+

Default value:

+

None

+

bucket_name

+

const char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

creation_date_seconds

+

int64_t

+

Yes

+

Explanation:

+

Time when the bucket was created.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

location

+

const char *

+

Yes

+

Explanation:

+

Where a bucket is located.

+

Value range:

+

To learn about valid regions and endpoints, see Regions and Endpoints. An endpoint is the request address for calling an API. Endpoints vary depending on services and regions. To obtain the regions and endpoints, contact the enterprise administrator.

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 6 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 8 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 9 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 11 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

The algorithm used for decryption.

+

Restrictions:

+

Returned in the event of SSE-C server-side encryption.

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Listing Buckets

This example lists buckets.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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);
+void list_bucket_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
+// Customize the callback structure for listing buckets.
+typedef struct list_service_data
+{
+    int headerPrinted;
+    int allDetails;
+    obs_status ret_status;
+} list_service_data;
+obs_status listServiceObsCallback(const char *owner_id, const char *bucket_name, 
+    int64_t creationDate, const char *location, void *callback_data);
+int main()
+{
+    // The following example shows how to list buckets:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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");
+    
+    list_service_data data;
+    memset(&data, 0, sizeof(data));
+    // When the value is set to 1, the owner ID of the bucket is added.
+    data.allDetails = 1;
+    // Customize a response callback function.
+    obs_list_service_obs_handler listHandler =
+    { 
+        {response_properties_callback,
+        &list_bucket_complete_callback },
+        &listServiceObsCallback
+    };
+    // List buckets.
+    list_bucket_obs(&options, &listHandler, &data);
+    if (data.ret_status == OBS_STATUS_OK) 
+    {
+        printf("list bucket successfully. \n");
+    }
+    else
+    {
+        printf("list bucket failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void list_bucket_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
+{
+    if (callback_data) {
+        list_service_data *data = (list_service_data *)callback_data;
+        data->ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void printListServiceObsHeader(int allDetails)
+{
+    printf("%-56s  %-20s  %-20s", "                         Bucket",
+        "      Created",
+        "     Location");
+    if (allDetails) {
+        printf("  %-64s",
+            "                            Owner ID");
+    }
+    printf("\n");
+    printf("--------------------------------------------------------  "
+        "--------------------  "
+        "--------------------");
+    if (allDetails) {
+        printf("  -------------------------------------------------");
+    }
+    printf("\n");
+}
+obs_status listServiceObsCallback(const char *owner_id,
+    const char *bucket_name,
+    int64_t creationDate,
+    const char *location,
+    void *callback_data)
+{
+    list_service_data *data = (list_service_data *)callback_data;
+    if (!data->headerPrinted) {
+        data->headerPrinted = 1;
+        printListServiceObsHeader(data->allDetails);
+    }
+    char timebuf[256] = { 0 };
+    if (creationDate >= 0) {
+        time_t t = (time_t)creationDate;
+        strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ", gmtime(&t));
+    }
+    else {
+        timebuf[0] = 0;
+    }
+    printf("%-56s  %-20s  %-20s", bucket_name, timebuf, location);
+    if (data->allDetails) {
+        printf("  %-64s", owner_id ? owner_id : "");
+    }
+    printf("\n");
+    return OBS_STATUS_OK;
+}
+
+
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0303.html b/docs/obs_3rd_party/c_sdk/obs_20_0303.html new file mode 100644 index 000000000..a25c778f2 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0303.html @@ -0,0 +1,1753 @@ + + +

Deleting a Bucket

+

Function

This API deletes an empty bucket. You can delete buckets you no longer use to free up space. The name of a deleted bucket can be reused for another bucket at least 30 minutes after the deletion.

+
+

Restrictions

  • Only empty buckets can be deleted. An empty bucket means that:
    • The bucket does not contain any object (including noncurrent versions and delete markers).
    • The bucket does not contain any fragments, which means that there are no multipart uploads that have not been completed in the bucket.
    +
  • To delete a bucket, you must be the bucket owner or have the required permission (obs:bucket:DeleteBucket in IAM or DeleteBucket in a bucket policy).
+
+

Method

void delete_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, 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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 3 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 4 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 9 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Default value:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Deleting a Bucket

This example deletes bucket example-bucket-name.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+int main()
+{
+    // The following example shows how to delete a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    { 
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    // Delete the bucket.
+    delete_bucket(&options, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("delete bucket successfully. \n");
+    }
+    else
+    {
+        printf("delete bucket failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
  • Only empty buckets (without objects and fragments) can be deleted.
  • Bucket deletion is a non-idempotent operation and an error will be reported if the to-be-deleted bucket does not exist.
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0304.html b/docs/obs_3rd_party/c_sdk/obs_20_0304.html new file mode 100644 index 000000000..08e3a72b3 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0304.html @@ -0,0 +1,1753 @@ + + +

Checking Whether a Bucket Exists

+

Function

This API checks whether a bucket exists. If an HTTP status code 200 is returned, the bucket exists. If 404 is returned, the bucket does not exist.

+
+

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).
+
+

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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, 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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 3 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 4 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 9 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Default value:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Checking Whether a Bucket Exists

This example checks whether bucket example-bucket-name exists.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+int main()
+{
+    // The following example shows how to check whether a bucket exists:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    { 
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    // Check whether the bucket exists.
+    obs_head_bucket(&options, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) 
+    {
+        printf("head bucket successfully. \n");
+    }
+    else 
+    {
+        printf("head bucket failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0305.html b/docs/obs_3rd_party/c_sdk/obs_20_0305.html new file mode 100644 index 000000000..0a990defc --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0305.html @@ -0,0 +1,2733 @@ + + +

Configuring a Bucket ACL

+

Function

Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over resources when a bucket or object is created. That is, the bucket creator has full control over the bucket, and the object uploader has full control over the object. Other accounts do not have the permissions to access resources. If resource owners want to grant other accounts the read and write permissions on resources, they can use ACLs. ACLs grant permissions to accounts. After an account is granted permissions, both the account and its IAM users can access the resources.

+

+

This API modifies a bucket ACL.

+
+

Restrictions

  • A bucket can have up to 100 ACL rules.
  • To configure an ACL for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutBucketAcl in IAM or PutBucketAcl in a bucket policy).
+
+

Method

void set_bucket_acl(const obs_options * options, manager_acl_info * aclinfo, 
+            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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

aclinfo

+

manager_acl_info *

+

Yes

+

Explanation:

+

ACL structure.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 manager_acl_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID. If the object is not a versioned object, set version to NULL.

+

Restrictions:

+

None

+

owner_id

+

char *

+

Yes

+

Explanation:

+

Account (domain) ID of the bucket owner.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the account ID of the bucket owner, see How Do I Get My Account ID and User ID?

+

Default value:

+

None

+

owner_display_name

+

char *

+

Yes

+

Explanation:

+

Display name of a user

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

acl_grant_count_return

+

int *

+

Yes

+

Explanation:

+

Length of the acl_grants array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

object_delivered

+

obs_object_delivered

+

Yes

+

Explanation:

+

Whether the ACL of the bucket applies to its objects

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_object_delivered.

+

acl_grants

+

obs_acl_grant *

+

Yes

+

Explanation:

+

Permissions information structure.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 4 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 5 obs_object_delivered

Value

+

Description

+

OBJECT_DELIVERED_TRUE

+

The ACL of the bucket applies to its objects.

+

OBJECT_DELIVERED_FALSE

+

The ACL of the bucket does not apply to its objects.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 6 obs_acl_grant

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

grantee_type

+

obs_grantee_type

+

Yes

+

Explanation:

+

Description of the authorized user type

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_grantee_type.

+

grantee.canonical_user.id

+

char[]

+

No

+

Explanation:

+

User ID of the authorized user.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the ID of an authorized user, see How Do I Get My Account ID and User ID?.

+

Default value:

+

None

+

permission

+

obs_permission

+

Yes

+

Explanation:

+

Bucket ACL.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_permission.

+

bucket_delivered

+

obs_bucket_delivered

+

Yes

+

Explanation:

+

Whether the bucket ACL is passed to objects in the bucket.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_bucket_delivered.

+

Default value:

+

BUCKET_DELIVERED_FALSE (indicating that the bucket ACL is not passed to the objects in the bucket)

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_grantee_type

Value

+

Description

+

OBS_GRANTEE_TYPE_CANONICAL_USER

+

An OBS user. Bucket or object permissions can be granted to any user who has an OBS account.

+

Authorized users can use the AK and SK to access OBS.

+

OBS_GRANTEE_TYPE_ALL_USERS

+

All users can access buckets or objects, including anonymous users.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
Table 8 obs_permission

Value

+

Description

+

OBS_PERMISSION_READ

+

Read permission. A grantee with this permission for a bucket can obtain the list of objects in and metadata of the bucket.

+

A grantee with this permission for an object can obtain the object content and metadata.

+

OBS_PERMISSION_WRITE

+

Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object in the bucket.

+

This permission is not available for objects.

+

OBS_PERMISSION_READ_ACP

+

ACP read permission. A grantee with this permission can obtain the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

OBS_PERMISSION_WRITE_ACP

+

ACP write permission. A grantee with this permission can update the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object.

+

OBS_PERMISSION_FULL_CONTROL

+

Full control permission. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.

+

A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object.

+
+
+ +
+ + + + + + + + + + +
Table 9 obs_bucket_delivered

Value

+

Description

+

BUCKET_DELIVERED_FALSE

+

A bucket ACL is not applied to the objects in the bucket.

+

BUCKET_DELIVERED_TRUE

+

A bucket ACL is applied to the objects in the bucket.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 10 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 12 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 13 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 14 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 15 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 17 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 19 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Default value:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 23 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Setting a Pre-defined ACL When Creating a Bucket

This example specifies a pre-defined ACL when creating a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+int main()
+{
+    // The following example shows how to specify a pre-defined ACL when creating a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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";
+    // Set host_name to the endpoint of the region where the bucket is located. bucketLocation must match the endpoint.
+    char * bucketLocation = "your-location";
+    options.bucket_options.bucket_name = bucketName;
+    
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    { 
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    // Create a bucket and set the ACL for the bucket. The following example specifies a private bucket:
+    create_bucket(&options, OBS_CANNED_ACL_PRIVATE, bucketLocation, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("create bucket successfully. \n");
+    }
+    else
+    {
+        printf("create bucket failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+

Code Examples: Setting a Pre-defined ACL for an Existing Bucket

This example sets a pre-defined ACL for an existing bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+int main()
+{
+    // The following example shows how to set an ACL for a bucket using the header:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    { 
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    // Set the pre-defined ACL for the bucket.
+    obs_canned_acl canned_acl = OBS_CANNED_ACL_PUBLIC_READ_WRITE;
+    set_bucket_acl_by_head(&options, canned_acl, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("set bucket acl by head successfully. \n");
+    }
+    else
+    {
+        printf("set bucket acl by head failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+

Code Examples: Setting a User-defined Bucket ACL

This example sets a bucket ACL directly.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+void init_acl_info(manager_acl_info *aclinfo);
+void deinitialize_acl_info(manager_acl_info *aclinfo);
+int main()
+{
+    // The following example shows how to set an ACL for a bucket using the body:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    { 
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    // Create and initialize the ACL.
+    manager_acl_info aclinfo;
+    init_acl_info(&aclinfo);
+    // Set the bucket owner ID (owner_id).
+    strcpy(aclinfo.owner_id, "1******************************a");
+    // Set the tenant ID of the authorized account (canonical_user.id).
+    strcpy(aclinfo.acl_grants[0].grantee.canonical_user.id, "0******************************0");
+    strcpy(aclinfo.acl_grants[0].grantee.canonical_user.display_name, "name1");
+    aclinfo.acl_grants[0].grantee_type = OBS_GRANTEE_TYPE_CANONICAL_USER;
+    // Set the ACL. The read permission is used as an example.
+    aclinfo.acl_grants[0].permission = OBS_PERMISSION_READ;
+    // Specify whether the bucket ACL is passed to the objects in the bucket. In this example, the bucket ACL is not passed.
+    aclinfo.acl_grants[0].bucket_delivered = BUCKET_DELIVERED_FALSE;
+    // Set the bucket ACL.
+    set_bucket_acl(&options, &aclinfo, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("set bucket acl successfully. \n");
+    }
+    else
+    {
+        printf("set bucket acl failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the memory.
+    deinitialize_acl_info(&aclinfo);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void init_acl_info(manager_acl_info *aclinfo)
+{
+    memset(aclinfo, 0, sizeof(manager_acl_info));
+    aclinfo->acl_grants = (obs_acl_grant*)malloc(sizeof(obs_acl_grant));
+    memset(aclinfo->acl_grants, 0, sizeof(obs_acl_grant));
+    strcpy(aclinfo->acl_grants->grantee.canonical_user.id, "userid1");
+    strcpy(aclinfo->acl_grants->grantee.canonical_user.display_name, "name1");
+    aclinfo->acl_grants->grantee_type = OBS_GRANTEE_TYPE_LOG_DELIVERY;
+    aclinfo->acl_grants->permission = OBS_PERMISSION_WRITE;
+    aclinfo->acl_grants->bucket_delivered = BUCKET_DELIVERED_FALSE;
+    aclinfo->acl_grant_count_return = (int*)malloc(sizeof(int));
+    *(aclinfo->acl_grant_count_return) = 1;
+    aclinfo->owner_id = (char *)malloc(sizeof(char) * OBS_MAX_GRANTEE_USER_ID_SIZE);
+    memset(aclinfo->owner_id, 0, sizeof(char) * OBS_MAX_GRANTEE_USER_ID_SIZE);
+    aclinfo->owner_display_name = (char *)malloc(sizeof(char) * OBS_MAX_GRANTEE_USER_ID_SIZE);
+    memset(aclinfo->owner_display_name, 0, sizeof(char) * OBS_MAX_GRANTEE_USER_ID_SIZE);
+    memset(&aclinfo->object_info, 0, sizeof(aclinfo->object_info));
+}
+void deinitialize_acl_info(manager_acl_info *aclinfo)
+{
+    free(aclinfo->acl_grants);
+    free(aclinfo->owner_display_name);
+    free(aclinfo->owner_id);
+    free(aclinfo->acl_grant_count_return);
+}
+
+
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0306.html b/docs/obs_3rd_party/c_sdk/obs_20_0306.html new file mode 100644 index 000000000..2bdd42ae9 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0306.html @@ -0,0 +1,1826 @@ + + +

Obtaining Bucket Storage Information

+

Function

This API returns the storage information on a bucket, including the number of objects and the space occupied by the objects in the bucket.

+

OBS measures bucket storage statistics in the background and does not update the storage information in real time. So, you are advised not to perform real-time verification on the storage information.

+
+
+

Restrictions

  • To obtain the storage information of a bucket, you must be the bucket owner or have the required permission (obs:bucket:GetBucketStorage in IAM or GetBucketStorage in a bucket policy).
+
+

Method

void get_bucket_storage_info(const obs_options *options, int capacity_length, char *capacity,
+                    int object_number_length, char *object_number,
+                    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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

capacity_length

+

int

+

Yes

+

Explanation:

+

Cache size of the used capacity

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

capacity

+

char *

+

Yes

+

Explanation:

+

Used capacity

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

object_number_length

+

int

+

Yes

+

Explanation:

+

Cache size of the object number

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

object_number

+

char *

+

Yes

+

Explanation:

+

Cache of the object number

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 3 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 4 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 9 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Default value:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Obtaining Bucket Storage Information

This example obtains the storage information about a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+int main()
+{
+    // The following example shows how to obtain the storage information about a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    { 
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    //Define the bucket capacity cache and object quantity cache.
+    char capacity[OBS_COMMON_LEN_256 + 1] = { 0 };
+    char obj_num[OBS_COMMON_LEN_256 + 1] = { 0 };
+    // Obtain the bucket storage information.
+    get_bucket_storage_info(&options, OBS_COMMON_LEN_256 + 1, capacity, OBS_COMMON_LEN_256 + 1, obj_num,
+        &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("get_bucket_storage_info success,bucket=%s objNum=%s capacity=%s\n",
+            bucketName, obj_num, capacity);
+    }
+    else
+    {
+        printf("get_bucket_storage_info failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0307.html b/docs/obs_3rd_party/c_sdk/obs_20_0307.html new file mode 100644 index 000000000..648429d8f --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0307.html @@ -0,0 +1,1768 @@ + + +

Setting a Bucket Quota

+

Function

A quota limits the maximum capacity allowed in a bucket. By default, there is no limit on the storage capacity of the entire OBS system or a single bucket, and any number of objects can be stored. You can set a storage quota to control the total size of objects that can be uploaded to the bucket. If the storage quota is reached, object upload will fail.

+

A quota limit does not apply to the objects uploaded before the quota is configured. If the specified quota is already smaller than the total size of existing objects in the bucket, the existing objects in the bucket will not be deleted, but no more object can be uploaded to the bucket later. In this case, you can upload new objects only by deleting some existing objects until the used space is less than the quota.

+
+

Restrictions

  • A bucket storage quota must be a non-negative integer expressed in bytes. The maximum value is 263 – 1.
  • OBS does not provide an API for deleting bucket storage quotas. You can set the bucket storage quota to 0 to cancel the limit.
  • To configure a storage quota for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutBucketQuota in IAM or PutBucketQuota in a bucket policy).
+
+

Method

void set_bucket_quota(const obs_options *options, uint64_t storage_quota, 
+                               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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

storage_quota

+

uint64_t

+

Yes

+

Explanation:

+

Quota size, in bytes.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 3 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 4 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 9 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

The value must contain 32 characters.

+

Value range:

+

None

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Configuring a Bucket Quota

This example sets a bucket quota.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+int main()
+{
+    // The following example shows how to set a bucket quota:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    { 
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    uint64_t bucketquota = 100 * 1024 * 1024 * 1024;
+    // Set the bucket quota.
+    set_bucket_quota(&options, bucketquota, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("set bucket quota successfully. \n");
+    }
+    else
+    {
+        printf("set bucket quota failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0308.html b/docs/obs_3rd_party/c_sdk/obs_20_0308.html new file mode 100644 index 000000000..8197b08c1 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0308.html @@ -0,0 +1,1795 @@ + + +

Configuring a Storage Class for a Bucket

+

Function

This API configures a storage class for a bucket. If you do not specify a storage class when uploading or copying an object, or initiating a multipart upload, the object inherits the bucket's storage class.

+
+

Restrictions

  • To configure a storage class for a bucket, you must be the bucket owner or have the required permission (obs:PutBucketStoragePolicy in IAM or PutBucketStoragePolicy in a bucket policy).
+
+

Method

void set_bucket_storage_class_policy(const obs_options *options, 
+          obs_storage_class storage_class_policy, 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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

storage_class_policy

+

obs_storage_class

+

Yes

+

Explanation:

+

Storage class of the bucket.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 3 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 4 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 6 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 8 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 9 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 11 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

The value must contain 32 characters.

+

Value range:

+

None

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Configuring a Storage Class for a Bucket

This example sets the storage class for a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+int main()
+{
+    // The following example shows how to set a storage class for a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    obs_storage_class storage_class_policy = OBS_STORAGE_CLASS_GLACIER;
+    set_bucket_storage_class_policy(&options, storage_class_policy,
+        &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("set bucket storage class successfully.");
+    }
+    else
+    {
+        printf("set bucket storage class failed(%s).\n",
+            obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0309.html b/docs/obs_3rd_party/c_sdk/obs_20_0309.html new file mode 100644 index 000000000..0df74fff2 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0309.html @@ -0,0 +1,1847 @@ + + +

Obtaining the Storage Class of a Bucket

+

Function

This API returns the storage class of a bucket.

+
+

Restrictions

  • To obtain a bucket's storage class, you must be the bucket owner or have the required permission (obs:bucket:GetBucketStoragePolicy in IAM or GetBucketStoragePolicy in a bucket policy).
+
+

Method

void get_bucket_storage_class_policy(const obs_options *options, 
+                        obs_get_bucket_storage_class_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

handler

+

obs_get_bucket_storage_class_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 5 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_get_bucket_storage_class_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

get_bucket_storage_class_callback

+

obs_get_bucket_storage_policy_callback *

+

Yes

+

Explanation:

+

The pointer to the callback function, where the callback parameters can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_get_bucket_storage_policy_callback.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_get_bucket_storage_policy_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

storage_class_policy

+

const char *

+

Yes

+

Explanation:

+

Storage class of the bucket.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

The value must contain 32 characters.

+

Value range:

+

None

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Obtaining the Storage Class of a Bucket

This example obtains the storage class of a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+obs_status get_bucket_storageclass_handler(const char * storage_class, void * callBackData);
+int main()
+{
+    // The following example shows how to obtain the storage class of a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Set the response callback function.
+    obs_get_bucket_storage_class_handler getBucketStorageResponse =
+    {
+        {response_properties_callback, &response_complete_callback},
+        &get_bucket_storageclass_handler
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    //Obtain the bucket storage class.
+    get_bucket_storage_class_policy(&options, &getBucketStorageResponse, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("get bucket storage class successfully.\n");
+    }
+    else
+    {
+        printf("get bucket storage class failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+obs_status get_bucket_storageclass_handler(const char * storage_class, void * callBackData)
+{
+    printf("Bucket storage class is: %s\n", storage_class);
+    return OBS_STATUS_OK;
+}
+
+
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0310.html b/docs/obs_3rd_party/c_sdk/obs_20_0310.html new file mode 100644 index 000000000..1dcabd41b --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0310.html @@ -0,0 +1,1767 @@ + + +

Obtaining the Storage Quota of a Bucket

+

Function

This API returns the storage quota (upper limit of the storage capacity) of a bucket. If the quota is 0, there is no upper limit on the bucket capacity.

+
+

Restrictions

  • A bucket storage quota must be a non-negative integer expressed in bytes. The maximum value is 263 – 1.
  • A bucket owner with a frozen account in arrears is not allowed to query the bucket storage quota.
  • To obtain the storage quota of a bucket, you must be the bucket owner or have the required permission (obs:bucket:GetBucketQuota in IAM or GetBucketQuota in a bucket policy).
+
+

Method

void get_bucket_quota(const obs_options *options, uint64_t *storagequota_return,
+            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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

storagequota_return

+

uint64_t *

+

Yes

+

Explanation:

+

The obtained quota size, in bytes.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 3 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 4 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 9 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Obtaining a Bucket Quota

This example calls get_bucket_quota to obtain the storage quota of a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+int main()
+{
+    // The following example shows how to obtain the bucket quota:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    { 
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    // Obtain the bucket quota.
+    uint64_t bucketquota = 0;
+    get_bucket_quota(&options, &bucketquota, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("Bucket=%s  Quota=%lu \n get bucket quota successfully. \n ",
+            bucketName, bucketquota);
+    }
+    else
+    {
+        printf("get bucket quota failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0311.html b/docs/obs_3rd_party/c_sdk/obs_20_0311.html new file mode 100644 index 000000000..b043471dd --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0311.html @@ -0,0 +1,2265 @@ + + +

Obtaining a Bucket ACL

+

Function

Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over resources when a bucket or object is created. That is, the bucket creator has full control over the bucket, and the object uploader has full control over the object. Other accounts do not have the permissions to access resources. If resource owners want to grant other accounts the read and write permissions on resources, they can use ACLs. ACLs grant permissions to accounts. After an account is granted permissions, both the account and its IAM users can access the resources.

+

+

This API returns the ACL of a bucket.

+
+

Restrictions

  • To obtain the ACL of a bucket, you must be the bucket owner or have the required permission (obs:bucket:GetBucketAcl in IAM or GetBucketAcl in a bucket policy).
+
+

Method

void get_bucket_acl(const obs_options * options, manager_acl_info * aclinfo, 
+           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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

aclinfo

+

manager_acl_info *

+

Yes

+

Explanation:

+

ACL structure.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 manager_acl_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID. If the object is not a versioned object, set version to NULL.

+

Restrictions:

+

None

+

owner_id

+

char *

+

Yes

+

Explanation:

+

Account (domain) ID of the bucket owner.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the account ID of the bucket owner, see How Do I Get My Account ID and User ID?

+

Default value:

+

None

+

owner_display_name

+

char *

+

Yes

+

Explanation:

+

Display name of a user

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

acl_grant_count_return

+

int *

+

Yes

+

Explanation:

+

Length of the acl_grants array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

object_delivered

+

obs_object_delivered

+

Yes

+

Explanation:

+

Whether the ACL of the bucket applies to its objects

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_object_delivered.

+

acl_grants

+

obs_acl_grant *

+

Yes

+

Explanation:

+

Permissions information structure.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 4 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 5 obs_object_delivered

Value

+

Description

+

OBJECT_DELIVERED_TRUE

+

The ACL of the bucket applies to its objects.

+

OBJECT_DELIVERED_FALSE

+

The ACL of the bucket does not apply to its objects.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 6 obs_acl_grant

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

grantee_type

+

obs_grantee_type

+

Yes

+

Explanation:

+

Description of the authorized user type

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_grantee_type.

+

grantee.canonical_user.id

+

char[]

+

No

+

Explanation:

+

User ID of the authorized user.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the ID of an authorized user, see How Do I Get My Account ID and User ID?.

+

Default value:

+

None

+

permission

+

obs_permission

+

Yes

+

Explanation:

+

Bucket ACL.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_permission.

+

bucket_delivered

+

obs_bucket_delivered

+

Yes

+

Explanation:

+

Whether the bucket ACL is passed to objects in the bucket.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_bucket_delivered.

+

Default value:

+

BUCKET_DELIVERED_FALSE (indicating that the bucket ACL is not passed to the objects in the bucket)

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_grantee_type

Value

+

Description

+

OBS_GRANTEE_TYPE_CANONICAL_USER

+

An OBS user. Bucket or object permissions can be granted to any user who has an OBS account.

+

Authorized users can use the AK and SK to access OBS.

+

OBS_GRANTEE_TYPE_ALL_USERS

+

All users can access buckets or objects, including anonymous users.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
Table 8 obs_permission

Value

+

Description

+

OBS_PERMISSION_READ

+

Read permission. A grantee with this permission for a bucket can obtain the list of objects in and metadata of the bucket.

+

A grantee with this permission for an object can obtain the object content and metadata.

+

OBS_PERMISSION_WRITE

+

Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object in the bucket.

+

This permission is not available for objects.

+

OBS_PERMISSION_READ_ACP

+

ACP read permission. A grantee with this permission can obtain the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

OBS_PERMISSION_WRITE_ACP

+

ACP write permission. A grantee with this permission can update the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object.

+

OBS_PERMISSION_FULL_CONTROL

+

Full control permission. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.

+

A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object.

+
+
+ +
+ + + + + + + + + + +
Table 9 obs_bucket_delivered

Value

+

Description

+

BUCKET_DELIVERED_FALSE

+

A bucket ACL is not applied to the objects in the bucket.

+

BUCKET_DELIVERED_TRUE

+

A bucket ACL is applied to the objects in the bucket.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 10 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 12 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 13 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 14 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 15 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 17 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 19 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Default value:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 23 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Obtaining a Bucket ACL

You can call get_bucket_acl to obtain the bucket ACL. The following example shows how to obtain the bucket ACL:
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.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 completion callback function. 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);
+manager_acl_info* malloc_acl_info();
+void free_acl_info(manager_acl_info **acl);
+void print_grant_info(int acl_grant_count, obs_acl_grant *acl_grants);
+int main()
+{
+    // The following example shows how to obtain the bucket ACL:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    { 
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    // Allocate the memory for the ACL structure.
+    manager_acl_info *aclinfo = malloc_acl_info();
+    // Call the API for obtaining the ACL.
+    get_bucket_acl(&options, aclinfo, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("get bucket acl: -------------");
+        printf("%s\n", aclinfo->owner_id);
+        if (aclinfo->acl_grant_count_return)
+        {
+            print_grant_info(*aclinfo->acl_grant_count_return, aclinfo->acl_grants);
+        }
+    }
+    else
+    {
+        printf("get bucket acl failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the memory.
+    free_acl_info(&aclinfo);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+manager_acl_info* malloc_acl_info()
+{
+    manager_acl_info *aclinfo = (manager_acl_info*)malloc(sizeof(manager_acl_info));
+    memset(aclinfo, 0, sizeof(manager_acl_info));
+    aclinfo->acl_grants = (obs_acl_grant*)malloc(sizeof(obs_acl_grant) * OBS_MAX_ACL_GRANT_COUNT);
+    memset(aclinfo->acl_grants, 0, sizeof(obs_acl_grant) * OBS_MAX_ACL_GRANT_COUNT);
+    aclinfo->acl_grant_count_return = (int*)malloc(sizeof(int));
+    *(aclinfo->acl_grant_count_return) = OBS_MAX_ACL_GRANT_COUNT;
+    size_t owner_id_size = (OBS_MAX_GRANTEE_USER_ID_SIZE + 1) * sizeof(char);
+    aclinfo->owner_id = (char *)malloc(owner_id_size);
+    memset(aclinfo->owner_id, 0, owner_id_size);
+    aclinfo->owner_display_name = (char *)malloc(OBS_MAX_GRANTEE_DISPLAY_NAME_SIZE);
+    memset(aclinfo->owner_display_name, 0, OBS_MAX_GRANTEE_DISPLAY_NAME_SIZE);
+    return aclinfo;
+}
+void free_acl_info(manager_acl_info **acl)
+{
+    manager_acl_info *aclinfo = *acl;
+    free(aclinfo->acl_grants);
+    free(aclinfo->owner_display_name);
+    free(aclinfo->owner_id);
+    free(aclinfo->acl_grant_count_return);
+    free(aclinfo);
+}
+void print_grant_info(int acl_grant_count, obs_acl_grant *acl_grants)
+{
+    int i;
+    for (i = 0; i < acl_grant_count; i++)
+    {
+        obs_acl_grant *grant = acl_grants + i;
+        const char *type;
+        char composedId[OBS_MAX_GRANTEE_USER_ID_SIZE +
+            OBS_MAX_GRANTEE_DISPLAY_NAME_SIZE + 16] = { 0 };
+        const char *id;
+        switch (grant->grantee_type) {
+        case OBS_GRANTEE_TYPE_CANONICAL_USER:
+            type = "UserID";
+            snprintf(composedId, sizeof(composedId),
+                "%s (%s)", grant->grantee.canonical_user.id,
+                grant->grantee.canonical_user.display_name);
+            id = composedId;
+            break;
+        case OBS_GRANTEE_TYPE_ALL_OBS_USERS:
+            type = "Group";
+            id = "Authenticated Users";
+            break;
+        default:
+            type = "Group";
+            id = "All Users";
+            break;
+        }
+        const char *perm;
+        switch (grant->permission) {
+        case OBS_PERMISSION_READ:
+            perm = "READ";
+            break;
+        case OBS_PERMISSION_WRITE:
+            perm = "WRITE";
+            break;
+        case OBS_PERMISSION_READ_ACP:
+            perm = "READ_ACP";
+            break;
+        case OBS_PERMISSION_WRITE_ACP:
+            perm = "WRITE_ACP";
+            break;
+        default:
+            perm = "FULL_CONTROL";
+            break;
+        }
+        const char *delivered;
+        if (grant->bucket_delivered == BUCKET_DELIVERED_FALSE)
+            delivered = "false";
+        else
+            delivered = "true";
+        printf("%-6s  %-90s  %-12s  %-8s\n", type, id, perm, delivered);
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Bucket Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0314.html b/docs/obs_3rd_party/c_sdk/obs_20_0314.html new file mode 100644 index 000000000..7ef401349 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0314.html @@ -0,0 +1,1891 @@ + + +

Setting a Pre-defined ACL for an Object

+

Function

Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over resources when a bucket or object is created. That is, the bucket creator has full control over the bucket, and the object uploader has full control over the object. Other accounts do not have the permissions to access resources. If resource owners want to grant other accounts the read and write permissions on resources, they can use ACLs. ACLs grant permissions to accounts. After an account is granted permissions, both the account and its IAM users can access the resources.

+

+

This API sets a pre-defined ACL for an existing object in a specified bucket.

+
+

Restrictions

  • To configure an object ACL, you must be the bucket owner or have the required permission (obs:object:PutObjectAcl in IAM or PutObjectAcl in a bucket policy).
  • An object ACL supports a maximum of 100 Grants.
+
+

Method

void set_object_acl_by_head(const obs_options *options, obs_object_info *object_info, 
+    obs_canned_acl canned_acl, obs_response_handler *handler, void *callback_data);
+
+

Request Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1 List of request parameters

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

options

+

constobs_options*

+

Yes

+

Explanation:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

canned_acl

+

obs_canned_acl

+

Yes

+

Explanation:

+

Pre-defined ACL

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+
+

Code Examples: Setting a Pre-defined ACL for an Object

This example sets an object ACL using set_object_acl_by_head.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to set an object ACL using set_object_acl_by_head:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    obs_canned_acl canned_acl = OBS_CANNED_ACL_PUBLIC_READ_WRITE;
+    obs_object_info object_info;
+    object_info.key = "example_get_file_test";
+    object_info.version_id = NULL;
+    // Set the pre-defined ACL for the object.
+    set_object_acl_by_head(&options, &object_info, canned_acl, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("set object acl by head successfully. \n");
+    }
+    else
+    {
+        printf("set object acl by head failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Object Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0315.html b/docs/obs_3rd_party/c_sdk/obs_20_0315.html new file mode 100644 index 000000000..88f37d1b9 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0315.html @@ -0,0 +1,2136 @@ + + +

Setting a User-defined Object ACL

+

Function

Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over resources when a bucket or object is created. That is, the bucket creator has full control over the bucket, and the object uploader has full control over the object. Other accounts do not have the permissions to access resources. If resource owners want to grant other accounts the read and write permissions on resources, they can use ACLs. ACLs grant permissions to accounts. After an account is granted permissions, both the account and its IAM users can access the resources.

+

+

This API directly sets an ACL for an existing object in a specified bucket.

+
+

Restrictions

  • To configure an object ACL, you must be the bucket owner or have the required permission (obs:object:PutObjectAcl in IAM or PutObjectAcl in a bucket policy).
  • An object ACL supports a maximum of 100 Grants.
+
+

Method

void set_object_acl(const obs_options *options, manager_acl_info *aclinfo, obs_response_handler *handler, void *callback_data);
+
+

Request Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1 List of request parameters

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

options

+

constobs_options*

+

Yes

+

Explanation:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

aclinfo

+

manager_acl_info *

+

Yes

+

Explanation:

+

Structure for managing ACL permission information

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 manager_acl_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

If the object is not a versioned object, set the version to NULL.

+

owner_id

+

char *

+

Yes

+

Explanation:

+

Account (domain) ID of the bucket owner.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the account ID of the bucket owner, see How Do I Get My Account ID and User ID?

+

Default value:

+

None

+

owner_display_name

+

char *

+

Yes

+

Explanation:

+

Display name of a user

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

acl_grant_count_return

+

int *

+

Yes

+

Explanation:

+

Length of the acl_grants array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

object_delivered

+

obs_object_delivered

+

Yes

+

Explanation:

+

Whether the ACL of the bucket applies to its objects

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_object_delivered.

+

Default value:

+

OBJECT_DELIVERED_TRUE (The ACL of the bucket applies to its objects.)

+

acl_grants

+

obs_acl_grant *

+

Yes

+

Explanation:

+

Permission information structure.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 19 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 20 obs_object_delivered

Value

+

Description

+

OBJECT_DELIVERED_TRUE

+

The ACL of the bucket applies to its objects.

+

OBJECT_DELIVERED_FALSE

+

The ACL of the bucket does not apply to its objects.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_acl_grant

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

grantee_type

+

obs_grantee_type

+

Yes

+

Explanation:

+

Description of the authorized user type

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_grantee_type.

+

grantee.canonical_user.id

+

char[]

+

No

+

Explanation:

+

User ID of the authorized user.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the ID of an authorized user, see How Do I Get My Account ID and User ID?.

+

Default value:

+

None

+

permission

+

obs_permission

+

Yes

+

Explanation:

+

Bucket ACL.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_permission.

+

bucket_delivered

+

obs_bucket_delivered

+

Yes

+

Explanation:

+

Whether the bucket ACL is applied to the objects in the bucket

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_bucket_delivered.

+

Default value:

+

BUCKET_DELIVERED_FALSE (The ACL of the bucket does not apply to its objects.)

+
+
+ +
+ + + + + + + + + + +
Table 22 obs_grantee_type

Value

+

Description

+

OBS_GRANTEE_TYPE_CANONICAL_USER

+

An OBS user. Bucket or object permissions can be granted to any user who has an OBS account.

+

Authorized users can use the AK and SK to access OBS.

+

OBS_GRANTEE_TYPE_ALL_USERS

+

All users can access buckets or objects, including anonymous users.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
Table 23 obs_permission

Value

+

Description

+

OBS_PERMISSION_READ

+

Read permission. A grantee with this permission for a bucket can obtain the list of objects in and metadata of the bucket.

+

A grantee with this permission for an object can obtain the object content and metadata.

+

OBS_PERMISSION_WRITE

+

Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object in the bucket.

+

This permission is not available for objects.

+

OBS_PERMISSION_READ_ACP

+

ACP read permission. A grantee with this permission can obtain the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

OBS_PERMISSION_WRITE_ACP

+

ACP write permission. A grantee with this permission can update the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object.

+

OBS_PERMISSION_FULL_CONTROL

+

Full control permission. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.

+

A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object.

+
+
+ +
+ + + + + + + + + + +
Table 24 obs_bucket_delivered

Value

+

Description

+

BUCKET_DELIVERED_FALSE

+

A bucket ACL is not applied to the objects in the bucket.

+

BUCKET_DELIVERED_TRUE

+

A bucket ACL is applied to the objects in the bucket.

+
+
+
+

Code Examples: Setting a User-defined Object ACL

This example sets an object ACL using set_object_acl.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to set an object ACL using set_object_acl:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Define an object ACL.
+    manager_acl_info aclinfo;
+    memset(&aclinfo, 0, sizeof(aclinfo));
+    aclinfo.object_info.key = "example_get_file_test";
+    aclinfo.object_info.version_id = NULL;
+    aclinfo.owner_id = "1******************************a";
+    // Set the ACL.
+    int acl_grant_count = 1;
+    aclinfo.acl_grant_count_return = &acl_grant_count;
+    aclinfo.acl_grants = (obs_acl_grant*)malloc(sizeof(obs_acl_grant) * acl_grant_count);
+    // Set the tenant ID of the authorized account (canonical_user.id).
+    strcpy(aclinfo.acl_grants[0].grantee.canonical_user.id, "0******************************0");
+    strcpy(aclinfo.acl_grants[0].grantee.canonical_user.display_name, "name1");
+    aclinfo.acl_grants[0].grantee_type = OBS_GRANTEE_TYPE_CANONICAL_USER;
+    // Specify the ACL. The read permission is used as an example.
+    aclinfo.acl_grants[0].permission = OBS_PERMISSION_READ;
+    // Set the object ACL.
+    set_object_acl(&options, &aclinfo, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("set object acl successfully. \n");
+    }
+    else
+    {
+        printf("set object acl failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    free(aclinfo.acl_grants);
+    aclinfo.acl_grants = NULL;
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Object Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0316.html b/docs/obs_3rd_party/c_sdk/obs_20_0316.html new file mode 100644 index 000000000..2bd28e48b --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0316.html @@ -0,0 +1,2338 @@ + + +

Obtaining the ACL of an Object

+

Function

Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over resources when a bucket or object is created. That is, the bucket creator has full control over the bucket, and the object uploader has full control over the object. Other accounts do not have the permissions to access resources. If resource owners want to grant other accounts the read and write permissions on resources, they can use ACLs. ACLs grant permissions to accounts. After an account is granted permissions, both the account and its IAM users can access the resources.

+

+

This API returns the ACL of an object.

+
+

Restrictions

  • To obtain an object ACL, you must be the bucket owner or have the required permission (obs:object:GetObjectAcl in IAM or GetObjectAcl in a bucket policy).
+
+

Method

void get_object_acl(const obs_options *options, manager_acl_info *aclinfo, obs_response_handler *handler, void *callback_data);
+
+

Request Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1 List of request parameters

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

options

+

constobs_options*

+

Yes

+

Explanation:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

aclinfo

+

manager_acl_info *

+

Yes

+

Explanation:

+

Structure for managing ACL permission information

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 manager_acl_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

If the object is not a versioned object, set the version to NULL.

+

owner_id

+

char *

+

Yes

+

Explanation:

+

Account (domain) ID of the bucket owner.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the account ID of the bucket owner, see How Do I Get My Account ID and User ID?

+

Default value:

+

None

+

owner_display_name

+

char *

+

Yes

+

Explanation:

+

Display name of a user

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

acl_grant_count_return

+

int *

+

Yes

+

Explanation:

+

Length of the acl_grants array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

object_delivered

+

obs_object_delivered

+

Yes

+

Explanation:

+

Whether the ACL of the bucket applies to its objects

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_object_delivered.

+

Default value:

+

OBJECT_DELIVERED_TRUE (The ACL of the bucket applies to its objects.)

+

acl_grants

+

obs_acl_grant *

+

Yes

+

Explanation:

+

Permission information structure.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 19 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 20 obs_object_delivered

Value

+

Description

+

OBJECT_DELIVERED_TRUE

+

The ACL of the bucket applies to its objects.

+

OBJECT_DELIVERED_FALSE

+

The ACL of the bucket does not apply to its objects.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_acl_grant

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

grantee_type

+

obs_grantee_type

+

Yes

+

Explanation:

+

Description of the authorized user type

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_grantee_type.

+

grantee.canonical_user.id

+

char[]

+

No

+

Explanation:

+

User ID of the authorized user.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the ID of an authorized user, see How Do I Get My Account ID and User ID?.

+

Default value:

+

None

+

permission

+

obs_permission

+

Yes

+

Explanation:

+

Bucket ACL.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_permission.

+

bucket_delivered

+

obs_bucket_delivered

+

Yes

+

Explanation:

+

Whether the bucket ACL is applied to the objects in the bucket

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_bucket_delivered.

+

Default value:

+

BUCKET_DELIVERED_FALSE (The ACL of the bucket does not apply to its objects.)

+
+
+ +
+ + + + + + + + + + +
Table 22 obs_grantee_type

Value

+

Description

+

OBS_GRANTEE_TYPE_CANONICAL_USER

+

An OBS user. Bucket or object permissions can be granted to any user who has an OBS account.

+

Authorized users can use the AK and SK to access OBS.

+

OBS_GRANTEE_TYPE_ALL_USERS

+

All users can access buckets or objects, including anonymous users.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
Table 23 obs_permission

Value

+

Description

+

OBS_PERMISSION_READ

+

Read permission. A grantee with this permission for a bucket can obtain the list of objects in and metadata of the bucket.

+

A grantee with this permission for an object can obtain the object content and metadata.

+

OBS_PERMISSION_WRITE

+

Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object in the bucket.

+

This permission is not available for objects.

+

OBS_PERMISSION_READ_ACP

+

ACP read permission. A grantee with this permission can obtain the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

OBS_PERMISSION_WRITE_ACP

+

ACP write permission. A grantee with this permission can update the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object.

+

OBS_PERMISSION_FULL_CONTROL

+

Full control permission. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.

+

A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object.

+
+
+ +
+ + + + + + + + + + +
Table 24 obs_bucket_delivered

Value

+

Description

+

BUCKET_DELIVERED_FALSE

+

A bucket ACL is not applied to the objects in the bucket.

+

BUCKET_DELIVERED_TRUE

+

A bucket ACL is applied to the objects in the bucket.

+
+
+
+

Code Examples: Obtaining the ACL of an Object

This example obtains the ACL of an object using get_object_acl.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+manager_acl_info* malloc_acl_info();
+void free_acl_info(manager_acl_info **acl); 
+void print_acl(manager_acl_info* acl);
+int main()
+{
+    // The following code shows how to obtain an object ACL using get_object_acl:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    options.bucket_options.protocol = OBS_PROTOCOL_HTTP;
+    obs_response_handler response_handler =
+    {
+        &response_properties_callback, &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Object ACL
+    manager_acl_info *aclinfo = malloc_acl_info();
+    aclinfo->object_info.key = "example_get_file_test";
+    aclinfo->object_info.version_id = NULL;
+    // Obtain the ACL.
+    get_object_acl(&options, aclinfo, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("get object acl successfully. \n");
+        print_acl(aclinfo);
+    }
+    else
+    {
+        printf("get object acl failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Free the memory.
+    free_acl_info(&aclinfo);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+void print_acl(manager_acl_info* acl) {
+    if (acl == NULL) {
+        printf("acl is NULL.\n");
+        return;
+    }
+    printf("object key :%s\n", acl->object_info.key);
+    printf("object version_id :%s\n", acl->object_info.version_id);
+    printf("object owner_id :%s\n", acl->owner_id);
+    printf("object owner_display_name :%s\n", acl->owner_display_name);
+    switch (acl->object_delivered)
+    {
+    case OBJECT_DELIVERED_TRUE:
+        printf("object acl delivered.\n");
+        break;
+    default:
+        printf("object acl not delivered.\n");
+        break;
+    }
+    if (acl->acl_grant_count_return == NULL) {
+        printf("acl_grant_count_return is NULL.\n");
+        return;
+    }
+    printf("object acl_grant_count :%d\n", *acl->acl_grant_count_return);
+    if (acl->acl_grants == NULL) {
+        printf("acl_grants is NULL.\n");
+        return;
+    }
+    for (int i = 0; i < *acl->acl_grant_count_return; ++i) {
+        obs_acl_grant* acl_grant = acl->acl_grants + i;
+        printf("acl %d\n", i + 1);
+        switch (acl_grant->bucket_delivered)
+        {
+        case BUCKET_DELIVERED_TRUE:
+            printf("object acl delivered from bucket.\n");
+            break;
+        default:
+            printf("object acl not delivered from bucket.\n");
+            break;
+        }
+        switch (acl_grant->grantee_type)
+        {
+        case OBS_GRANTEE_TYPE_CANONICAL_USER:
+            printf("object acl grantee_type is OBS_GRANTEE_TYPE_CANONICAL_USER.\n");
+            break;
+        case OBS_GRANTEE_TYPE_ALL_OBS_USERS:
+            printf("object acl grantee_type is OBS_GRANTEE_TYPE_ALL_OBS_USERS.\n");
+            break;
+        case OBS_GRANTEE_TYPE_ALL_USERS:
+            printf("object acl grantee_type is OBS_GRANTEE_TYPE_ALL_USERS.\n");
+            break;
+        case OBS_GRANTEE_TYPE_LOG_DELIVERY:
+            printf("object acl grantee_type is OBS_GRANTEE_TYPE_LOG_DELIVERY.\n");
+            break;
+        default:
+            printf("object acl grantee_type is unknown.\n");
+            break;
+        }
+        switch (acl_grant->permission)
+        {
+        case OBS_PERMISSION_READ:
+            printf("object acl grantee_type is OBS_PERMISSION_READ.\n");
+            break;
+        case OBS_PERMISSION_WRITE:
+            printf("object acl grantee_type is OBS_PERMISSION_WRITE.\n");
+            break;
+        case OBS_PERMISSION_READ_ACP:
+            printf("object acl grantee_type is OBS_PERMISSION_READ_ACP.\n");
+            break;
+        case OBS_PERMISSION_WRITE_ACP:
+            printf("object acl grantee_type is OBS_PERMISSION_WRITE_ACP.\n");
+            break;
+        case OBS_PERMISSION_FULL_CONTROL:
+            printf("object acl grantee_type is OBS_PERMISSION_FULL_CONTROL.\n");
+            break;
+        default:
+            printf("object acl grantee_type is unknown.\n");
+            break;
+        }
+        printf("acl_grant->grantee.canonical_user.display_name: %s\n", acl_grant->grantee.canonical_user.display_name);
+        printf("acl_grant->grantee.canonical_user.id: %s\n", acl_grant->grantee.canonical_user.id);
+    }
+}
+manager_acl_info* malloc_acl_info()
+{
+    manager_acl_info *aclinfo = (manager_acl_info*)malloc(sizeof(manager_acl_info));
+    memset(aclinfo, 0, sizeof(manager_acl_info));
+    size_t acl_grants_size = OBS_MAX_ACL_GRANT_COUNT * sizeof(obs_acl_grant);
+    aclinfo->acl_grants = (obs_acl_grant*)malloc(acl_grants_size);
+    memset(aclinfo->acl_grants, 0, acl_grants_size);
+    aclinfo->acl_grant_count_return = (int*)malloc(sizeof(int));
+    *(aclinfo->acl_grant_count_return) = 0;
+    size_t owner_id_size = (OBS_MAX_GRANTEE_USER_ID_SIZE + 1) * sizeof(char);
+    size_t owner_display_name_size = (OBS_MAX_GRANTEE_USER_ID_SIZE + 1) * sizeof(char);
+    aclinfo->owner_id = (char *)malloc(owner_id_size);
+    memset(aclinfo->owner_id, 0, owner_id_size);
+    aclinfo->owner_display_name = (char *)malloc(owner_display_name_size);
+    memset(aclinfo->owner_display_name, 0, owner_display_name_size);
+    return aclinfo;
+}
+void free_acl_info(manager_acl_info **acl)
+{
+    manager_acl_info *aclinfo = *acl;
+    free(aclinfo->acl_grants);
+    free(aclinfo->owner_display_name);
+    free(aclinfo->owner_id);
+    free(aclinfo->acl_grant_count_return);
+    free(aclinfo);
+}
+
+
+
+
+
+
+
+
Parent topic: Object Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0317.html b/docs/obs_3rd_party/c_sdk/obs_20_0317.html new file mode 100644 index 000000000..3adc681ae --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0317.html @@ -0,0 +1,1891 @@ + + +

Setting a Pre-defined ACL for an Object Version

+

Function

OBS allows you to control access to versioned objects. By default, only the versioned object creator has the read and write permissions on the object. You can set access control policies for versioned objects. For example, if an object is configured with the public access policy, all users are allowed to read the object. If a versioned object is encrypted with SSE-KMS, the ACL configured for it is not in effect in the cross-tenant case.

+

You can set an access control policy when uploading a versioned object or call an ACL API to modify or obtain the ACL of an existing object.

+

This API sets an ACL for a versioned object in a specified bucket.

+
+

Restrictions

  • To configure an object ACL, you must be the bucket owner or have the required permission (obs:object:PutObjectAcl in IAM or PutObjectAcl in a bucket policy).
  • An object ACL supports a maximum of 100 Grants.
+
+

Method

void set_object_acl_by_head(const obs_options *options, obs_object_info *object_info, 
+    obs_canned_acl canned_acl, obs_response_handler *handler, void *callback_data);
+
+

Request Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1 List of request parameters

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

options

+

constobs_options*

+

Yes

+

Explanation:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

canned_acl

+

obs_canned_acl

+

Yes

+

Explanation:

+

Pre-defined ACL

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+
+

Code Examples: Setting an Object Version ACL

This example sets the ACL for an object version using set_object_acl_by_head.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to set object properties using set_object_acl_by_head:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    obs_canned_acl canned_acl = OBS_CANNED_ACL_PUBLIC_READ_WRITE;
+    obs_object_info object_info;
+    object_info.key = "example_get_file_test";
+    object_info.version_id = "G00111934EAA2CE900004016129AC990";
+    // Set a pre-defined ACL for an object.
+    set_object_acl_by_head(&options, &object_info, canned_acl, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("set object acl by head successfully. \n");
+    }
+    else
+    {
+        printf("set object acl by head failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0318.html b/docs/obs_3rd_party/c_sdk/obs_20_0318.html new file mode 100644 index 000000000..240c9b0a4 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0318.html @@ -0,0 +1,2136 @@ + + +

Setting an Object Version ACL Directly

+

Function

OBS allows you to control access to versioned objects. By default, only the versioned object creator has the read and write permissions on the object. You can set access control policies for versioned objects. For example, if an object is configured with the public access policy, all users are allowed to read the object. If a versioned object is encrypted with SSE-KMS, the ACL configured for it is not in effect in the cross-tenant case.

+

You can set an access control policy when uploading a versioned object or call an ACL API to modify or obtain the ACL of an existing object.

+

This API sets an ACL for a versioned object in a specified bucket.

+
+

Restrictions

  • To configure an object ACL, you must be the bucket owner or have the required permission (obs:object:PutObjectAcl in IAM or PutObjectAcl in a bucket policy).
  • An object ACL supports a maximum of 100 Grants.
+
+

Method

void set_object_acl(const obs_options *options, manager_acl_info *aclinfo, obs_response_handler *handler, void *callback_data);
+
+

Request Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1 List of request parameters

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

options

+

constobs_options*

+

Yes

+

Explanation:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

aclinfo

+

manager_acl_info *

+

Yes

+

Explanation:

+

Structure for managing ACL permission information

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 manager_acl_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

If the object is not a versioned object, set the version to NULL.

+

owner_id

+

char *

+

Yes

+

Explanation:

+

Account (domain) ID of the bucket owner.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the account ID of the bucket owner, see How Do I Get My Account ID and User ID?

+

Default value:

+

None

+

owner_display_name

+

char *

+

Yes

+

Explanation:

+

Display name of a user

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

acl_grant_count_return

+

int *

+

Yes

+

Explanation:

+

Length of the acl_grants array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

object_delivered

+

obs_object_delivered

+

Yes

+

Explanation:

+

Whether the ACL of the bucket applies to its objects

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_object_delivered.

+

Default value:

+

OBJECT_DELIVERED_TRUE (The ACL of the bucket applies to its objects.)

+

acl_grants

+

obs_acl_grant *

+

Yes

+

Explanation:

+

Permission information structure.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 19 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 20 obs_object_delivered

Value

+

Description

+

OBJECT_DELIVERED_TRUE

+

The ACL of the bucket applies to its objects.

+

OBJECT_DELIVERED_FALSE

+

The ACL of the bucket does not apply to its objects.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_acl_grant

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

grantee_type

+

obs_grantee_type

+

Yes

+

Explanation:

+

Description of the authorized user type

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_grantee_type.

+

grantee.canonical_user.id

+

char[]

+

No

+

Explanation:

+

User ID of the authorized user.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the ID of an authorized user, see How Do I Get My Account ID and User ID?.

+

Default value:

+

None

+

permission

+

obs_permission

+

Yes

+

Explanation:

+

Bucket ACL.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_permission.

+

bucket_delivered

+

obs_bucket_delivered

+

Yes

+

Explanation:

+

Whether the bucket ACL is applied to the objects in the bucket

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_bucket_delivered.

+

Default value:

+

BUCKET_DELIVERED_FALSE (The ACL of the bucket does not apply to its objects.)

+
+
+ +
+ + + + + + + + + + +
Table 22 obs_grantee_type

Value

+

Description

+

OBS_GRANTEE_TYPE_CANONICAL_USER

+

An OBS user. Bucket or object permissions can be granted to any user who has an OBS account.

+

Authorized users can use the AK and SK to access OBS.

+

OBS_GRANTEE_TYPE_ALL_USERS

+

All users can access buckets or objects, including anonymous users.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
Table 23 obs_permission

Value

+

Description

+

OBS_PERMISSION_READ

+

Read permission. A grantee with this permission for a bucket can obtain the list of objects in and metadata of the bucket.

+

A grantee with this permission for an object can obtain the object content and metadata.

+

OBS_PERMISSION_WRITE

+

Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object in the bucket.

+

This permission is not available for objects.

+

OBS_PERMISSION_READ_ACP

+

ACP read permission. A grantee with this permission can obtain the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

OBS_PERMISSION_WRITE_ACP

+

ACP write permission. A grantee with this permission can update the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object.

+

OBS_PERMISSION_FULL_CONTROL

+

Full control permission. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.

+

A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object.

+
+
+ +
+ + + + + + + + + + +
Table 24 obs_bucket_delivered

Value

+

Description

+

BUCKET_DELIVERED_FALSE

+

A bucket ACL is not applied to the objects in the bucket.

+

BUCKET_DELIVERED_TRUE

+

A bucket ACL is applied to the objects in the bucket.

+
+
+
+

Code Examples: Setting an Object Version ACL

This example sets the ACL for an object version using set_object_acl.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to set the ACL for an object version using set_object_acl:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Define the ACL of an object version.
+    manager_acl_info aclinfo;
+    memset(&aclinfo, 0, sizeof(aclinfo));
+    aclinfo.object_info.key = "example_source_object_key";
+    aclinfo.object_info.version_id = "G00111934EAA2CE900004016129AC990";
+    aclinfo.owner_id = "1******************************a";
+    // Set the ACL.
+    int acl_grant_count = 1;
+    aclinfo.acl_grant_count_return = &acl_grant_count;
+    aclinfo.acl_grants = (obs_acl_grant*)malloc(sizeof(obs_acl_grant) * acl_grant_count);
+    // Set the tenant ID of the authorized account (canonical_user.id).
+    strcpy(aclinfo.acl_grants[0].grantee.canonical_user.id, "0******************************0");
+    strcpy(aclinfo.acl_grants[0].grantee.canonical_user.display_name, "name1");
+    aclinfo.acl_grants[0].grantee_type = OBS_GRANTEE_TYPE_CANONICAL_USER;
+    // Specify the ACL. The read permission is used as an example.
+    aclinfo.acl_grants[0].permission = OBS_PERMISSION_READ;
+    // Set the ACL.
+    set_object_acl(&options, &aclinfo, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("set object acl successfully. \n");
+    }
+    else
+    {
+        printf("set object acl failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    free(aclinfo.acl_grants);
+    aclinfo.acl_grants = NULL;
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0319.html b/docs/obs_3rd_party/c_sdk/obs_20_0319.html new file mode 100644 index 000000000..b9ab65324 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0319.html @@ -0,0 +1,2338 @@ + + +

Obtaining the ACL of an Object Version

+

Function

OBS provides access control over buckets. You can use an access policy to define whether a user can perform certain operations on a specific bucket. OBS access control can be implemented using IAM permissions, bucket policies, and ACLs (including bucket and object ACLs).

+

A versioned object ACL grants permissions to another account and its IAM users, rather than the current account and its IAM users. Authorization is performed based on objects. An ACL policy is set for an object. Therefore, you must specify the object name when setting an ACL policy. The permissions granted by a versioned object ACL include the view and edit access to the object and the set ACL.

+

This API obtains the ACL of an object version.

+
+

Restrictions

  • To obtain an object ACL, you must be the bucket owner or have the required permission (obs:object:GetObjectAcl in IAM or GetObjectAcl in a bucket policy).
+
+

Method

void get_object_acl(const obs_options *options, manager_acl_info *aclinfo, obs_response_handler *handler, void *callback_data);
+
+

Request Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1 List of request parameters

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

options

+

constobs_options*

+

Yes

+

Explanation:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

aclinfo

+

manager_acl_info *

+

Yes

+

Explanation:

+

Structure for managing ACL permission information

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 manager_acl_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

If the object is not a versioned object, set the version to NULL.

+

owner_id

+

char *

+

Yes

+

Explanation:

+

Account (domain) ID of the bucket owner.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the account ID of the bucket owner, see How Do I Get My Account ID and User ID?

+

Default value:

+

None

+

owner_display_name

+

char *

+

Yes

+

Explanation:

+

Display name of a user

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

acl_grant_count_return

+

int *

+

Yes

+

Explanation:

+

Length of the acl_grants array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

object_delivered

+

obs_object_delivered

+

Yes

+

Explanation:

+

Whether the ACL of the bucket applies to its objects

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_object_delivered.

+

Default value:

+

OBJECT_DELIVERED_TRUE (The ACL of the bucket applies to its objects.)

+

acl_grants

+

obs_acl_grant *

+

Yes

+

Explanation:

+

Permission information structure.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 19 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 20 obs_object_delivered

Value

+

Description

+

OBJECT_DELIVERED_TRUE

+

The ACL of the bucket applies to its objects.

+

OBJECT_DELIVERED_FALSE

+

The ACL of the bucket does not apply to its objects.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_acl_grant

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

grantee_type

+

obs_grantee_type

+

Yes

+

Explanation:

+

Description of the authorized user type

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_grantee_type.

+

grantee.canonical_user.id

+

char[]

+

No

+

Explanation:

+

User ID of the authorized user.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the ID of an authorized user, see How Do I Get My Account ID and User ID?.

+

Default value:

+

None

+

permission

+

obs_permission

+

Yes

+

Explanation:

+

Bucket ACL.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_permission.

+

bucket_delivered

+

obs_bucket_delivered

+

Yes

+

Explanation:

+

Whether the bucket ACL is applied to the objects in the bucket

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_bucket_delivered.

+

Default value:

+

BUCKET_DELIVERED_FALSE (The ACL of the bucket does not apply to its objects.)

+
+
+ +
+ + + + + + + + + + +
Table 22 obs_grantee_type

Value

+

Description

+

OBS_GRANTEE_TYPE_CANONICAL_USER

+

An OBS user. Bucket or object permissions can be granted to any user who has an OBS account.

+

Authorized users can use the AK and SK to access OBS.

+

OBS_GRANTEE_TYPE_ALL_USERS

+

All users can access buckets or objects, including anonymous users.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
Table 23 obs_permission

Value

+

Description

+

OBS_PERMISSION_READ

+

Read permission. A grantee with this permission for a bucket can obtain the list of objects in and metadata of the bucket.

+

A grantee with this permission for an object can obtain the object content and metadata.

+

OBS_PERMISSION_WRITE

+

Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object in the bucket.

+

This permission is not available for objects.

+

OBS_PERMISSION_READ_ACP

+

ACP read permission. A grantee with this permission can obtain the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

OBS_PERMISSION_WRITE_ACP

+

ACP write permission. A grantee with this permission can update the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object.

+

OBS_PERMISSION_FULL_CONTROL

+

Full control permission. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.

+

A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object.

+
+
+ +
+ + + + + + + + + + +
Table 24 obs_bucket_delivered

Value

+

Description

+

BUCKET_DELIVERED_FALSE

+

A bucket ACL is not applied to the objects in the bucket.

+

BUCKET_DELIVERED_TRUE

+

A bucket ACL is applied to the objects in the bucket.

+
+
+
+

Code Examples: Obtaining the ACL of an Object Version

This example obtains the ACL of an object version using get_object_acl.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+manager_acl_info* malloc_acl_info();
+void free_acl_info(manager_acl_info **acl); 
+void print_acl(manager_acl_info* acl);
+int main()
+{
+    // The following code shows how to obtain the ACL of an object version using get_object_acl:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    options.bucket_options.protocol = OBS_PROTOCOL_HTTP;
+    obs_response_handler response_handler =
+    {
+        &response_properties_callback, &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Object ACL information
+    manager_acl_info *aclinfo = malloc_acl_info();
+    aclinfo->object_info.key = "example_source_object_key";
+    aclinfo->object_info.version_id = "G00111934EAA2CE900004016129AC990";
+    // Obtain the object ACL.
+    get_object_acl(&options, aclinfo, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("get object acl successfully. \n");
+        print_acl(aclinfo);
+    }
+    else
+    {
+        printf("get object acl failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Free the memory.
+    free_acl_info(&aclinfo);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+void print_acl(manager_acl_info* acl) {
+    if (acl == NULL) {
+        printf("acl is NULL.\n");
+        return;
+    }
+    printf("object key :%s\n", acl->object_info.key);
+    printf("object version_id :%s\n", acl->object_info.version_id);
+    printf("object owner_id :%s\n", acl->owner_id);
+    printf("object owner_display_name :%s\n", acl->owner_display_name);
+    switch (acl->object_delivered)
+    {
+    case OBJECT_DELIVERED_TRUE:
+        printf("object acl delivered.\n");
+        break;
+    default:
+        printf("object acl not delivered.\n");
+        break;
+    }
+    if (acl->acl_grant_count_return == NULL) {
+        printf("acl_grant_count_return is NULL.\n");
+        return;
+    }
+    printf("object acl_grant_count :%d\n", *acl->acl_grant_count_return);
+    if (acl->acl_grants == NULL) {
+        printf("acl_grants is NULL.\n");
+        return;
+    }
+    for (int i = 0; i < *acl->acl_grant_count_return; ++i) {
+        obs_acl_grant* acl_grant = acl->acl_grants + i;
+        printf("acl %d\n", i + 1);
+        switch (acl_grant->bucket_delivered)
+        {
+        case BUCKET_DELIVERED_TRUE:
+            printf("object acl delivered from bucket.\n");
+            break;
+        default:
+            printf("object acl not delivered from bucket.\n");
+            break;
+        }
+        switch (acl_grant->grantee_type)
+        {
+        case OBS_GRANTEE_TYPE_CANONICAL_USER:
+            printf("object acl grantee_type is OBS_GRANTEE_TYPE_CANONICAL_USER.\n");
+            break;
+        case OBS_GRANTEE_TYPE_ALL_OBS_USERS:
+            printf("object acl grantee_type is OBS_GRANTEE_TYPE_ALL_OBS_USERS.\n");
+            break;
+        case OBS_GRANTEE_TYPE_ALL_USERS:
+            printf("object acl grantee_type is OBS_GRANTEE_TYPE_ALL_USERS.\n");
+            break;
+        case OBS_GRANTEE_TYPE_LOG_DELIVERY:
+            printf("object acl grantee_type is OBS_GRANTEE_TYPE_LOG_DELIVERY.\n");
+            break;
+        default:
+            printf("object acl grantee_type is unknown.\n");
+            break;
+        }
+        switch (acl_grant->permission)
+        {
+        case OBS_PERMISSION_READ:
+            printf("object acl grantee_type is OBS_PERMISSION_READ.\n");
+            break;
+        case OBS_PERMISSION_WRITE:
+            printf("object acl grantee_type is OBS_PERMISSION_WRITE.\n");
+            break;
+        case OBS_PERMISSION_READ_ACP:
+            printf("object acl grantee_type is OBS_PERMISSION_READ_ACP.\n");
+            break;
+        case OBS_PERMISSION_WRITE_ACP:
+            printf("object acl grantee_type is OBS_PERMISSION_WRITE_ACP.\n");
+            break;
+        case OBS_PERMISSION_FULL_CONTROL:
+            printf("object acl grantee_type is OBS_PERMISSION_FULL_CONTROL.\n");
+            break;
+        default:
+            printf("object acl grantee_type is unknown.\n");
+            break;
+        }
+        printf("acl_grant->grantee.canonical_user.display_name: %s\n", acl_grant->grantee.canonical_user.display_name);
+        printf("acl_grant->grantee.canonical_user.id: %s\n", acl_grant->grantee.canonical_user.id);
+    }
+}
+manager_acl_info* malloc_acl_info()
+{
+    manager_acl_info *aclinfo = (manager_acl_info*)malloc(sizeof(manager_acl_info));
+    memset(aclinfo, 0, sizeof(manager_acl_info));
+    size_t acl_grants_size = OBS_MAX_ACL_GRANT_COUNT * sizeof(obs_acl_grant);
+    aclinfo->acl_grants = (obs_acl_grant*)malloc(acl_grants_size);
+    memset(aclinfo->acl_grants, 0, acl_grants_size);
+    aclinfo->acl_grant_count_return = (int*)malloc(sizeof(int));
+    *(aclinfo->acl_grant_count_return) = 0;
+    size_t owner_id_size = (OBS_MAX_GRANTEE_USER_ID_SIZE + 1) * sizeof(char);
+    size_t owner_display_name_size = (OBS_MAX_GRANTEE_USER_ID_SIZE + 1) * sizeof(char);
+    aclinfo->owner_id = (char *)malloc(owner_id_size);
+    memset(aclinfo->owner_id, 0, owner_id_size);
+    aclinfo->owner_display_name = (char *)malloc(owner_display_name_size);
+    memset(aclinfo->owner_display_name, 0, owner_display_name_size);
+    return aclinfo;
+}
+void free_acl_info(manager_acl_info **acl)
+{
+    manager_acl_info *aclinfo = *acl;
+    free(aclinfo->acl_grants);
+    free(aclinfo->owner_display_name);
+    free(aclinfo->owner_id);
+    free(aclinfo->acl_grant_count_return);
+    free(aclinfo);
+}
+
+
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0400.html b/docs/obs_3rd_party/c_sdk/obs_20_0400.html new file mode 100644 index 000000000..d8ea92c63 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0400.html @@ -0,0 +1,19 @@ + + +

Object Upload

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0401.html b/docs/obs_3rd_party/c_sdk/obs_20_0401.html new file mode 100644 index 000000000..21827d341 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0401.html @@ -0,0 +1,2908 @@ + + +

Uploading an Object - Streaming

+

Function

This API uploads a local file to OBS over the Internet. You can upload text, pictures, videos, or any other types of files.

+

You can upload texts, images, videos, or any other types of files smaller than 5 GB.

+

You can call put_object to upload the data streams to OBS.

+
+

Restrictions

  • To upload an object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • The object size in a single upload ranges from 0 to 5 GB.
  • To upload objects larger than 5 GB, multipart uploads should be used.
+
+

Method

1
+2
+3
+4
void put_object(const obs_options *options, char *key, uint64_t content_length,
+                         obs_put_properties *put_properties,
+                         server_side_encryption_params *encryption_params,
+                         obs_put_object_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

content_length

+

uint64_t

+

Yes

+

Explanation:

+

Length of the object content

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

If this parameter is not specified, the SDK automatically calculates the size of the object.

+

put_properties

+

obs_put_properties*

+

Yes

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Encryption setting of the uploaded object

+

Restrictions:

+

None

+

handler

+

obs_put_object_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 5 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+

None

+

Value range:

+
  • An integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header, the response message must contain this header.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

Default value:

+

None

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+

None

+

Value range:

+
  • An integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + +
Table 14 obs_az_redundancy

Value

+

Description

+

OBS_REDUNDANCY_1AZ

+

By default, a single-AZ bucket is created.

+

OBS_REDUNDANCY_3AZ

+

A 3-AZ bucket is created.

+
+
+ +
+ + + + + + + + + + + + + +
Table 15 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in callbackBodyType.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request.

+

Restrictions:

+

None

+

Value range:

+
  • application/x-www-form-urlencoded
  • application/json
+

Default value:

+

If no value is specified, the default value application/json is used.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 18 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that the server-side encryption used for objects is SSE-KMS.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 20 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_put_object_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

put_object_data_callback

+

obs_put_object_data_callback *

+

Yes

+

Explanation:

+

Callback function pointer, which is used to copy the data to be uploaded to the data upload buffer.

+

Restrictions:

+

None

+

progress_callback

+

obs_progress_callback_internal *

+

Yes

+

Explanation:

+

Pointer to the progress callback function.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_put_object_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

buffer_size

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

buffer

+

char *

+

Yes

+

Explanation:

+

Buffer for storing the data to be uploaded. The data to be uploaded is copied to this buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_progress_callback_internal

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

now

+

uint64_t

+

Yes

+

Explanation:

+

Number of bytes that have been uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

total

+

uint64_t

+

Yes

+

Explanation:

+

Total number of bytes to be uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 24 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 25 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 26 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 28 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 29 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 30 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Streaming Upload

This example calls put_object to upload an object in a stream.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
#include "eSDKOBS.h"
+#include <stdio.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);
+void put_buffer_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
+typedef struct put_buffer_object_callback_data
+{
+    char *put_buffer;
+    uint64_t buffer_size;
+    uint64_t cur_offset;
+    obs_status ret_status;
+} put_buffer_object_callback_data;
+int put_buffer_data_callback(int buffer_size, char *buffer, void *callback_data);
+char* generate_upload_buffer(uint64_t buffer_size);
+int main()
+{
+    // The following code shows how to use put_object to upload an object in the stream:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Initialize the properties of the object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    //Initialize the structure for storing the uploaded data.
+    put_buffer_object_callback_data data;
+    memset(&data, 0, sizeof(put_buffer_object_callback_data));
+    // Set the buffer size.
+    data.buffer_size = 10 * 1024 * 1024;
+    // Create a simulated data buffer for the streaming upload and assign the value to the data upload structure.
+    data.put_buffer = generate_upload_buffer(data.buffer_size);
+    if (NULL == data.put_buffer) {
+        printf("generate put buffer failed. \n");
+        return;
+    }
+    // Name of the object to be uploaded
+    char *key = "example_put_buffer_test.txt";
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_buffer_complete_callback },
+          &put_buffer_data_callback
+    };
+    put_object(&options, key, data.buffer_size, &put_properties, 0, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from buffer successfully. \n");
+    }
+    else
+    {
+        printf("put object from buffer failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    // Release the buffer.
+    free(data.put_buffer);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void put_buffer_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
+{
+    if (callback_data) {
+        put_buffer_object_callback_data *data = (put_buffer_object_callback_data *)callback_data;
+        data->ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+int put_buffer_data_callback(int buffer_size, char *buffer, void *callback_data)
+{
+    put_buffer_object_callback_data *data =
+        (put_buffer_object_callback_data *)callback_data;
+    int toRead = 0;
+    if (data->buffer_size) {
+        toRead = ((data->buffer_size > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->buffer_size);
+        memcpy_s(buffer, buffer_size, data->put_buffer + data->cur_offset, toRead);
+    }
+    uint64_t originalContentLength = data->buffer_size;
+    data->buffer_size -= toRead;
+    data->cur_offset += toRead;
+    if (data->buffer_size) {
+        printf("%llu bytes remaining ", (unsigned long long)data->buffer_size);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->buffer_size) * 100) / originalContentLength));
+    }
+    return toRead;
+}
+// Create a simulated streaming upload buffer.
+char* generate_upload_buffer(uint64_t buffer_size) {
+    void* upload_buffer = NULL;
+    if (buffer_size > 0) {
+        upload_buffer = malloc(buffer_size);
+        if (upload_buffer != NULL) {
+            memset(upload_buffer, 't', buffer_size);
+        }
+    }
+    return upload_buffer;
+}
+
+
+
+
+
+
+
+
Parent topic: Object Upload
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0402.html b/docs/obs_3rd_party/c_sdk/obs_20_0402.html new file mode 100644 index 000000000..6d8ff2730 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0402.html @@ -0,0 +1,2887 @@ + + +

Uploading an Object - File-Based

+

Function

This API uploads local files to OBS over the Internet. You can upload text, pictures, videos, or any other types of files.

+

This API uploads an object in text to a bucket.

+
+

Restrictions

  • To upload an object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • The object size in a single upload ranges from 0 to 5 GB.
  • To upload objects larger than 5 GB, multipart uploads should be used.
+
+

Method

1
+2
+3
+4
void put_object(const obs_options *options, char *key, uint64_t content_length,
+                         obs_put_properties *put_properties,
+                         server_side_encryption_params *encryption_params,
+                         obs_put_object_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

content_length

+

uint64_t

+

Yes

+

Explanation:

+

Length of the object content

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

If this parameter is not specified, the SDK automatically calculates the size of the object.

+

put_properties

+

obs_put_properties*

+

Yes

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Encryption setting of the uploaded object

+

Restrictions:

+

None

+

handler

+

obs_put_object_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 5 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+

None

+

Value range:

+
  • An integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header, the response message must contain this header.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

Default value:

+

None

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+

None

+

Value range:

+
  • An integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + +
Table 14 obs_az_redundancy

Value

+

Description

+

OBS_REDUNDANCY_1AZ

+

By default, a single-AZ bucket is created.

+

OBS_REDUNDANCY_3AZ

+

A 3-AZ bucket is created.

+
+
+ +
+ + + + + + + + + + + + + +
Table 15 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in callbackBodyType.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request.

+

Restrictions:

+

None

+

Value range:

+
  • application/x-www-form-urlencoded
  • application/json
+

Default value:

+

If no value is specified, the default value application/json is used.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 18 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that the server-side encryption used for objects is SSE-KMS.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 20 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_put_object_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

put_object_data_callback

+

obs_put_object_data_callback *

+

Yes

+

Explanation:

+

Callback function pointer, which is used to copy the data to be uploaded to the data upload buffer.

+

Restrictions:

+

None

+

progress_callback

+

obs_progress_callback_internal *

+

Yes

+

Explanation:

+

Pointer to the progress callback function.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_put_object_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

buffer_size

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

buffer

+

char *

+

Yes

+

Explanation:

+

Buffer for storing the data to be uploaded. The data to be uploaded is copied to this buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_progress_callback_internal

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

now

+

uint64_t

+

Yes

+

Explanation:

+

Number of bytes that have been uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

total

+

uint64_t

+

Yes

+

Explanation:

+

Total number of bytes to be uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 24 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 25 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 26 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 28 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 29 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 30 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Uploading a File

This example uploads a file using put_object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data);
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct put_file_object_callback_data
+{
+    FILE *infile;
+    uint64_t content_length;
+    obs_status ret_status;
+} put_file_object_callback_data;
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data);
+int main()
+{
+    // The following example shows how to upload a file using put_object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Initialize the properties of the object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Name of the object to be uploaded
+    char *key = "example_put_file_test";
+    // The uploaded file
+    char file_name[256] = "./example_local_file_test.txt";
+    uint64_t content_length = 0;
+    // Initialize the structure for storing the uploaded data.
+    put_file_object_callback_data data;
+    memset(&data, 0, sizeof(put_file_object_callback_data));
+    // Open the file and obtain the file length.
+    content_length = open_file_and_get_length(file_name, &data);
+    // Set the callback function.
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_file_complete_callback },
+        &put_file_data_callback
+    };
+    put_object(&options, key, content_length, &put_properties, 0, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from file successfully. \n");
+    }
+    else
+    {
+        printf("put object failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    if (data.infile != NULL) {
+        fclose(data.infile);
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data)
+{
+    put_file_object_callback_data *data =
+        (put_file_object_callback_data *)callback_data;
+    int ret = 0;
+    if (data->content_length) {
+        int toRead = ((data->content_length > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->content_length);
+        ret = fread(buffer, 1, toRead, data->infile);
+    }
+    uint64_t originalContentLength = data->content_length;
+    data->content_length -= ret;
+    if (data->content_length) {
+        printf("%llu bytes remaining ", (unsigned long long)data->content_length);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->content_length) * 100) / originalContentLength));
+    }
+    return ret;
+}
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    put_file_object_callback_data *data = (put_file_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data)
+{
+    uint64_t content_length = 0;
+    const char *body = 0;
+    if (!content_length)
+    {
+        struct stat statbuf;
+        if (stat(localfile, &statbuf) == -1)
+        {
+            fprintf(stderr, "\nERROR: Failed to stat file %s: ",
+                localfile);
+            return 0;
+        }
+        content_length = statbuf.st_size;
+    }
+    if (!(data->infile = fopen(localfile, "rb")))
+    {
+        fprintf(stderr, "\nERROR: Failed to open input file %s: ",
+            localfile);
+        return 0;
+    }
+    data->content_length = content_length;
+    return content_length;
+}
+
+
+
+
  • The content to be uploaded cannot exceed 5 GB.
  • When uploading file streams, you must open files in rb or rb+ mode.
+
+
+
+
+
+
Parent topic: Object Upload
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0403.html b/docs/obs_3rd_party/c_sdk/obs_20_0403.html new file mode 100644 index 000000000..8a0afd7e4 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0403.html @@ -0,0 +1,2821 @@ + + +

Creating a Folder

+

Function

This API creates a folder in an existing bucket to manage data in OBS.

+

OBS does not involve folders like in a file system. All elements in buckets are objects. To create a folder in OBS is essentially to create an object whose size is 0 and whose name ends with a slash (/). Such objects are no different from other objects (you can perform normal operations on them such as download and delete), except that they are displayed as folders in OBS console.

+
+

Restrictions

  • To create a folder, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • To create a folder in OBS is essentially to create an object whose size is 0 and whose name ends with a slash (/).
  • To create a multi-level folder, you only need to create the folder of the last level. For example, if you want to create a folder named src1/src2/src3/, create it directly. You do not need to first create the src1/ and src1/src2/ folders.
+
+

Method

1
+2
+3
+4
void put_object(const obs_options *options, char *key, uint64_t content_length,
+                         obs_put_properties *put_properties,
+                         server_side_encryption_params *encryption_params,
+                         obs_put_object_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

content_length

+

uint64_t

+

Yes

+

Explanation:

+

Length of the object content

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

If this parameter is not specified, the SDK automatically calculates the size of the object.

+

put_properties

+

obs_put_properties*

+

Yes

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Encryption setting of the uploaded object

+

Restrictions:

+

None

+

handler

+

obs_put_object_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 5 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+

None

+

Value range:

+
  • An integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header, the response message must contain this header.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

Default value:

+

None

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+

None

+

Value range:

+
  • An integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + +
Table 14 obs_az_redundancy

Value

+

Description

+

OBS_REDUNDANCY_1AZ

+

By default, a single-AZ bucket is created.

+

OBS_REDUNDANCY_3AZ

+

A 3-AZ bucket is created.

+
+
+ +
+ + + + + + + + + + + + + +
Table 15 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in callbackBodyType.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request.

+

Restrictions:

+

None

+

Value range:

+
  • application/x-www-form-urlencoded
  • application/json
+

Default value:

+

If no value is specified, the default value application/json is used.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 18 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that the server-side encryption used for objects is SSE-KMS.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 20 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_put_object_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

put_object_data_callback

+

obs_put_object_data_callback *

+

Yes

+

Explanation:

+

Callback function pointer, which is used to copy the data to be uploaded to the data upload buffer.

+

Restrictions:

+

None

+

progress_callback

+

obs_progress_callback_internal *

+

Yes

+

Explanation:

+

Pointer to the progress callback function.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_put_object_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

buffer_size

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

buffer

+

char *

+

Yes

+

Explanation:

+

Buffer for storing the data to be uploaded. The data to be uploaded is copied to this buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_progress_callback_internal

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

now

+

uint64_t

+

Yes

+

Explanation:

+

Number of bytes that have been uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

total

+

uint64_t

+

Yes

+

Explanation:

+

Total number of bytes to be uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 24 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 25 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 26 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 28 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 29 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 30 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Creating a Folder

This example creates a folder, which is an object whose size is 0 and whose name ends with a slash (/).
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data);
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct put_file_object_callback_data
+{
+    FILE *infile;
+    uint64_t content_length;
+    obs_status ret_status;
+} put_file_object_callback_data;
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data);
+int main()
+{
+    // The following code shows how to create a folder, which is an object whose size is 0 and whose name ends with a slash (/):
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Initialize the properties of the object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Name of the object to be uploaded
+    char *key = "example_folder/";
+    // Initialize the structure for storing the uploaded data.
+    put_file_object_callback_data data;
+    memset(&data, 0, sizeof(put_file_object_callback_data));
+    // Set the callback function.
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_file_complete_callback },
+        &put_file_data_callback
+    };
+    put_object(&options, key, 0, &put_properties, 0, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from file successfully. \n");
+    }
+    else
+    {
+        printf("put object failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data)
+{
+    put_file_object_callback_data *data =
+        (put_file_object_callback_data *)callback_data;
+    int ret = 0;
+    if (data->content_length) {
+        int toRead = ((data->content_length > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->content_length);
+        ret = fread(buffer, 1, toRead, data->infile);
+    }
+    uint64_t originalContentLength = data->content_length;
+    data->content_length -= ret;
+    if (data->content_length) {
+        printf("%llu bytes remaining ", (unsigned long long)data->content_length);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->content_length) * 100) / originalContentLength));
+    }
+    return ret;
+}
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    put_file_object_callback_data *data = (put_file_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+
+
+
+
+
+
+
+
Parent topic: Object Upload
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0404.html b/docs/obs_3rd_party/c_sdk/obs_20_0404.html new file mode 100644 index 000000000..2be7d85f0 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0404.html @@ -0,0 +1,3463 @@ + + +

Setting Object Properties

+

Function

This API sets properties for an object when uploading it. Object properties include the object length, MIME type, MD5 value (for verification), storage class, and custom object metadata. You can configure properties for an object that is being uploaded in streaming, file-based, or multipart mode or when copying an object.

+
+

Restrictions

  • To configure object properties, you must be the bucket owner or have the required permission (obs:object:ModifyObjectMetaData in IAM or ModifyObjectMetaData in a bucket policy).
+
  • An object can have multiple pieces of metadata. The size of the metadata cannot exceed 8 KB in total.
  • Currently, metadata names only support ASCII characters. Non-ASCII characters must be Base64-encoded.
  • If you do not set a storage class for an object, the object will inherit the storage class of its bucket by default.
+
+

Method

void set_object_metadata(const obs_options *options, obs_object_info *object_info, 
+	obs_put_properties *put_properties,
+	server_side_encryption_params *encryption_params,
+	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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

put_properties

+

obs_put_properties*

+

Yes

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Encryption setting of the uploaded object

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket properties comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

For details, see Creating Access Keys.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Value of the Expires header in the OBS request. It specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 15 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 18 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 20 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 21 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 22 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 25 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 26 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Setting the MIME Type for an Object

This example sets the MIME type when uploading a file. If the MIME type is not set, the C SDK will automatically identify the MIME type based on the extension of the file. For example, the MIME type of .xml files is application/xml and that of .html files is text/html.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data);
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct put_file_object_callback_data
+{
+    FILE *infile;
+    uint64_t content_length;
+    obs_status ret_status;
+} put_file_object_callback_data;
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data);
+int main()
+{
+    // The following code uses file upload as an example to describe how to set the MIME type for an object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Initialize the properties of the object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Name of the object to be uploaded
+    char *key = "example_put_file_test";
+    // Uploaded file
+    char file_name[256] = "./example_local_file_test.txt";
+    uint64_t content_length = 0;
+    // Initialize the structure for storing the uploaded data.
+    put_file_object_callback_data data;
+    memset(&data, 0, sizeof(put_file_object_callback_data));
+    // Open the file and obtain the file length.
+    content_length = open_file_and_get_length(file_name, &data);
+    // Set the callback function.
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_file_complete_callback },
+        &put_file_data_callback
+    };
+    // Set the MIME type.
+    put_properties.content_type = "text/plain";
+    put_object(&options, key, content_length, &put_properties, 0, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from file successfully. \n");
+    }
+    else
+    {
+        printf("put object failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    if (data.infile != NULL) {
+        fclose(data.infile);
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data)
+{
+    put_file_object_callback_data *data =
+        (put_file_object_callback_data *)callback_data;
+    int ret = 0;
+    if (data->content_length) {
+        int toRead = ((data->content_length > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->content_length);
+        ret = fread(buffer, 1, toRead, data->infile);
+    }
+    uint64_t originalContentLength = data->content_length;
+    data->content_length -= ret;
+    if (data->content_length) {
+        printf("%llu bytes remaining ", (unsigned long long)data->content_length);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->content_length) * 100) / originalContentLength));
+    }
+    return ret;
+}
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    put_file_object_callback_data *data = (put_file_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data)
+{
+    uint64_t content_length = 0;
+    const char *body = 0;
+    if (!content_length)
+    {
+        struct stat statbuf;
+        if (stat(localfile, &statbuf) == -1)
+        {
+            fprintf(stderr, "\nERROR: Failed to stat file %s: ",
+                localfile);
+            return 0;
+        }
+        content_length = statbuf.st_size;
+    }
+    if (!(data->infile = fopen(localfile, "rb")))
+    {
+        fprintf(stderr, "\nERROR: Failed to open input file %s: ",
+            localfile);
+        return 0;
+    }
+    data->content_length = content_length;
+    return content_length;
+}
+
+
+
+
+

Code Examples: Setting the Storage Class for an Object

This example sets the storage class for an object during upload.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data);
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct put_file_object_callback_data
+{
+    FILE *infile;
+    uint64_t content_length;
+    obs_status ret_status;
+} put_file_object_callback_data;
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data);
+int main()
+{
+    // The following example shows how to set the storage class for an object during upload:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    //Set the storage class to Cold.
+    options.bucket_options.storage_class = OBS_STORAGE_CLASS_GLACIER;
+    // Initialize the properties of the object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Name of the object to be uploaded
+    char *key = "example_put_file_test_cold";
+    // Uploaded file
+    char file_name[256] = "./example_local_file_test.txt";
+    uint64_t content_length = 0;
+    // Initialize the structure for storing the uploaded data.
+    put_file_object_callback_data data;
+    memset(&data, 0, sizeof(put_file_object_callback_data));
+    // Open the file and obtain the file length.
+    content_length = open_file_and_get_length(file_name, &data);
+    // Set the callback function.
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_file_complete_callback },
+        &put_file_data_callback
+    };
+    put_object(&options, key, content_length, &put_properties, 0, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from file successfully. \n");
+    }
+    else
+    {
+        printf("put object failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    if (data.infile != NULL) {
+        fclose(data.infile);
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data)
+{
+    put_file_object_callback_data *data =
+        (put_file_object_callback_data *)callback_data;
+    int ret = 0;
+    if (data->content_length) {
+        int toRead = ((data->content_length > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->content_length);
+        ret = fread(buffer, 1, toRead, data->infile);
+    }
+    uint64_t originalContentLength = data->content_length;
+    data->content_length -= ret;
+    if (data->content_length) {
+        printf("%llu bytes remaining ", (unsigned long long)data->content_length);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->content_length) * 100) / originalContentLength));
+    }
+    return ret;
+}
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    put_file_object_callback_data *data = (put_file_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data)
+{
+    uint64_t content_length = 0;
+    const char *body = 0;
+    if (!content_length)
+    {
+        struct stat statbuf;
+        if (stat(localfile, &statbuf) == -1)
+        {
+            fprintf(stderr, "\nERROR: Failed to stat file %s: ",
+                localfile);
+            return 0;
+        }
+        content_length = statbuf.st_size;
+    }
+    if (!(data->infile = fopen(localfile, "rb")))
+    {
+        fprintf(stderr, "\nERROR: Failed to open input file %s: ",
+            localfile);
+        return 0;
+    }
+    data->content_length = content_length;
+    return content_length;
+}
+
+
+
+
+

Code Examples: Customizing Metadata for an Object

This example customizes metadata for an object during upload.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data);
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct put_file_object_callback_data
+{
+    FILE *infile;
+    uint64_t content_length;
+    obs_status ret_status;
+} put_file_object_callback_data;
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data);
+int main()
+{
+    // The following example shows how to customize metadata for an object during upload:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Initialize the properties of the object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Name of the object to be uploaded
+    char *key = "example_put_file_test_with_matadatas";
+    // Uploaded file
+    char file_name[256] = "./example_local_file_test.txt";
+    uint64_t content_length = 0;
+    // Initialize the structure for storing the uploaded data.
+    put_file_object_callback_data data;
+    memset(&data, 0, sizeof(put_file_object_callback_data));
+    // Open the file and obtain the file length.
+    content_length = open_file_and_get_length(file_name, &data);
+    // Set the callback function.
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_file_complete_callback },
+        &put_file_data_callback
+    };
+    //Set the custom metadata.
+    obs_name_value example_matadatas[2] = {0};
+    example_matadatas[0].name = "example-property1";
+    example_matadatas[0].value = "example-property-value1";
+    example_matadatas[1].name = "example-property2";
+    example_matadatas[1].value = "example-property-value2";
+    put_properties.meta_data = &example_matadatas;
+    //Set the custom metadata count.
+    put_properties.meta_data_count = 2;
+    put_object(&options, key, content_length, &put_properties, 0, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from file successfully. \n");
+    }
+    else
+    {
+        printf("put object failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    if (data.infile != NULL) {
+        fclose(data.infile);
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data)
+{
+    put_file_object_callback_data *data =
+        (put_file_object_callback_data *)callback_data;
+    int ret = 0;
+    if (data->content_length) {
+        int toRead = ((data->content_length > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->content_length);
+        ret = fread(buffer, 1, toRead, data->infile);
+    }
+    uint64_t originalContentLength = data->content_length;
+    data->content_length -= ret;
+    if (data->content_length) {
+        printf("%llu bytes remaining ", (unsigned long long)data->content_length);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->content_length) * 100) / originalContentLength));
+    }
+    return ret;
+}
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    put_file_object_callback_data *data = (put_file_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data)
+{
+    uint64_t content_length = 0;
+    const char *body = 0;
+    if (!content_length)
+    {
+        struct stat statbuf;
+        if (stat(localfile, &statbuf) == -1)
+        {
+            fprintf(stderr, "\nERROR: Failed to stat file %s: ",
+                localfile);
+            return 0;
+        }
+        content_length = statbuf.st_size;
+    }
+    if (!(data->infile = fopen(localfile, "rb")))
+    {
+        fprintf(stderr, "\nERROR: Failed to open input file %s: ",
+            localfile);
+        return 0;
+    }
+    data->content_length = content_length;
+    return content_length;
+}
+
+
+
+
+
+
+
+
Parent topic: Object Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0405.html b/docs/obs_3rd_party/c_sdk/obs_20_0405.html new file mode 100644 index 000000000..b2a8476b8 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0405.html @@ -0,0 +1,2638 @@ + + +

Initiating a Multipart Upload

+

Function

This API initiates a multipart upload and returns a globally unique upload ID. You can use this upload ID in your subsequent requests for uploading, assembling, and listing parts. Initiating multipart upload tasks do not affect existing objects with the same names as the involved objects in those tasks. There can be more than one multipart upload for the same object. Each multipart upload initiation request can contain additional headers such as contentType, contentEncoding, and the headers for ACL and custom metadata. These headers are recorded in the multipart upload metadata.

+

You can use this API to initiate a multipart upload in a specified bucket.

+
+

Restrictions

  • To initiate a multipart upload, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • After initiating a multipart upload and uploading one or more parts, you must assemble the parts or abort the multipart upload to stop being charged for the storage of the uploaded parts.
+
+

Method

1
+2
+3
+4
void initiate_multi_part_upload(const obs_options *options, char *key,int upload_id_return_size,
+        char *upload_id_return, obs_put_properties *put_properties,
+        server_side_encryption_params *encryption_params,
+        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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

upload_id_return_size

+

int

+

Yes

+

Explanation:

+

Size of the cache for the multipart upload ID.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

upload_id_return

+

char *

+

Yes

+

Explanation:

+

Cache of the multipart upload ID.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

put_properties

+

obs_put_properties*

+

No

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Encryption setting of the uploaded object

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

For details, see Creating Access Keys.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Base64-encoded MD5 value of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Value of the Expires header in the OBS request. It specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (downloading from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

If the object has not been modified after the specified time, the request is successful. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Specifies a preset ETag value. If the ETag value of the object to be downloaded or copied is different from the value of this parameter, the request is successful. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 14 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 17 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 19 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 20 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 21 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 25 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 26 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Initiating a Multipart Upload

This example initiates a multipart upload using initiate_multi_part_upload.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to initiate a multipart upload using initiate_multi_part_upload:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Define the cache and size of the multipart upload ID.
+    char upload_id[OBS_COMMON_LEN_256] = { 0 };
+    int upload_id_size = OBS_COMMON_LEN_256;
+    // Set the response callback function.
+    obs_response_handler handler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    // Name of the object to be uploaded in multiparts
+    char *key = "example_multi_part_upload_object_key";
+    // Initiate a multipart upload. Set upload_id below to the value of upload_id_return listed in the parameter table above.
+    obs_status ret_status;
+    initiate_multi_part_upload(&options, key, upload_id_size, upload_id, NULL, NULL, &handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("test init upload part successfully. uploadId= %s\n", upload_id);
+    }
+    else
+    {
+        printf("test init upload part failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Multipart Upload APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0406.html b/docs/obs_3rd_party/c_sdk/obs_20_0406.html new file mode 100644 index 000000000..db873cb85 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0406.html @@ -0,0 +1,2867 @@ + + +

Copying a Part

+

Function

This API uploads a part for a specified multipart upload by copying data to a specified bucket.

+

After initiating a multipart upload task, you can add parts for this task by copying part or all of an existing object in OBS.

+

Assume that you copy a source object and save it as part1. If there is already an existing part called part1, the new part1 will overwrite the existing part1. Then, only the new part1 can be listed. The old part1 is deleted. To prevent accidental deletion, ensure there is no existing object with the same name as the part involved when using this API. The source object remains unchanged during the copy process.

+
+

Restrictions

  • To copy a part, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • You cannot determine whether the operation is successful solely based on status_code returned in the HTTP header. For example, code 200 indicates that the server has received and started to process the request. The copy operation is considered successful only when the response body contains an ETag.
+
+

Method

1
+2
+3
+4
void copy_part(const obs_options *options, char *key, obs_copy_destination_object_info *object_info,
+        obs_upload_part_info *copypart, obs_put_properties *put_properties, 
+        server_side_encryption_params *encryption_params,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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

object_info

+

obs_copy_destination_object_info *

+

Yes

+

Explanation:

+

Identifies a multipart upload.

+

Restrictions:

+

None

+

copypart

+

obs_upload_part_info *

+

Yes

+

Explanation:

+

Information about the part to be uploaded

+

Restrictions:

+

None

+

put_properties

+

obs_put_properties*

+

No

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Configuring server-side encryption

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Value range:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 12 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_copy_destination_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

destination_bucket

+

char *

+

Yes

+

Explanation:

+

Destination bucket to which an object is copied.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

destination_key

+

char *

+

Yes

+

Explanation:

+

Name of the destination object.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

Yes

+

Explanation:

+

Version ID of the source object to be copied.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

last_modified_return

+

int64_t *

+

Yes

+

Explanation:

+

Last time when the object was modified

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag_return_size

+

int

+

Yes

+

Explanation:

+

Length of the ETag returned for copying an object.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag_return

+

char *

+

Yes

+

Explanation:

+

ETag returned for copying an object.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 21 obs_upload_part_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

part_number

+

unsigned int

+

Yes

+

Explanation:

+

Number of the uploaded part.

+

Restrictions:

+

None

+

Value range:

+

An integer ranging from 1 to 10000.

+

Default value:

+

None

+

upload_id

+

int

+

Yes

+

Explanation:

+

ID of a multipart upload task.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Value of the Expires header in the OBS request. It specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (downloading from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length of the file to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

If the object has not been modified after the specified time, the request is successful. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Specifies a preset ETag value. If the ETag value of the object to be downloaded or copied is different from the value of this parameter, the request is successful. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 25 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 26 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 27 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 28 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+
+

Code Examples: Copying a Part

This example copies parts using copy_part.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to copy parts using copy_part:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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";
+    char * destBucketName = "example-bucket-name";
+    options.bucket_options.bucket_name = bucketName;
+    options.bucket_options.protocol = OBS_PROTOCOL_HTTP;
+    // Parameters related to SSE-KMS encryption. If there is no parameter, leave it blank.
+    server_side_encryption_params encryption_params;
+    memset(&encryption_params, 0, sizeof(server_side_encryption_params));
+    // ETag value returned after the part is copied.
+    char etag_return[256] = { 0 };
+    char *key = "example_upload_file_object_key";
+        // Define the part copy information.
+    obs_copy_destination_object_info object_info;
+    memset(&object_info, 0, sizeof(obs_copy_destination_object_info));
+    object_info.destination_bucket = destBucketName;
+    object_info.destination_key = "example_multi_part_upload_object_key";
+    object_info.etag_return = etag_return;
+    object_info.etag_return_size = 256;
+    obs_upload_part_info copypart;
+    memset(©part, 0, sizeof(obs_upload_part_info));
+    // Set the response callback function.
+    obs_response_handler responseHandler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    char* upload_id = "000001930065F7C64014C38C138D654B";
+    uint64_t object_size_total = 145184256;
+    uint64_t part_size_one = 5 * 1024 * 1024;
+    // Copy the first part.
+    copypart.part_number = 1;
+    copypart.upload_id = upload_id;
+    obs_status ret_status = OBS_STATUS_BUTT;
+    //Initialize put_properties.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Copy the first 5 MB of the data in the first part.
+    put_properties.start_byte = 0;
+    put_properties.byte_count = part_size_one;
+    copy_part(&options, key, &object_info, ©part,
+        &put_properties, &encryption_params, &responseHandler, &ret_status);
+    if (OBS_STATUS_OK == ret_status && etag_return[0] != '\0') {
+        printf(" copy part 1 successfully etag:%s. \n", etag_return);
+    }
+    else
+    {
+        printf("copy part 1 failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    memset(etag_return, 0, sizeof(etag_return));
+    // Copy the remaining data in the second part.
+    copypart.part_number = 2;
+    copypart.upload_id = upload_id;
+    ret_status = OBS_STATUS_BUTT;
+    put_properties.start_byte = part_size_one;
+    put_properties.byte_count = object_size_total - part_size_one;
+    copy_part(&options, key, &object_info, ©part,
+        &put_properties, &encryption_params, &responseHandler, &ret_status);
+    if (ret_status == OBS_STATUS_OK && etag_return[0] != '\0') {
+        printf(" copy part 2 successfully etag:%s. \n", etag_return);
+    }
+    else
+    {
+        printf("copy part 2 failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *data =
+            (obs_status *)callback_data;
+        *data = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Multipart Upload APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0407.html b/docs/obs_3rd_party/c_sdk/obs_20_0407.html new file mode 100644 index 000000000..5b2bb5fc9 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0407.html @@ -0,0 +1,3169 @@ + + +

Uploading an Object - Resumable

+

Function

The resumable upload is an encapsulated and enhanced version of the multipart upload used for dealing with possible upload failures of large files when the network connection is unstable or a program crashes. This API splits the file into multiple parts and uploads them individually. The upload result of each part is recorded in a checkpoint file in real time. A success message is returned only when all parts are uploaded. If any parts fail, an error message is returned telling you to call the API again to upload the failed parts. Since the checkpoint file contains the progress of each part, it saves you uploading all parts again in the event of an error.

+

You can call upload_file to perform a resumable upload.

+
+

Restrictions

  • To upload an object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • The file uploaded by the resumable upload API must be at least 100 KB.
  • You must enable the resumable upload option when you use this API, so the progress of the last upload can be obtained for upload resumption.
+
+

Method

1
+2
+3
+4
+5
void upload_file(const obs_options *options, char *key, server_side_encryption_params *encryption_params, 
+    obs_upload_file_configuration *upload_file_config, 
+    obs_upload_file_server_callback server_callback,
+    obs_upload_file_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

upload_file_config

+

obs_upload_file_configuration *

+

Yes

+

Explanation:

+

Configuration of the file upload.

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Encryption setting of the uploaded object

+

Restrictions:

+

None

+

handler

+

obs_upload_file_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

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 your custom callback_data.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

See obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 5 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_upload_file_configuration

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

upload_file

+

char *

+

Yes

+

Explanation:

+

Path of the local file to be uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

part_size

+

uint64_t

+

No

+

Explanation:

+

Part size, in bytes

+

Restrictions:

+

None

+

Value range:

+

100 KB to 5 GB

+

Default value:

+

5 MB

+

check_point_file

+

char *

+

No

+

Explanation:

+

Path of the file that records the upload progress. This parameter is effective only in the resumable mode. If the value of this parameter is left blank, the file will be in the same directory as the local file to be uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

enable_check_point

+

int

+

No

+

Explanation:

+

Whether to enable the resumable mode

+

Restrictions:

+

None

+

Value range:

+
  • 0: The resumable mode is disabled. In this case, this API works as a multipart upload API, and no checkpoint files are generated.
  • 1: The resumable mode is enabled.
+

Default value:

+

0: disabled

+

task_num

+

int

+

No

+

Explanation:

+

Maximum number of parts that can be uploaded concurrently

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

1

+

pause_upload_flag

+

int *

+

No

+

Explanation:

+

Flag indicating that the upload is paused.

+

Restrictions:

+

The value cannot be NULL. If the value is 1, the upload is paused.

+

Value range:

+

None

+

Default value:

+

None

+

put_properties

+

obs_put_properties *

+

Yes

+

Explanation:

+

Object properties.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • The value must be an integer greater than 0.
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + +
Table 14 obs_az_redundancy

Value

+

Description

+

OBS_REDUNDANCY_1AZ

+

By default, a single-AZ bucket is created.

+

OBS_REDUNDANCY_3AZ

+

A 3-AZ bucket is created.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • The value must be an integer greater than 0.
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 16 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 19 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 21 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_upload_file_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

upload_file_callback

+

obs_upload_file_callback *

+

Yes

+

Explanation:

+

The pointer to the callback function, where the callback parameters can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

progress_callback

+

obs_progress_callback *

+

Yes

+

Explanation:

+

Pointer to the progress callback function.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_upload_file_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Request status

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

result_message

+

char *

+

Yes

+

Explanation:

+

Upload result

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

part_count_return

+

int

+

Yes

+

Explanation:

+

Number of parts.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

upload_info_list

+

obs_upload_file_part_info *

+

Yes

+

Explanation:

+

Part information.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_upload_file_part_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

part_num

+

obs_response_handler *

+

Yes

+

Explanation:

+

Part number

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

Yes

+

Explanation:

+

Start position of part creation.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

part_size

+

uint64_t

+

Yes

+

Explanation:

+

Part size.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

status_return

+

part_upload_status

+

Yes

+

Explanation:

+

Part status.

+

Restrictions:

+

None

+

Value range:

+

For details, see part_upload_status.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
Table 25 part_upload_status

Value

+

Description

+

UPLOAD_NOTSTART

+

The upload has not started.

+

UPLOADING

+

Uploading.

+

UPLOAD_FAILED

+

The upload fails.

+

UPLOAD_SUCCESS

+

The file is uploaded.

+

STATUS_BUTT

+

Default status.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 26 obs_progress_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

progress

+

double

+

Yes

+

Explanation:

+

Progress percentage.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

uploadedSize

+

uint64_t

+

Yes

+

Explanation:

+

Number of bytes that have been uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

fileTotalSize

+

uint64_t

+

Yes

+

Explanation:

+

Total number of bytes to be uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 27 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 28 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 29 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 30 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

The value must contain 32 characters.

+

Value range:

+

None

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 31 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 32 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 33 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Resumable Upload

This example calls the resumable upload API to upload a file.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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 completion callback function. 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);
+void uploadFileResultCallback(obs_status status,
+    char *resultMsg,
+    int partCountReturn,
+    obs_upload_file_part_info * uploadInfoList,
+    void *callbackData);
+void test_progress_callback(double progress, uint64_t uploadedSize, uint64_t fileTotalSize, void *callback_data);
+int main()
+{
+    // The following example shows how to use the resumable upload API to upload a file:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    //Initialize the put_properties structure.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    obs_upload_file_configuration uploadFileInfo;
+    memset(&uploadFileInfo, 0, sizeof(obs_upload_file_configuration));
+    uploadFileInfo.check_point_file = 0;
+    uploadFileInfo.enable_check_point = 1;
+    uploadFileInfo.part_size = 5L * 1024 * 1024;
+    uploadFileInfo.task_num = 8;
+    uploadFileInfo.upload_file = "./example_local_file_to_upload.tar";
+    uploadFileInfo.put_properties = &put_properties;
+    int pause_upload_flag = 0;
+    uploadFileInfo.pause_upload_flag = &pause_upload_flag;
+    // Name of the object to be uploaded in resumable upload
+    char *key = "example_upload_file_object_key";
+    obs_status ret_status = OBS_STATUS_BUTT;
+    //Callback function
+    obs_upload_file_response_handler Handler =
+    {
+        {&response_properties_callback, &response_complete_callback},
+        &uploadFileResultCallback, &test_progress_callback
+    };
+    obs_upload_file_server_callback server_callback;
+    init_server_callback(&server_callback);
+    initialize_break_point_lock();
+    upload_file(&options, key, 0, &uploadFileInfo, server_callback, &Handler, &ret_status);
+    deinitialize_break_point_lock();
+    if (OBS_STATUS_OK == ret_status) {
+        printf("test upload file successfully. \n");
+    }
+    else
+    {
+        printf("test upload file failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *data =
+            (obs_status *)callback_data;
+        *data = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+//uploadFileResultCallback is used as an example here. The printf statements can be replaced with custom logging print statements.
+void uploadFileResultCallback(obs_status status,
+    char *resultMsg,
+    int partCountReturn,
+    obs_upload_file_part_info * uploadInfoList,
+    void *callbackData)
+{
+    int i = 0;
+    obs_upload_file_part_info * pstUploadInfoList = uploadInfoList;
+    printf("status return is %d(%s)\n", status, obs_get_status_name(status));
+    printf("%s", resultMsg);
+    printf("partCount[%d]\n", partCountReturn);
+    for (i = 0; i < partCountReturn; i++)
+    {
+        printf("partNum[%d],startByte[%llu],partSize[%llu],status[%d]\n",
+            pstUploadInfoList->part_num,
+            pstUploadInfoList->start_byte,
+            pstUploadInfoList->part_size,
+            pstUploadInfoList->status_return);
+        pstUploadInfoList++;
+    }
+    if (callbackData) {
+        obs_status* retStatus = (obs_status*)callbackData;
+        (*retStatus) = status;
+    }
+}
+static double g_progress = 0;
+void test_progress_callback(double progress, uint64_t uploadedSize, uint64_t fileTotalSize, void *callback_data) {
+    if (progress == 100 || (g_progress < progress && progress - g_progress > 2)) {
+        printf("test_progress_callback progress=%f  uploadedSize=%llu fileTotalSize=%llu  callback_data=%p\n", progress, uploadedSize, fileTotalSize, callback_data);
+        g_progress = progress;
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Object Upload
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0408.html b/docs/obs_3rd_party/c_sdk/obs_20_0408.html new file mode 100644 index 000000000..430712859 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0408.html @@ -0,0 +1,2821 @@ + + +

Uploading an Object - Append

+

Function

This API uploads a file or folder to an existing OBS bucket. You can upload text, pictures, videos, or any other types of files.

+

This API adds data to the end of a specified object. If there is no object with the same key found in the bucket, a new object is created.

+

The latest modification time of the object is updated each time an upload is appended.

+
+

Restrictions

  • To upload an object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • If SSE-C is used for server-side encryption, you must carry request headers such as x-obs-server-side-encryption in each append upload.
  • If SSE-KMS is used for server-side encryption, you only need to carry request headers such as x-obs-server-side-encryption when you first call this API to upload an object and when there is no existing object with the same name in the bucket.
  • The size of each append upload cannot exceed 5 GB.
  • The maximum number of append uploads for each appendable object is 10,000.
  • If the storage class is COLD (Cold), this API cannot be called.
  • Objects uploaded using put_object, referred to as normal objects, can overwrite objects uploaded using append_object, referred to as appendable objects. Data cannot be appended to an appendable object anymore once the object has been overwritten by a normal object.
  • When you upload an object for the first time in appendable mode, an exception will be reported (HTTP status code 409) if a common object with the same name exists.
  • The ETag returned for the append upload is the ETag for the appended content, rather than that of the whole object.
+
+

Method

void append_object(const obs_options *options, char *key, uint64_t content_length, const char * position,
+                   obs_put_properties *put_properties,server_side_encryption_params *encryption_params,
+                   obs_append_object_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

content_length

+

uint64_t

+

Yes

+

Explanation:

+

Length of the object content

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

If this parameter is not specified, the SDK automatically calculates the size of the object.

+

position

+

char *

+

Yes

+

Explanation:

+

Start position of the append

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

put_properties

+

obs_put_properties*

+

Yes

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Encryption setting of the uploaded object

+

Restrictions:

+

None

+

handler

+

obs_append_object_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 5 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • The value must be an integer greater than 0.
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Value of the Expires header in the OBS request. It specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + +
Table 13 obs_az_redundancy

Value

+

Description

+

OBS_REDUNDANCY_1AZ

+

By default, a single-AZ bucket is created.

+

OBS_REDUNDANCY_3AZ

+

A 3-AZ bucket is created.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Value range:

+
  • The value must be an integer greater than 0.
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 16 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 19 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 21 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 22 obs_append_object_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

append_object_data_callback

+

obs_append_object_data_callback *

+

Yes

+

Explanation:

+

Callback function pointer, which is used to copy the data to be uploaded to the data upload buffer.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_append_object_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

buffer_size

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

buffer

+

char *

+

Yes

+

Explanation:

+

Buffer for storing the data to be uploaded. The data to be uploaded is copied to this buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 24 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 25 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 26 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 28 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 29 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Uploading an Object - Append

This example calls append_object to perform the append upload.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void put_buffer_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
+typedef struct put_buffer_object_callback_data
+{
+    char *put_buffer;
+    uint64_t buffer_size;
+    uint64_t cur_offset;
+    obs_status ret_status;
+} put_buffer_object_callback_data;
+int put_buffer_data_callback(int buffer_size, char *buffer, void *callback_data);
+char* generate_upload_buffer(uint64_t buffer_size);
+int main()
+{
+    // The following code shows how to use append_object to perform the append upload:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Initialize the properties of the object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    //Initialize the structure for storing the uploaded data.
+    put_buffer_object_callback_data data;
+    memset(&data, 0, sizeof(put_buffer_object_callback_data));
+    // Set the buffer size.
+    data.buffer_size = 10 * 1024 * 1024;
+    // Create a simulated data buffer for the streaming upload and assign the value to the data upload structure.
+    data.put_buffer = generate_upload_buffer(data.buffer_size);
+    if (NULL == data.put_buffer) {
+        printf("generate put buffer failed. \n");
+        return;
+    }
+    // Name of the object to be uploaded
+    char *key = "example_put_file_test_append";
+    // The start position of the append upload
+    char *position = "0";
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_buffer_complete_callback },
+          &put_buffer_data_callback
+    };
+    append_object(&options, key, data.buffer_size, position, &put_properties,
+        0, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("append object from buffer successfully. \n");
+    }
+    else
+    {
+        printf("append object from buffer failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void put_buffer_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
+{
+    if (callback_data) {
+        put_buffer_object_callback_data *data = (put_buffer_object_callback_data *)callback_data;
+        data->ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+int put_buffer_data_callback(int buffer_size, char *buffer, void *callback_data)
+{
+    put_buffer_object_callback_data *data =
+        (put_buffer_object_callback_data *)callback_data;
+    int toRead = 0;
+    if (data->buffer_size) {
+        toRead = ((data->buffer_size > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->buffer_size);
+        memcpy_s(buffer, buffer_size, data->put_buffer + data->cur_offset, toRead);
+    }
+    uint64_t originalContentLength = data->buffer_size;
+    data->buffer_size -= toRead;
+    data->cur_offset += toRead;
+    if (data->buffer_size) {
+        printf("%llu bytes remaining ", (unsigned long long)data->buffer_size);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->buffer_size) * 100) / originalContentLength));
+    }
+    return toRead;
+}
+// Create a simulated streaming upload buffer.
+char* generate_upload_buffer(uint64_t buffer_size) {
+    void* upload_buffer = NULL;
+    if (buffer_size > 0) {
+        upload_buffer = malloc(buffer_size);
+        if (upload_buffer != NULL) {
+            memset(upload_buffer, 't', buffer_size);
+        }
+    }
+    return upload_buffer;
+}
+
+
+
+
+
+
+
+
Parent topic: Object Upload
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0500.html b/docs/obs_3rd_party/c_sdk/obs_20_0500.html new file mode 100644 index 000000000..60b1b066b --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0500.html @@ -0,0 +1,17 @@ + + +

Object Download

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0501.html b/docs/obs_3rd_party/c_sdk/obs_20_0501.html new file mode 100644 index 000000000..5d5772e48 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0501.html @@ -0,0 +1,2350 @@ + + +

Downloading an Object

+

Function

This API downloads an object as text from OBS to your local computer.

+
+

Restrictions

  • To download an object, you must be the bucket owner or have the required permission (obs:object:GetObject in IAM or GetObject in a bucket policy).
  • Objects in the Cold storage class can be downloaded only when they are in the Restored status.
+
+

Method

void get_object(const obs_options *options, obs_object_info *object_info,
+                         obs_get_conditions *get_conditions, 
+                         server_side_encryption_params *encryption_params,
+                         obs_get_object_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

get_conditions

+

obs_get_conditions *

+

Yes

+

Explanation:

+

Sets filter conditions of the object and read range.

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Obtains the decryption settings of an object.

+

Restrictions:

+

None

+

handler

+

obs_get_object_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_get_object_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

get_object_data_callback

+

obs_get_object_data_callback *

+

Yes

+

Explanation:

+

Pointer to the callback function, which is used to copy the data to be downloaded from the data buffer to the custom callback data.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_get_object_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

buffer_size

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

buffer

+

char *

+

Yes

+

Explanation:

+

Data buffer to be downloaded. Data in this buffer is copied to callback_data to download data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 20 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 22 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 23 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 25 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+
+

Code Examples: Downloading an Object

This example uses get_object to download an object as a local file.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data);
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct get_object_callback_data
+{
+    FILE *outfile;
+    obs_status ret_status;
+}get_object_callback_data;
+FILE * write_to_file(char *localfile);
+int main()
+{
+    // The following code shows how to use the get_object function to download an object to a local file:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Set the name of the local file to which the object is downloaded.
+    char *file_name = "./example_get_file_test";
+    obs_object_info object_info;
+    // Set the object to be downloaded.
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "example_get_file_test";
+    object_info.version_id = NULL;
+    //Set the structure for storing the downloaded object data based on service requirements.
+    get_object_callback_data data;
+    data.ret_status = OBS_STATUS_BUTT;
+    data.outfile = write_to_file(file_name);
+    // Define parameters for range-based download.
+    obs_get_conditions getcondition;
+    memset(&getcondition, 0, sizeof(obs_get_conditions));
+    init_get_properties(&getcondition);
+    // Download start position. The default value is 0, indicating that the download starts from byte 0.
+    getcondition.start_byte = 0;
+    // Download length. The default value is 0, indicating that the object is downloaded until the end.
+    // getcondition.byte_count = 0;
+    // Define the download callback function.
+    obs_get_object_handler get_object_handler =
+    {
+        { &response_properties_callback,
+          &get_object_complete_callback},
+        &get_object_data_callback
+    };
+    get_object(&options, &object_info, &getcondition, 0, &get_object_handler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("get object successfully. \n");
+    }
+    else
+    {
+        printf("get object failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    fclose(data.outfile);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    size_t wrote = fwrite(buffer, 1, buffer_size, data->outfile);
+    return ((wrote < (size_t)buffer_size) ?
+        OBS_STATUS_AbortedByCallback : OBS_STATUS_OK);
+}
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+FILE * write_to_file(char *localfile)
+{
+    FILE *outfile = 0;
+    if (localfile) {
+        struct stat buf;
+        if (stat(localfile, &buf) == -1) {
+            outfile = fopen(localfile, "wb");
+        }
+        else {
+            outfile = fopen(localfile, "a");
+        }
+        if (!outfile) {
+            fprintf(stderr, "\nERROR: Failed to open output file %s: ",
+                localfile);
+            return outfile;
+        }
+    } else {
+        fprintf(stderr, "\nERROR: Failed to open output file, it's NULL, write object to stdout.",
+            localfile);
+        outfile = stdout;
+    }
+    return outfile;
+}
+
+
+
+
  • You can perform operations on the input streams of an object to read and write the object contents to a local file or to the memory.
  • getcondition can be left empty, indicating that the entire object is downloaded.
+
+
+
+
+
+
Parent topic: Object Download
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0502.html b/docs/obs_3rd_party/c_sdk/obs_20_0502.html new file mode 100644 index 000000000..58598529d --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0502.html @@ -0,0 +1,2180 @@ + + +

Downloading an Object - Conditional

+

Function

This API returns the objects that meet one or more conditions. If there are no objects that meet the specified conditions, an error is returned.

+
+

Restrictions

  • To download an object, you must be the bucket owner or have the required permission (obs:object:GetObject in IAM or GetObject in a bucket policy).
  • Objects in the Cold storage class can be downloaded only when they are in the Restored status.
+
+

Method

void get_object(const obs_options *options, obs_object_info *object_info,
+    obs_get_conditions *get_conditions, 
+    server_side_encryption_params *encryption_params,
+    obs_get_object_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

get_conditions

+

obs_get_conditions *

+

Yes

+

Explanation:

+

Sets filter conditions of the object and read range.

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Obtains the decryption settings of an object.

+

Restrictions:

+

None

+

handler

+

obs_get_object_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_get_object_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

get_object_data_callback

+

obs_get_object_data_callback *

+

Yes

+

Explanation:

+

Pointer to the callback function, which is used to copy the data to be downloaded from the data buffer to the custom callback data.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_get_object_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

buffer_size

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

buffer

+

char *

+

Yes

+

Explanation:

+

Data buffer to be downloaded. Data in this buffer is copied to callback_data to download data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 20 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 22 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 23 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 25 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+
+

Code Examples: Conditional Download

This example downloads an object to the local host with conditions using get_object.
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data);
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct get_object_callback_data
+{
+    FILE *outfile;
+    obs_status ret_status;
+}get_object_callback_data;
+FILE * write_to_file(char *localfile);
+int main()
+{
+    // The following code shows how to use the get_object function to download an object to a local file:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Set the name of the local file to which the object is downloaded.
+    char *file_name = "./example_get_file_test";
+    obs_object_info object_info;
+    // Set the object to be downloaded.
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "example_get_file_test";
+    object_info.version_id = NULL;
+    //Set the structure for storing the downloaded object data based on service requirements.
+    get_object_callback_data data;
+    data.ret_status = OBS_STATUS_BUTT;
+    data.outfile = write_to_file(file_name);
+    // Define parameters for range-based download.
+    obs_get_conditions getcondition;
+    memset(&getcondition, 0, sizeof(obs_get_conditions));
+    init_get_properties(&getcondition);
+    getcondition.if_match_etag = "34a7ef8cc629583f3cdd882791f31351";
+    // Set the download condition if_modified_since to timestamp 0.
+    getcondition.if_modified_since = 0;
+    getcondition.if_not_match_etag = "34a7ef8cc629583f3cdd882791f31350";
+    // Set the download condition if_modified_since to timestamp 2147483647.
+    getcondition.if_not_modified_since = INT_MAX;
+    // Define the download callback function.
+    obs_get_object_handler get_object_handler =
+    {
+        { &response_properties_callback,
+          &get_object_complete_callback},
+        &get_object_data_callback
+    };
+    get_object(&options, &object_info, &getcondition, 0, &get_object_handler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("get object successfully. \n");
+    }
+    else
+    {
+        printf("get object failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    fclose(data.outfile);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    size_t wrote = fwrite(buffer, 1, buffer_size, data->outfile);
+    return ((wrote < (size_t)buffer_size) ?
+        OBS_STATUS_AbortedByCallback : OBS_STATUS_OK);
+}
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+FILE * write_to_file(char *localfile)
+{
+    FILE *outfile = 0;
+    if (localfile) {
+        struct stat buf;
+        if (stat(localfile, &buf) == -1) {
+            outfile = fopen(localfile, "wb");
+        }
+        else {
+            outfile = fopen(localfile, "a");
+        }
+        if (!outfile) {
+            fprintf(stderr, "\nERROR: Failed to open output file %s: ",
+                localfile);
+            return outfile;
+        }
+    } else {
+        fprintf(stderr, "\nERROR: Failed to open output file, it's NULL, write object to stdout.",
+            localfile);
+        outfile = stdout;
+    }
+    return outfile;
+}
+
+
+
+
+
+
Parent topic: Object Download
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0503.html b/docs/obs_3rd_party/c_sdk/obs_20_0503.html new file mode 100644 index 000000000..e2df0abec --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0503.html @@ -0,0 +1,2150 @@ + + +

Restoring a Cold Object

+

Function

To obtain the content of an object in the Cold storage class, you need to restore the object first and then you can download it. After an object is restored, a copy of the object is saved in the Standard storage class. By doing so, the object in the Cold storage class and its copy in the Standard storage class co-exist in the bucket. The copy will be automatically deleted once its retention period ends.

+

This API is used to restore Cold objects in a specified bucket.

+
+

Restrictions

  • To restore a Cold object, you must be the bucket owner or have the required permission (obs:object:RestoreObject in IAM or RestoreObject in a bucket policy.)
  • To prolong the validity period of the Cold data restored, you can repeatedly restore the data, but you will be billed for each restore. After a restoration, the validity period of Standard object copies will be extended, and you need to pay for storing these copies during the extended period.
+
+

Method

void restore_object(const obs_options *options, obs_object_info *object_info, const char *days, obs_tier tier,const 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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

days

+

char *

+

Yes

+

Explanation:

+

Retention period of the restored object

+

Restrictions:

+

None

+

Value range:

+

The value ranges from 1 to 30, in days.

+

Default value:

+

None

+

tier

+

obs_tier

+

No

+

Explanation:

+

Restore options: obs_tier.OBS_TIER_EXPEDITED or obs_tier.OBS_TIER_STANDARD

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_tier.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+
  • The name of each object in a bucket must be unique.
  • The object specified must be in the Cold storage class. Otherwise, an error is reported.
+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 12 obs_tier

Value

+

Description

+

OBS_TIER_NULL

+

Default invalid value.

+

OBS_TIER_STANDARD

+

It indicates that objects can be restored from Cold storage within 3 to 5 hours.

+

OBS_TIER_EXPEDITED

+

It indicates that objects can be quickly restored from Cold storage within 1 to 5 minutes.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Restoring and Downloading a Cold Object

This example calls restore_object to restore a Cold object and then use the get_object function to download the object to a local file. (Note that the restoration may take a long time.)
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data);
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+// The completion callback function. 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 get_object_callback_data
+{
+    FILE *outfile;
+    obs_status ret_status;
+}get_object_callback_data;
+FILE * write_to_file(char *localfile);
+void wait_until_restore_complete(obs_options* options, obs_object_info* object_info, server_side_encryption_params* sse);
+int main()
+{
+    // The following code shows how to use the get_object function to download an object in OBS Cold to a local file:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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_object_info object_info;
+    // Set the object to be downloaded.
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "example_get_file_test_restore";
+    object_info.version_id = NULL;
+    // Set the response callback function.
+    obs_response_handler handler =
+    {
+      &response_properties_callback, &response_complete_callback
+    };
+    // Restore the object.
+    obs_tier tier = OBS_TIER_EXPEDITED; 
+    obs_status ret_status = OBS_STATUS_BUTT;
+    const char* storedDays = "1"; 
+    options.request_options.auth_switch = OBS_OBS_TYPE;
+    restore_object(&options, &object_info, storedDays, tier, &handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("restore object successfully. \n");
+    }
+    else
+    {
+        printf("restore object failed(%s).\n", obs_get_status_name(ret_status));
+        return;
+    }
+    // Wait until the object is restored.
+    wait_until_restore_complete(&options, &object_info, NULL);
+    // Set the name of the local file to which the object is downloaded.
+    char *file_name = "./example_get_file_test";
+    //Set the structure for storing the downloaded object data based on service requirements.
+    get_object_callback_data data;
+    data.ret_status = OBS_STATUS_BUTT;
+    data.outfile = write_to_file(file_name);
+    obs_get_conditions getcondition;
+    memset(&getcondition, 0, sizeof(obs_get_conditions));
+    init_get_properties(&getcondition);
+    // Define the download callback function.
+    obs_get_object_handler get_object_handler =
+    {
+        { &response_properties_callback,
+          &get_object_complete_callback},
+        &get_object_data_callback
+    };
+    get_object(&options, &object_info, &getcondition, 0, &get_object_handler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("get object successfully. \n");
+    }
+    else
+    {
+        printf("get object failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    fclose(data.outfile);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+typedef struct test_restore_info {
+    char restore_info[128];
+    obs_status status;
+}test_restore_info;
+void response_complete_callback_restore(obs_status status, const obs_error_details *error, void *callback_data)
+{
+    if (callback_data) {
+        test_restore_info *data =
+            (test_restore_info *)callback_data;
+        data->status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+static obs_status response_properties_callback_restore(const obs_response_properties *properties, void *callback_data)
+{
+    if (callback_data) {
+        test_restore_info *data =
+            (test_restore_info *)callback_data;
+        if (properties->restore != NULL) {
+            strcpy(data->restore_info, properties->restore);
+        }
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+}
+void wait_until_restore_complete(obs_options* options, obs_object_info* object_info, server_side_encryption_params* sse) {
+    test_restore_info restore_info;
+    // Set the response callback function.
+    obs_response_handler handler =
+    {
+      &response_properties_callback_restore, &response_complete_callback_restore
+    };
+    do {
+        memset(restore_info.restore_info, 0, sizeof(restore_info.restore_info));
+        restore_info.status = OBS_STATUS_BUTT;
+        get_object_metadata(options, object_info, sse, &handler, &restore_info);
+        char* prefix = "ongoing-request=\"false\", expiry-date=";
+        // Check whether the character string starts with a specified character.
+        if (strstr(restore_info.restore_info, prefix) == restore_info.restore_info) {
+            printf("restore_info.restore_info:%s\n", restore_info.restore_info);
+            break;
+        }
+        else {
+            printf("restore_info.restore_info:%s\n", restore_info.restore_info);
+        }
+        Sleep(6 * 1000);
+    } while (1);
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *data =
+            (obs_status *)callback_data;
+        *data = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    size_t wrote = fwrite(buffer, 1, buffer_size, data->outfile);
+    return ((wrote < (size_t)buffer_size) ?
+        OBS_STATUS_AbortedByCallback : OBS_STATUS_OK);
+}
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    data->ret_status = status;
+    print_error_details(error);
+}
+FILE * write_to_file(char *localfile)
+{
+    FILE *outfile = 0;
+    if (localfile) {
+        struct stat buf;
+        if (stat(localfile, &buf) == -1) {
+            outfile = fopen(localfile, "wb");
+        }
+        else {
+            outfile = fopen(localfile, "a");
+        }
+        if (!outfile) {
+            fprintf(stderr, "\nERROR: Failed to open output file %s: ",
+                localfile);
+            return outfile;
+        }
+    } else {
+        fprintf(stderr, "\nERROR: Failed to open output file, it's NULL, write object to stdout.",
+            localfile);
+        outfile = stdout;
+    }
+    return outfile;
+}
+
+
+
+
+
+
+
+
Parent topic: Object Download
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0504.html b/docs/obs_3rd_party/c_sdk/obs_20_0504.html new file mode 100644 index 000000000..5cc20f4ae --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0504.html @@ -0,0 +1,2482 @@ + + +

Downloading an Object - Resumable

+

Function

Downloading large files often fails due to an unstable network or program breakdown. It is a waste of resources to download files again. Moreover, the restarted download may still fail due to an unstable network. To resolve such issues, the resumable download API splits the file to be downloaded into multiple parts and downloads them separately. The download result of each part is recorded in a checkpoint file in real time. Only when all parts are downloaded is a message indicating the download is successful returned. If any parts fail to be downloaded, a message is returned telling you to call the API again to download the failed parts. Since the checkpoint file contains the progress of all parts, it helps you avoid downloading all parts in re-downloads, so that you can enjoy a cost-effective, efficient download.

+

You can use download_file to perform a resumable download.

+
+

Restrictions

  • To download an object, you must be the bucket owner or have the required permission (obs:object:GetObject in IAM or GetObject in a bucket policy).
  • The API for resumable download, which is implemented based on partial download, is an encapsulated and enhanced version of partial download.
  • By resuming a failed download from where it failed, this API helps save resources. In addition, parts can be downloaded concurrently, which helps speed up the download. During the download process, you do not need to take care of internal service details, such as the creation and deletion of checkpoint files, division of objects, or concurrent downloads of parts.
+
+

Method

void download_file(const obs_options *options, char *key, char* version_id, 
+    obs_get_conditions *get_conditions,
+    server_side_encryption_params *encryption_params,
+    obs_download_file_configuration * download_file_config,
+    obs_download_file_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

version_id

+

char *

+

Yes

+

Explanation:

+

Object version ID.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

download_file_config

+

obs_download_file_configuration *

+

Yes

+

Explanation:

+

Configuration description of the file to be downloaded.

+

Restrictions:

+

None

+

get_conditions

+

obs_get_conditions *

+

Yes

+

Explanation:

+

Sets filter conditions of the object and read range.

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Decryption settings of the downloaded object.

+

Restrictions:

+

None

+

handler

+

obs_download_file_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Value range:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Value range:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Value range:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 13 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 15 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_download_file_configuration

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

downLoad_file

+

char *

+

Yes

+

Explanation:

+

Local path to which the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

part_size

+

uint64_t

+

No

+

Explanation:

+

Part size, in bytes

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

check_point_file

+

char *

+

No

+

Explanation:

+

Path of the file that records the upload progress. This parameter is effective only in the resumable mode.

+

Restrictions:

+
  • If the value of this parameter is left blank, the file will be in the same directory as the local file to be uploaded.
  • This parameter is valid only when enable_check_point is set to 1.
+

Value range:

+

None

+

Default value:

+

None

+

enable_check_point

+

int

+

No

+

Explanation:

+

Whether to enable the resumable mode

+

Restrictions:

+

None

+

Value range:

+
  • 0: The resumable mode is disabled. In this case, this API works as a multipart transmission API, and no checkpoint files are generated.
  • 1: The resumable mode is enabled.
+

Default value:

+

0: disabled

+

task_num

+

int

+

No

+

Explanation:

+

Maximum number of parts that can be uploaded concurrently Use this parameter to configure how many concurrent tasks there can be in downloading a single object.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

1

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_download_file_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

download_file_callback

+

obs_download_file_callback *

+

Yes

+

Explanation:

+

The pointer to the callback function, where the callback parameters can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_download_file_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Request status

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

result_message

+

char *

+

Yes

+

Explanation:

+

Download result.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 19 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 20 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 24 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 25 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Resumable Download

This example calls download_file to perform the resumable download.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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 completion callback function. 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);
+void downloadFileResultCallback(obs_status status,
+    char *resultMsg,
+    int partCountReturn,
+    obs_download_file_part_info * downloadInfoList,
+    void *callbackData);
+int main()
+{
+    // The following code shows how to use download_file to perform the resumable download:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Set the object to be downloaded.
+    char* key = "example_get_file_test";
+    // Set the name of the local file to which the object is downloaded.
+    char *file_name = "./example_get_file_test";
+    // Initialize getConditions.
+    obs_get_conditions getConditions;
+    memset(&getConditions, 0, sizeof(obs_get_conditions));
+    init_get_properties(&getConditions);
+    // Object information in the resumable download
+    obs_download_file_configuration downloadFileConfig;
+    memset(&downloadFileConfig, 0, sizeof(obs_download_file_configuration));
+    // Size of the object parts
+    uint64_t downloadSliceSize = 5L * 1024 * 1024;
+    downloadFileConfig.check_point_file = NULL;
+    downloadFileConfig.enable_check_point = 1;
+    downloadFileConfig.part_size = downloadSliceSize;
+    downloadFileConfig.task_num = 10;
+    downloadFileConfig.downLoad_file = file_name;
+    // Set the response callback function.
+    obs_download_file_response_handler Handler =
+    {
+        {&response_properties_callback, &response_complete_callback},
+        &downloadFileResultCallback
+    };
+    char* versionId = NULL;
+    server_side_encryption_params* sse = NULL;
+    initialize_break_point_lock();
+    obs_status ret_status = OBS_STATUS_BUTT;
+    download_file(&options, key, versionId, &getConditions, sse, &downloadFileConfig,
+        &Handler, &ret_status);
+    deinitialize_break_point_lock();
+    if (OBS_STATUS_OK == ret_status) {
+        printf("test download file successfully. \n");
+    }
+    else
+    {
+        printf("test download file failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *data =
+            (obs_status *)callback_data;
+        *data = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+//downloadFileResultCallback is used as an example here. The printf statements can be replaced with custom logging print statements.
+void downloadFileResultCallback(obs_status status,
+    char *resultMsg,
+    int partCountReturn,
+    obs_download_file_part_info * downloadInfoList,
+    void *callbackData)
+{
+    int i = 0;
+    obs_download_file_part_info * pstDownloadInfoList = downloadInfoList;
+    printf("status return is %d(%s)\n", status, obs_get_status_name(status));
+    printf("%s", resultMsg);
+    printf("partCount[%d]\n", partCountReturn);
+    for (i = 0; i < partCountReturn; i++)
+    {
+        printf("partNum[%d],startByte[%llu],partSize[%llu],status[%d]\n",
+            pstDownloadInfoList->part_num,
+            pstDownloadInfoList->start_byte,
+            pstDownloadInfoList->part_size,
+            pstDownloadInfoList->status_return);
+        pstDownloadInfoList++;
+    }
+    if (callbackData) {
+        obs_status* retStatus = (obs_status*)callbackData;
+        (*retStatus) = status;
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Object Download
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0600.html b/docs/obs_3rd_party/c_sdk/obs_20_0600.html new file mode 100644 index 000000000..d20c93d0f --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0600.html @@ -0,0 +1,29 @@ + + +

Object Management

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0601.html b/docs/obs_3rd_party/c_sdk/obs_20_0601.html new file mode 100644 index 000000000..682851dca --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0601.html @@ -0,0 +1,1994 @@ + + +

Obtaining Object Properties

+

Function

Object metadata contains a set of name-value pairs that are used for describing and managing objects.

+

Currently, only the system-defined metadata is supported. System-defined metadata consists of system-controlled metadata and user-controlled metadata. The kind of metadata like Last-Modified is controlled by the system and cannot be modified. However, the kind of metadata configured for objects such as ContentLanguage can be modified by calling APIs.

+

This API sends a HEAD request for obtaining object metadata.

+
+

Restrictions

  • To obtain object metadata, you must be the bucket owner or have the required permission (obs:object:GetObject in IAM or GetObject in a bucket policy).
+
+

Method

void get_object_metadata(const obs_options *options, obs_object_info *object_info, 
+	server_side_encryption_params *encryption_params,
+	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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID. For non-multi-version objects, set version to 0.

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Encryption setting of the uploaded object

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 13 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 15 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 19 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Obtaining Object Properties

This example calls get_object_metadata to obtain object metadata.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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); 
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to use get_object_metadata to obtain object metadata:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Object information
+    obs_object_info object_info;
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "example_get_file_test";
+    object_info.version_id = NULL;
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    {
+        // Object properties can be obtained from response_properties_callback.
+        &response_properties_callback, &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Obtain object properties.
+    get_object_metadata(&options, &object_info, 0, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("get object metadata successfully. \n");
+    }
+    else
+    {
+        printf("get object metadata failed.\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Object Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0602.html b/docs/obs_3rd_party/c_sdk/obs_20_0602.html new file mode 100644 index 000000000..20b36518d --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0602.html @@ -0,0 +1,2962 @@ + + +

Setting a Pre-defined ACL During Object Upload

+

Function

Access control lists (ACLs) allow resource owners to grant other accounts the permissions to access resources. By default, only the resource owner has full control over resources when a bucket or object is created. That is, the bucket creator has full control over the bucket, and the object uploader has full control over the object. Other accounts do not have the permissions to access resources. If resource owners want to grant other accounts the read and write permissions on resources, they can use ACLs. ACLs grant permissions to accounts. After an account is granted permissions, both the account and its IAM users can access the resources.

+

+

This API specifies a pre-defined ACL when uploading an object.

+
+

Restrictions

  • To configure an object ACL, you must be the bucket owner or have the required permission (obs:object:PutObjectAcl in IAM or PutObjectAcl in a bucket policy).
  • An object can have a maximum of 100 rules in its ACL.
+
+

Method

1
+2
+3
+4
void put_object(const obs_options *options, char *key, uint64_t content_length,
+                         obs_put_properties *put_properties,
+                         server_side_encryption_params *encryption_params,
+                         obs_put_object_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

content_length

+

uint64_t

+

Yes

+

Explanation:

+

Length of the object content

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

If this parameter is not specified, the SDK automatically calculates the size of the object.

+

put_properties

+

obs_put_properties*

+

Yes

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Encryption setting of the uploaded object

+

Restrictions:

+

None

+

handler

+

obs_put_object_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + +
Table 5 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+

None

+

Value range:

+
  • An integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header, the response message must contain this header.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

Default value:

+

None

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+

None

+

Value range:

+
  • An integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + +
Table 14 obs_az_redundancy

Value

+

Description

+

OBS_REDUNDANCY_1AZ

+

By default, a single-AZ bucket is created.

+

OBS_REDUNDANCY_3AZ

+

A 3-AZ bucket is created.

+
+
+ +
+ + + + + + + + + + + + + +
Table 15 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in callbackBodyType.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request.

+

Restrictions:

+

None

+

Value range:

+
  • application/x-www-form-urlencoded
  • application/json
+

Default value:

+

If no value is specified, the default value application/json is used.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 18 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that the server-side encryption used for objects is SSE-KMS.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 20 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_put_object_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

put_object_data_callback

+

obs_put_object_data_callback *

+

Yes

+

Explanation:

+

Callback function pointer, which is used to copy the data to be uploaded to the data upload buffer.

+

Restrictions:

+

None

+

progress_callback

+

obs_progress_callback_internal *

+

Yes

+

Explanation:

+

Pointer to the progress callback function.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_put_object_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

buffer_size

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

buffer

+

char *

+

Yes

+

Explanation:

+

Buffer for storing the data to be uploaded. The data to be uploaded is copied to this buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_progress_callback_internal

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

now

+

uint64_t

+

Yes

+

Explanation:

+

Number of bytes that have been uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

total

+

uint64_t

+

Yes

+

Explanation:

+

Total number of bytes to be uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 24 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 25 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 26 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID. If the object has no version ID, the value is NULL.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 28 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 29 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 30 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Setting a Pre-defined ACL When Uploading the Object

This example specifies a pre-defined ACL when uploading an object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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); 
+void put_buffer_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct put_buffer_object_callback_data
+{
+    char *put_buffer;
+    uint64_t buffer_size;
+    uint64_t cur_offset;
+    obs_status ret_status;
+} put_buffer_object_callback_data;
+int put_buffer_data_callback(int buffer_size, char *buffer, void *callback_data);
+char* generate_upload_buffer(uint64_t buffer_size);
+int main()
+{
+    // The following code shows how to specify a pre-defined ACL when uploading an object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Name of the object to be uploaded
+    char *key = "example_put_buffer_test_with_acl.txt";
+    // Initialize the put_properties structure. You can set object properties through this structure.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Specify a pre-defined ACL.
+    put_properties.canned_acl = OBS_CANNED_ACL_PUBLIC_READ_WRITE;
+    // Callback data
+    put_buffer_object_callback_data data;
+    memset(&data, 0, sizeof(put_buffer_object_callback_data));
+    // Set the buffer size.
+    data.buffer_size = 10 * 1024 * 1024;
+    // Create a simulated data buffer for the streaming upload and assign the value to the data upload structure.
+    data.put_buffer = generate_upload_buffer(data.buffer_size);
+    // Callback function
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_buffer_complete_callback },
+        &put_buffer_data_callback
+    };
+    // Upload the data stream.
+    put_object(&options, key, data.buffer_size, &put_properties, 0, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from file successfully. \n");
+    }
+    else
+    {
+        printf("put object failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// The response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void put_buffer_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
+{
+    if (callback_data) {
+        put_buffer_object_callback_data *data = (put_buffer_object_callback_data *)callback_data;
+        data->ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+int put_buffer_data_callback(int buffer_size, char *buffer, void *callback_data)
+{
+    put_buffer_object_callback_data *data =
+        (put_buffer_object_callback_data *)callback_data;
+    int toRead = 0;
+    if (data->buffer_size) {
+        toRead = ((data->buffer_size > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->buffer_size);
+        memcpy_s(buffer, buffer_size, data->put_buffer + data->cur_offset, toRead);
+    }
+    uint64_t originalContentLength = data->buffer_size;
+    data->buffer_size -= toRead;
+    data->cur_offset += toRead;
+    if (data->buffer_size) {
+        printf("%llu bytes remaining ", (unsigned long long)data->buffer_size);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->buffer_size) * 100) / originalContentLength));
+    }
+    return toRead;
+}
+// Create a simulated streaming upload buffer.
+char* generate_upload_buffer(uint64_t buffer_size) {
+    void* upload_buffer = NULL;
+    if (buffer_size > 0) {
+        upload_buffer = malloc(buffer_size);
+        if (upload_buffer != NULL) {
+            memset(upload_buffer, 't', buffer_size);
+        }
+    }
+    return upload_buffer;
+}
+
+
+
+
+
+
+
+
Parent topic: Object Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0603.html b/docs/obs_3rd_party/c_sdk/obs_20_0603.html new file mode 100644 index 000000000..fcdfe9784 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0603.html @@ -0,0 +1,2348 @@ + + +

Listing Objects in a Bucket

+

Function

This API lists some or all of the objects in a bucket. You can use parameters such as the prefix, number of returned objects, and start position to list objects that meet specified criteria. Returned objects are listed in alphabetical order by object name.

+
+

Restrictions

  • A maximum of 1,000 objects can be listed for each API call.
  • To list objects in a bucket, you must be the bucket owner or have the required permission (obs:bucket:ListBucket in IAM and ListBucket in a bucket policy).
+
+

Method

void list_bucket_objects(const obs_options *options, const char *prefix, const char *marker, 
+    const char *delimiter, int maxkeys, obs_list_objects_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

prefix

+

char *

+

No

+

Explanation:

+

Name prefix that the objects to be listed must contain

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

marker

+

char *

+

No

+

Explanation:

+

Object name to start with when listing objects. All objects are listed in the lexicographical order.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

delimiter

+

char *

+

No

+

Explanation:

+

The character used to group object names. If the object name contains the value specified by the delimiter parameter, the string from the first character to the first delimiter in the object name (excluding the prefix if prefix is specified) is grouped into one commonPrefix to be returned.

+

For a parallel file system, if this parameter is not specified, all the content in the directory is recursively listed by default, and subdirectories are also listed. In big data scenarios, file systems usually have multiple directory levels and each directory level has a large number of objects. In such case, you are advised to configure [delimiter="/"] to list the content in the current directory but exclude the content in subdirectories, thereby making the listing more efficient.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

maxkeys

+

int

+

Yes

+

Explanation:

+

Maximum number of objects that can be listed.

+

Restrictions:

+

If the specified value is greater than 1000, 1000 is used by default.

+

Value range:

+

An integer from 1 to 1000

+

Default value:

+

1000

+

handler

+

obs_list_objects_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_list_objects_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

list_Objects_callback

+

obs_list_objects_callback *

+

Yes

+

Explanation:

+

Callback function pointer, which is used to copy the data to be uploaded to the data upload buffer.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_list_objects_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

is_truncated

+

int

+

Yes

+

Explanation:

+

Whether the result is truncated.

+

Restrictions:

+

None

+

Value range:

+
  • 0 (indicating that all results have been returned)
  • 1 (indicating that not all results have been returned)
+

Default value:

+

None

+

next_marker

+

const char *

+

Yes

+

Explanation:

+

Where in the bucket the next listing begins. This parameter is returned if some listing results were not returned. You can set key_marker of the next request to the returned value to list the remaining results.

+

Restrictions:

+

This parameter is only available for listing objects with multiple versions.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

contents_count

+

const char *

+

Yes

+

Explanation:

+

Start position for the next request for listing objects. It must be used together with next_key_marker. This parameter is returned if some listing results were not returned. You can set version_id_marker of the next request to the returned value to list the remaining results.

+

Restrictions:

+

This parameter is only available for listing objects with multiple versions.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

contents

+

const obs_list_objects_content *

+

Yes

+

Explanation:

+

Information about the listed objects.

+

Restrictions:

+

None

+

common_prefixes_count

+

int

+

Yes

+

Explanation:

+

Number of common prefixes.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

common_prefixes

+

const char **

+

Yes

+

Explanation:

+

List of object name prefixes grouped according to the delimiter parameter (if specified)

+

Restrictions:

+

None

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_list_objects_content

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

const char *

+

No

+

Explanation:

+

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

None

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

last_modified

+

int64_t

+

No

+

Explanation:

+

Time when the object was last modified, in UTC.

+

Restrictions:

+

None

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag value is a hash of the object. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag after MD5 encryption.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

size

+

uint64_t

+

No

+

Explanation:

+

Object size in bytes.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

owner_id

+

const char *

+

No

+

Explanation:

+

Domain ID (account ID) of the object owner.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

type

+

const char *

+

No

+

Explanation:

+

Object type. This parameter is returned when the object type is not Normal.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples: Listing Objects

This example calls the list_bucket_objects function to list objects in a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.h>
+#include <sys/stat.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);
+void listobjects_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct list_object_callback_data
+{
+    int is_truncated;
+    char next_marker[1024];
+    int keyCount;
+    int allDetails;
+    obs_status ret_status;
+} list_object_callback_data; 
+obs_status list_objects_callback(int is_truncated, const char *next_marker,
+    int contents_count,
+    const obs_list_objects_content *contents,
+    int common_prefixes_count,
+    const char **common_prefixes,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to use the list_bucket_objects function to list objects in a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Set the response callback function.
+    obs_list_objects_handler list_bucket_objects_handler =
+    {
+        { &response_properties_callback, &listobjects_complete_callback },
+        &list_objects_callback
+    };
+    // Customize callback data.
+    list_object_callback_data data;
+    memset(&data, 0, sizeof(list_object_callback_data));
+    data.allDetails = 1;
+    const char* prefix = NULL;
+    const char* marker = NULL;
+    const char* delimiter = "/";
+    int maxkeys = 1000;
+    // List objects.
+    list_bucket_objects(&options, prefix, marker, delimiter, maxkeys, &list_bucket_objects_handler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("list bucket objects successfully. \n");
+    }
+    else
+    {
+        printf("list bucket objects failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void listobjects_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    if (callback_data)
+    {
+        list_object_callback_data *data = (list_object_callback_data *)callback_data;
+        data->ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+static void printListBucketHeader(int allDetails)
+{
+    printf("%-50s  %-20s  %-5s",
+        "   Key",
+        "   Last Modified", "Size");
+    if (allDetails) {
+        printf("  %-34s  %-64s  %-12s            %-12s",
+            "   ETag",
+            "   Owner ID",
+            "Display Name",
+            "StorageClass");
+    }
+    printf("\n");
+    printf("--------------------------------------------------  "
+        "--------------------  -----");
+    if (allDetails) {
+        printf("  ----------------------------------  "
+            "-------------------------------------------------"
+            "---------------  ------------            ------------");
+    }
+    printf("\n");
+}
+obs_status list_objects_callback(int is_truncated, const char *next_marker,
+    int contents_count,
+    const obs_list_objects_content *contents,
+    int common_prefixes_count,
+    const char **common_prefixes,
+    void *callback_data)
+{
+    list_object_callback_data *data = (list_object_callback_data *)callback_data;
+    data->is_truncated = is_truncated;
+    if ((!next_marker || !next_marker[0]) && contents_count) {
+        next_marker = contents[contents_count - 1].key;
+    }
+    if (next_marker) {
+        snprintf(data->next_marker, sizeof(data->next_marker), "%s",
+            next_marker);
+    }
+    else {
+        data->next_marker[0] = 0;
+    }
+    if (contents_count && !data->keyCount) {
+        printListBucketHeader(data->allDetails);
+    }
+    int i;
+    for (i = 0; i < contents_count; i++) {
+        const obs_list_objects_content *content = &(contents[i]);
+        char timebuf[256] = { 0 };
+        time_t t = (time_t)content->last_modified;
+        strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ",
+            gmtime(&t));
+        char sizebuf[16] = { 0 };
+        if (content->size < 100000) {
+            sprintf_s(sizebuf, sizeof(sizebuf), "%5llu", (unsigned long long) content->size);
+        }
+        else if (content->size < (1024 * 1024)) {
+            sprintf_s(sizebuf, sizeof(sizebuf), "%4lluK",
+                ((unsigned long long) content->size) / 1024ULL);
+        }
+        else if (content->size < (10 * 1024 * 1024)) {
+            float f = content->size;
+            f /= (1024 * 1024);
+            sprintf_s(sizebuf, sizeof(sizebuf), "%1.2fM", f);
+        }
+        else if (content->size < (1024 * 1024 * 1024)) {
+            sprintf_s(sizebuf, sizeof(sizebuf), "%4lluM",
+                ((unsigned long long) content->size) /
+                (1024ULL * 1024ULL));
+        }
+        else {
+            float f = (content->size / 1024);
+            f /= (1024 * 1024);
+            sprintf_s(sizebuf, sizeof(sizebuf), "%1.2fG", f);
+        }
+        printf("%-50s  %s  %s", content->key, timebuf, sizebuf);
+        if (data->allDetails) {
+            printf("  %-36s  %-64s  %-20s  %-16s  %-16s",
+                content->etag,
+                content->owner_id ? content->owner_id : "",
+                content->owner_display_name ? content->owner_display_name : "",
+                content->storage_class ? content->storage_class : "",
+                content->type ? content->type : ""
+            );
+        }
+        printf("\n");
+    }
+    data->keyCount += contents_count;
+    for (i = 0; i < common_prefixes_count; i++) {
+        printf("\nCommon Prefix: %s\n", common_prefixes[i]);
+    }
+    printf("contents_count:%d\n", contents_count);
+    return OBS_STATUS_OK;
+}
+
+
+
+
+
+
+
+
Parent topic: Object Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0604.html b/docs/obs_3rd_party/c_sdk/obs_20_0604.html new file mode 100644 index 000000000..89a0c19da --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0604.html @@ -0,0 +1,1836 @@ + + +

Deleting an Object

+

Function

This API deletes an object in the specified bucket to save space and costs.

+
+

Restrictions

  • To delete an object, you must be the bucket owner or have the required permission (obs:object:DeleteObject in IAM or DeleteObject in a bucket policy).
  • If versioning is not enabled for a bucket, deleted objects cannot be restored.
+
+

Method

1
+2
void delete_object(const obs_options *options, obs_object_info *object_info,
+	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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples: Deleting an Object

This example calls delete_object to delete a single object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to use delete_object to delete a single object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Information about the object to be deleted.
+    obs_object_info object_info;
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "example_get_file_test_delete";
+    object_info.version_id = NULL;
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    {
+        &response_properties_callback, &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Delete the object.
+    delete_object(&options, &object_info, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("delete object successfully. \n");
+    }
+    else
+    {
+        printf("delete object failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Object Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0605.html b/docs/obs_3rd_party/c_sdk/obs_20_0605.html new file mode 100644 index 000000000..815a8978e --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0605.html @@ -0,0 +1,3439 @@ + + +

Copying an Object

+

Function

This API copies an object stored in a specified bucket to another path by creating a copy of the object. You can copy an object of up to 5 GB in a single operation.

+
+

Restrictions

  • To copy an object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • This API requires carrying the information about the source bucket and object using headers. A message body cannot be carried.
  • The destination object size ranges from 0 to 5 GB. If the source object size exceeds 5 GB, you must use a multipart copying API by referring to Copying a Part.
+
+

Method

1
+2
+3
+4
+5
void copy_object(const obs_options *options, char *key, const char *version_id, 
+	obs_copy_destination_object_info *object_info,
+        unsigned int is_copy, obs_put_properties *put_properties, 
+	server_side_encryption_params *encryption_params,
+	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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

object_info

+

obs_copy_destination_object_info *

+

Yes

+

Explanation:

+

Information about the object to be copied.

+

Restrictions:

+

None

+

is_copy

+

unsigned int

+

Yes

+

Explanation:

+

Indicates whether the metadata of the destination object is copied from the source object or replaced with the metadata contained in the request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

put_properties

+

obs_put_properties*

+

No

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Server-side encryption configuration

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 12 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Value of the Expires header in the OBS request. It specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (downloading from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

If the object has not been modified after the specified time, the request is successful. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 23 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 25 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 26 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_copy_destination_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

destination_bucket

+

constchar*

+

Yes

+

Explanation:

+

Name of the destination bucket for replication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

destination_key

+

constchar*

+

Yes

+

Explanation:

+

Name of the destination object.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

constchar*

+

No

+

Explanation:

+

Version ID of the destination object.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

last_modified_return

+

int64_t *

+

Yes

+

Explanation:

+

Time when the object was last modified, in UTC.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag_return_size

+

int

+

Yes

+

Explanation:

+

Length of the returned ETag

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag_return

+

char*

+

Yes

+

Explanation:

+

128-bit MD5 digest of the Base64 code of a new object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+
+
+
+

Code Examples: Simple Copying

This example copies an object using copy_object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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); 
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to copy an object using copy_object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    char eTag[OBS_COMMON_LEN_256] = { 0 };
+    int64_t lastModified;
+    // Specify the destination object information.
+    obs_copy_destination_object_info objectinfo = { 0 };
+    objectinfo.destination_bucket = "example-dest-bucket-name";
+    objectinfo.destination_key = "example_destination_key";
+    objectinfo.etag_return = eTag;
+    objectinfo.etag_return_size = sizeof(eTag);
+    objectinfo.last_modified_return = &lastModified;
+    // Set the response callback function.
+    obs_response_handler responseHandler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    char* source_object_key = "example_source_object_key";
+    char* source_object_version_id = NULL;
+    // Copy an object.
+    copy_object(&options, source_object_key, source_object_version_id, &objectinfo, 1, NULL, NULL, &responseHandler, &ret_status);
+    if (OBS_STATUS_OK == ret_status && eTag[0] != '\0') {
+        printf("test_copy_object successfully. \n");
+    }
+    else
+    {
+        printf("test_copy_object failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+

Code Examples: Specifying Copying Conditions

  • If the object copy request includes if_not_modified_since, if_match_etag, if_modified_since, or if_not_match_etag, and the specified condition is not met, the copy will fail and an exception will be thrown with HTTP status code 412 precondition failed returned.
  • if_modified_since and if_not_match_etag can be used together. So do if_not_modified_since and if_match_etag.
+
+
This example calls the copy_object function to perform conditional copy.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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); 
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to use the copy_object function to perform conditional copy:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    char eTag[OBS_COMMON_LEN_256] = { 0 };
+    int64_t lastModified;
+    // Specify the destination object information.
+    obs_copy_destination_object_info objectinfo = { 0 };
+    objectinfo.destination_bucket = "example-dest-bucket-name";
+    objectinfo.destination_key = "example_destination_key";
+    objectinfo.etag_return = eTag;
+    objectinfo.etag_return_size = sizeof(eTag);
+    objectinfo.last_modified_return = &lastModified;
+    //Specify conditions.
+    obs_put_properties putProperties = { 0 };
+    init_put_properties(&putProperties);
+    obs_get_conditions get_conditions = { 0 }; 
+    init_get_properties(&get_conditions);
+    putProperties.get_conditions = &get_conditions;
+    putProperties.get_conditions->if_match_etag = "2ea225dbff5b5b1d7bd6bd3b740681cd";
+    putProperties.get_conditions->if_modified_since = 0;
+    putProperties.get_conditions->if_not_match_etag = "34a7ef8cc629583f3cdd882791f31350";
+    putProperties.get_conditions->if_not_modified_since = INT_MAX;
+    // Set the response callback function.
+    obs_response_handler responseHandler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    char* source_object_key = "example_source_object_key";
+    char* source_object_version_id = NULL;
+    // Copy an object.
+    copy_object(&options, source_object_key, source_object_version_id, &objectinfo, 1, &putProperties, NULL, &responseHandler, &ret_status);
+    if (OBS_STATUS_OK == ret_status && eTag[0] != '\0') {
+        printf("test_copy_object successfully. \n");
+    }
+    else
+    {
+        printf("test_copy_object failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+

Code Examples: Rewriting an Object ACL

This example rewrites the ACL of the destination object when calling the copy_object function to copy an object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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); 
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to use the copy_object function to rewrite the ACL of the destination object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    char eTag[OBS_COMMON_LEN_256] = { 0 };
+    int64_t lastModified;
+    // Specify the destination object information.
+    obs_copy_destination_object_info objectinfo = { 0 };
+    objectinfo.destination_bucket = "example-dest-bucket-name";
+    objectinfo.destination_key = "example_destination_key";
+    objectinfo.etag_return = eTag;
+    objectinfo.etag_return_size = sizeof(eTag);
+    objectinfo.last_modified_return = &lastModified;
+    //Rewrite the ACL of the destination object.
+    obs_put_properties putProperties = { 0 };
+    init_put_properties(&putProperties);
+    putProperties.canned_acl = OBS_CANNED_ACL_PUBLIC_READ;
+    // Set the response callback function.
+    obs_response_handler responseHandler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    char* source_object_key = "example_source_object_key";
+    char* source_object_version_id = NULL;
+    // Copy an object.
+    copy_object(&options, source_object_key, source_object_version_id, &objectinfo, 1, &putProperties, NULL, &responseHandler, &ret_status);
+    if (OBS_STATUS_OK == ret_status && eTag[0] != '\0') {
+        printf("test_copy_object successfully. \n");
+    }
+    else
+    {
+        printf("test_copy_object failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Object Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0700.html b/docs/obs_3rd_party/c_sdk/obs_20_0700.html new file mode 100644 index 000000000..28f229635 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0700.html @@ -0,0 +1,1801 @@ + + +

Using a Temporary URL for Authorized Access

+

Function

This API creates a temporary URL to grant temporary permissions for operating OBS. This URL contains the information about the AK and SK, request method, and related parameters. You need to specify a validity period for the URL during the creation. To create such a URL, you need to use the temp_auth_configure structure.

+

The temp_auth_configure structure exists in the obs_options structure. This method is applicable to each C SDK API.

+ +
+ + + + + + + + + + + + + + + +

Parameter

+

Description

+

Structure in SDK

+

expires

+

Validity period of the generated temporary URL

+

obs_options. temp_auth_configure

+

temp_auth_callback

+

The callback function used to return the generated temporary URL

+

callback_data

+

Callback data

+
+
+
+

Restrictions

+
  • If a CORS or signature mismatch error occurs, troubleshoot the issue as follows:
    1. If CORS is not configured, you need to configure CORS rules on OBS Console.
    2. If the signatures do not match, check whether signature parameters are missing or invalid. For example, during an object upload, the backend uses Content-Type to calculate the signature and generate a temporary URL, but if Content-Type is not set or is set to an invalid value when the frontend uses that URL, a CORS error occurs. To resolve this issue, ensure Content-Type remains consistent at the frontend and backend.
    +
+
+

Method

void (*temp_auth_callback)(char *temp_auth_url, uint64_t temp_auth_url_len, char *temp_auth_headers,
+        uint64_t temp_auth_headers_len, void *callback_data);
+
+

To access OBS using a temporary URL generated by the OBS SDK for C, perform the following steps:

+
  1. Call any interface in the SDK to generate a temporary URL and headers based on the following code example.
  2. Use any HTTP library to make an HTTP/HTTPS request to OBS.
+

The following code examples use a temporary URL to create a bucket or upload, download, list, or delete objects.

+

Code Examples: Generating a Temporary URL for Creating a Bucket

This example generates a temporary URL for creating a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
#include "eSDKOBS.h"
+#include <stdio.h>
+#define MAX_TEMP_URL_LEN 1024
+#define MAX_HEADER_LEN 1024
+// 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 completion callback function. 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 __tempAuthResult
+{
+    char tmpAuthUrl[MAX_TEMP_URL_LEN];
+    char actualHeaders[MAX_HEADER_LEN];
+}tempAuthResult;
+void tempAuthCallBack_getResult(char *tempAuthUrl, uint64_t tempAuthUrlLen, char *tempAuthActualHeaders,
+    uint64_t tempAuthActualHeadersLen, void *callbackData);
+int main()
+{
+    // The following code shows how to generate a URL for creating a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    temp_auth_configure tempauth;
+    tempAuthResult  ptrResult;
+    memset(&ptrResult, 0, sizeof(tempAuthResult));
+    //Callback data
+    tempauth.callback_data = (void *)(&ptrResult);
+    // Validity period
+    tempauth.expires = 10;
+    // The callback function returns the generated temporary URL.
+    tempauth.temp_auth_callback = &tempAuthCallBack_getResult;
+    options.temp_auth = &tempauth;
+    // Assign values to the callback function.
+    obs_response_handler response_handler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Call the interface.
+    create_bucket(&options, OBS_CANNED_ACL_PRIVATE, NULL, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("the temporary signature url of create bucket generated successfully. \n"
+            "the temporary signature url is %s. \n"
+            "the actualHeaders are %s. \n", ptrResult.tmpAuthUrl, ptrResult.actualHeaders);
+    }
+    else
+    {
+        printf(" the temporary signature url of create bucket generation failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void tempAuthCallBack_getResult(char *tempAuthUrl, uint64_t tempAuthUrlLen, char *tempAuthActualHeaders,
+    uint64_t tempAuthActualHeadersLen, void *callbackData)
+{
+    int urlLen = 0;
+    tempAuthResult * ptrResult = (tempAuthResult *)callbackData;
+    urlLen = strlen(tempAuthUrl);
+    strcpy_s(ptrResult->tmpAuthUrl, MAX_TEMP_URL_LEN, tempAuthUrl);
+    strcpy_s(ptrResult->actualHeaders, MAX_HEADER_LEN, tempAuthActualHeaders);
+}
+
+
+
+
+

Code Examples: Generating a Temporary URL for Uploading an Object

This example generates a temporary URL for uploading an object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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 __tempAuthResult
+{
+    char tmpAuthUrl[1024];
+    char actualHeaders[1024];
+}tempAuthResult;
+void tempAuthCallBack_getResult(char *tempAuthUrl, uint64_t tempAuthUrlLen, char *tempAuthActualHeaders,
+    uint64_t tempAuthActualHeadersLen, void *callbackData);
+int main()
+{
+    // The following code shows how to generate a URL for uploading an object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    temp_auth_configure tempauth;
+    tempAuthResult  ptrResult;
+    memset(&ptrResult, 0, sizeof(tempAuthResult));
+    //Callback data
+    tempauth.callback_data = (void *)(&ptrResult);
+    // Validity period
+    tempauth.expires = 10;
+    // The callback function returns the generated temporary URL.
+    tempauth.temp_auth_callback = &tempAuthCallBack_getResult;
+    options.temp_auth = &tempauth;
+    // Assign values to the callback function.
+    obs_response_handler response_handler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    char* key = "example-object-key";
+    obs_put_object_handler putobjectHandler =
+    {
+        response_handler,
+        NULL
+    };
+    // Initialize the put_properties structure.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Call the interface.
+    put_object(&options, key, 0, &put_properties, 0, &putobjectHandler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("the temporary signature url of put object generated successfully. \n"
+            "the temporary signature url is %s. \n"
+            "the actualHeaders are %s. \n", ptrResult.tmpAuthUrl, ptrResult.actualHeaders);
+    }
+    else
+    {
+        printf(" the temporary signature url of put object generation failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void tempAuthCallBack_getResult(char *tempAuthUrl, uint64_t tempAuthUrlLen, char *tempAuthActualHeaders,
+    uint64_t tempAuthActualHeadersLen, void *callbackData)
+{
+    int urlLen = 0;
+    tempAuthResult * ptrResult = (tempAuthResult *)callbackData;
+    urlLen = strlen(tempAuthUrl);
+    strcpy_s(ptrResult->tmpAuthUrl, 1024, tempAuthUrl);
+    strcpy_s(ptrResult->actualHeaders, 1024, tempAuthActualHeaders);
+}
+
+
+
+
+

Code Examples: Generating a Temporary URL for Downloading an Object

This example generates a temporary URL for downloading an object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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 __tempAuthResult
+{
+    char tmpAuthUrl[1024];
+    char actualHeaders[1024];
+}tempAuthResult;
+void tempAuthCallBack_getResult(char *tempAuthUrl, uint64_t tempAuthUrlLen, char *tempAuthActualHeaders,
+    uint64_t tempAuthActualHeadersLen, void *callbackData);
+int main()
+{
+    // The following code shows how to generate a URL for downloading an object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    temp_auth_configure tempauth;
+    tempAuthResult  ptrResult;
+    memset(&ptrResult, 0, sizeof(tempAuthResult));
+    //Callback data
+    tempauth.callback_data = (void *)(&ptrResult);
+    // Validity period
+    tempauth.expires = 10;
+    // The callback function returns the generated temporary URL.
+    tempauth.temp_auth_callback = &tempAuthCallBack_getResult;
+    options.temp_auth = &tempauth;
+    // Assign values to the callback function.
+    obs_response_handler response_handler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    char* key = "example-object-key";
+    char* versionid = NULL;
+    // Downloaded object information
+    obs_object_info object_info;
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = key;
+    object_info.version_id = versionid;
+    obs_get_object_handler getobjectHandler =
+    {
+        response_handler,
+        NULL
+    };
+    // Initialize the put_properties structure.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Call the interface.
+    get_object(&options, &object_info, 0, 0, &getobjectHandler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("the temporary signature url of get object generated successfully. \n"
+            "the temporary signature url is %s. \n"
+            "the actualHeaders are %s. \n", ptrResult.tmpAuthUrl, ptrResult.actualHeaders);
+    }
+    else
+    {
+        printf(" the temporary signature url of get object generation failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void tempAuthCallBack_getResult(char *tempAuthUrl, uint64_t tempAuthUrlLen, char *tempAuthActualHeaders,
+    uint64_t tempAuthActualHeadersLen, void *callbackData)
+{
+    int urlLen = 0;
+    tempAuthResult * ptrResult = (tempAuthResult *)callbackData;
+    urlLen = strlen(tempAuthUrl);
+    strcpy_s(ptrResult->tmpAuthUrl, 1024, tempAuthUrl);
+    strcpy_s(ptrResult->actualHeaders, 1024, tempAuthActualHeaders);
+}
+
+
+
+
+

Code Examples: Generating a Temporary URL for Listing Objects

This example generates a temporary URL for listing objects.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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 __tempAuthResult
+{
+    char tmpAuthUrl[1024];
+    char actualHeaders[1024];
+}tempAuthResult;
+void tempAuthCallBack_getResult(char *tempAuthUrl, uint64_t tempAuthUrlLen, char *tempAuthActualHeaders,
+    uint64_t tempAuthActualHeadersLen, void *callbackData);
+int main()
+{
+    // The following code shows how to generate a URL for listing objects:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    temp_auth_configure tempauth;
+    tempAuthResult  ptrResult;
+    memset(&ptrResult, 0, sizeof(tempAuthResult));
+    //Callback data
+    tempauth.callback_data = (void *)(&ptrResult);
+    // Validity period
+    tempauth.expires = 10;
+    // The callback function returns the generated temporary URL.
+    tempauth.temp_auth_callback = &tempAuthCallBack_getResult;
+    options.temp_auth = &tempauth;
+    // Assign values to the callback function.
+    obs_response_handler response_handler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    char* prefix = "example-prefix";
+    char* next_marker = "example-next-marker";
+    char* delimiter = "/";
+    //Maximum number of objects that can be listed
+    int maxkeys = 100;
+    obs_list_objects_handler list_bucket_objects_handler =
+    {
+        response_handler,
+        NULL
+    };
+    list_bucket_objects(&options, prefix, next_marker, delimiter, maxkeys,
+        &list_bucket_objects_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("the temporary signature url of list objects generated successfully. \n"
+            "the temporary signature url is %s. \n"
+            "the actualHeaders are %s. \n", ptrResult.tmpAuthUrl, ptrResult.actualHeaders);
+    }
+    else
+    {
+        printf(" the temporary signature url of list objects generation failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void tempAuthCallBack_getResult(char *tempAuthUrl, uint64_t tempAuthUrlLen, char *tempAuthActualHeaders,
+    uint64_t tempAuthActualHeadersLen, void *callbackData)
+{
+    int urlLen = 0;
+    tempAuthResult * ptrResult = (tempAuthResult *)callbackData;
+    urlLen = strlen(tempAuthUrl);
+    strcpy_s(ptrResult->tmpAuthUrl, 1024, tempAuthUrl);
+    strcpy_s(ptrResult->actualHeaders, 1024, tempAuthActualHeaders);
+}
+
+
+
+
+

Code Examples: Generating a Temporary URL for Deleting an Object

This example generates a temporary URL for deleting an object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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 __tempAuthResult
+{
+    char tmpAuthUrl[1024];
+    char actualHeaders[1024];
+}tempAuthResult;
+void tempAuthCallBack_getResult(char *tempAuthUrl, uint64_t tempAuthUrlLen, char *tempAuthActualHeaders,
+    uint64_t tempAuthActualHeadersLen, void *callbackData);
+int main()
+{
+    // The following code shows how to generate a URL for deleting an object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    temp_auth_configure tempauth;
+    tempAuthResult  ptrResult;
+    memset(&ptrResult, 0, sizeof(tempAuthResult));
+    //Callback data
+    tempauth.callback_data = (void *)(&ptrResult);
+    // Validity period
+    tempauth.expires = 10;
+    // The callback function returns the generated temporary URL.
+    tempauth.temp_auth_callback = &tempAuthCallBack_getResult;
+    options.temp_auth = &tempauth;
+    // Assign values to the callback function.
+    obs_response_handler response_handler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    char* key = "example-object-key";
+    char* versionid = NULL;
+    // Information about the object to be deleted.
+    obs_object_info object_info;
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = key;
+    object_info.version_id = versionid;
+    delete_object(&options, &object_info, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("the temporary signature url of put object generated successfully. \n"
+            "the temporary signature url is %s. \n"
+            "the actualHeaders are %s. \n", ptrResult.tmpAuthUrl, ptrResult.actualHeaders);
+    }
+    else
+    {
+        printf(" the temporary signature url of put object generation failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void tempAuthCallBack_getResult(char *tempAuthUrl, uint64_t tempAuthUrlLen, char *tempAuthActualHeaders,
+    uint64_t tempAuthActualHeadersLen, void *callbackData)
+{
+    int urlLen = 0;
+    tempAuthResult * ptrResult = (tempAuthResult *)callbackData;
+    urlLen = strlen(tempAuthUrl);
+    strcpy_s(ptrResult->tmpAuthUrl, 1024, tempAuthUrl);
+    strcpy_s(ptrResult->actualHeaders, 1024, tempAuthActualHeaders);
+}
+
+
+
+
+
+
+
+
Parent topic: Other APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0800.html b/docs/obs_3rd_party/c_sdk/obs_20_0800.html new file mode 100644 index 000000000..7827f8305 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0800.html @@ -0,0 +1,31 @@ + + +

Versioning

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0802.html b/docs/obs_3rd_party/c_sdk/obs_20_0802.html new file mode 100644 index 000000000..38987eb20 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0802.html @@ -0,0 +1,1762 @@ + + +

Configuring Versioning for a Bucket

+

Function

You can enable versioning to automatically maintain previous versions of an object. When versioning is enabled, you can access earlier versions of an object to recover your data in the event of accidental actions or application failures.

+

This API configures versioning for a bucket.

+
+

Restrictions

  • To configure versioning for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutBucketVersioning in IAM or PutBucketVersioning in a bucket policy).
+
+

Method

void set_bucket_version_configuration(const obs_options *options, const char *version_status, 
+           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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

version_status

+

char *

+

Yes

+

Explanation:

+

The versioning status of a bucket.

+

Restrictions:

+

None

+

Value range:

+
  • OBS_VERSION_STATUS_ENABLED
  • OBS_VERSION_STATUS_SUSPENDED
+

Default value:

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Configuring Versioning for a Bucket

This example configures versioning for a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to configure versioning for a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    // Set the storage class of the bucket. The following uses Standard as an example.
+    options.bucket_options.storage_class = OBS_STORAGE_CLASS_STANDARD;
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Enable versioning for the bucket.
+    set_bucket_version_configuration(&options, OBS_VERSION_STATUS_ENABLED,
+        &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("set bucket version successfully. \n");
+    }
+    else
+    {
+        printf("set bucket version failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0803.html b/docs/obs_3rd_party/c_sdk/obs_20_0803.html new file mode 100644 index 000000000..80f2461b5 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0803.html @@ -0,0 +1,1780 @@ + + +

Obtaining the Versioning Status of a Bucket

+

Function

You can enable versioning to automatically maintain previous versions of an object. When versioning is enabled, you can access earlier versions of an object to recover your data in the event of accidental actions or application failures.

+

This API obtains the versioning status of a bucket.

+
+

Restrictions

  • To view the versioning status of a bucket, you must be the bucket owner or have the required permission (obs:bucket:GetBucketVersioning in IAM or GetBucketVersioning in a bucket policy).
+
+

Method

void get_bucket_version_configuration(const obs_options *options, int status_return_size, 
+        char *status_return, 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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

status_return_size

+

int

+

Yes

+

Explanation:

+

Size of the versioning status cache

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

status_return

+

char *

+

Yes

+

Explanation:

+

Versioning status cache

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Obtaining the Versioning Status of a Bucket

This example obtains the versioning status of a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to obtain the versioning status of a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    // Set the storage class of the bucket. The following uses Standard as an example.
+    options.bucket_options.storage_class = OBS_STORAGE_CLASS_STANDARD;
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Obtain the bucket versioning status.
+    char status[OBS_COMMON_LEN_256 + 1] = { 0 };
+    get_bucket_version_configuration(&options, sizeof(status), status,
+        &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("get bucket version successfully.\n policy=(%s)\n", status);
+    }
+    else
+    {
+        printf("get bucket version failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0804.html b/docs/obs_3rd_party/c_sdk/obs_20_0804.html new file mode 100644 index 000000000..dc3abb266 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0804.html @@ -0,0 +1,2349 @@ + + +

Obtaining an Object Version

+

Function

You can call get_object to obtain an object version by specifying the version ID (obs_object_info.version_id).

+

If the version ID is not specified, the object of the latest version will be downloaded.

+
+

Restrictions

  • To download an object version, you must be the bucket owner or have the required permission (obs:object:GetObject in IAM or GetObject in a bucket policy).
  • Versioned objects in the Cold storage class can be downloaded only when they are in the Restored status.
+
+

Method

void get_object(const obs_options *options, obs_object_info *object_info,
+        obs_get_conditions *get_conditions, 
+        server_side_encryption_params *encryption_params,
+        obs_get_object_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

get_conditions

+

obs_get_conditions *

+

Yes

+

Explanation:

+

Sets filter conditions of the object and read range.

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Obtains the decryption settings of an object.

+

Restrictions:

+

None

+

handler

+

obs_get_object_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_get_object_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

get_object_data_callback

+

obs_get_object_data_callback *

+

Yes

+

Explanation:

+

Pointer to the callback function, which is used to copy the data to be downloaded from the data buffer to the custom callback data.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_get_object_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

buffer_size

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

buffer

+

char *

+

Yes

+

Explanation:

+

Data buffer to be downloaded. Data in this buffer is copied to callback_data to download data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 20 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 22 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 23 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 25 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+
+

Code Examples: Obtaining an Object Version

This example downloads an object version as a local file using the get_object function.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data);
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct get_object_callback_data
+{
+    FILE *outfile;
+    obs_status ret_status;
+}get_object_callback_data;
+FILE * write_to_file(char *localfile);
+int main()
+{
+    // The following code shows how to use the get_object function to download an object version to a local file:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Set the name of the local file to which the object is downloaded.
+    char *file_name = "./example_get_file_test";
+    obs_object_info object_info;
+    // Set the object version to be downloaded.
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "example_get_file_test";
+    object_info.version_id = "G00111934EA2FAC2000040180A3CB360";
+    //Set the structure for storing the downloaded object data based on service requirements.
+    get_object_callback_data data;
+    data.ret_status = OBS_STATUS_BUTT;
+    data.outfile = write_to_file(file_name);
+    // Define parameters for range-based download.
+    obs_get_conditions getcondition;
+    memset(&getcondition, 0, sizeof(obs_get_conditions));
+    init_get_properties(&getcondition);
+    // Download start position. The default value is 0, indicating that the download starts from byte 0.
+    getcondition.start_byte = 0;
+    // Download length. The default value is 0, indicating that the object is downloaded until the end.
+    // getcondition.byte_count = 0;
+    // Define the download callback function.
+    obs_get_object_handler get_object_handler =
+    {
+        { &response_properties_callback,
+          &get_object_complete_callback},
+        &get_object_data_callback
+    };
+    get_object(&options, &object_info, &getcondition, 0, &get_object_handler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("get object successfully. \n");
+    }
+    else
+    {
+        printf("get object failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    fclose(data.outfile);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    size_t wrote = fwrite(buffer, 1, buffer_size, data->outfile);
+    return ((wrote < (size_t)buffer_size) ?
+        OBS_STATUS_AbortedByCallback : OBS_STATUS_OK);
+}
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+FILE * write_to_file(char *localfile)
+{
+    FILE *outfile = 0;
+    if (localfile) {
+        struct stat buf;
+        if (stat(localfile, &buf) == -1) {
+            outfile = fopen(localfile, "wb");
+        }
+        else {
+            outfile = fopen(localfile, "a");
+        }
+        if (!outfile) {
+            fprintf(stderr, "\nERROR: Failed to open output file %s: ",
+                localfile);
+            return outfile;
+        }
+    } else {
+        fprintf(stderr, "\nERROR: Failed to open output file, it's NULL, write object to stdout.",
+            localfile);
+        outfile = stdout;
+    }
+    return outfile;
+}
+
+
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0805.html b/docs/obs_3rd_party/c_sdk/obs_20_0805.html new file mode 100644 index 000000000..d1b6fe1e8 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0805.html @@ -0,0 +1,2784 @@ + + +

Copying an Object Version

+

Function

This API copies an object version in a specified bucket. You can create a copy up to 5 GB for a versioned object in a single operation.

+
+

Restrictions

  • To copy a versioned object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • This API requires carrying the information about the source bucket and object using headers. A message body cannot be carried.
  • The object copy ranges from 0 GB to 5 GB. If the source object size exceeds 5 GB, you can only use the Copying a Part function to copy.
+
+

Method

1
+2
+3
+4
+5
void copy_object(const obs_options *options, char *key, const char *version_id, 
+        obs_copy_destination_object_info *object_info,
+        unsigned int is_copy, obs_put_properties *put_properties, 
+        server_side_encryption_params *encryption_params,
+        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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

object_info

+

obs_copy_destination_object_info *

+

Yes

+

Explanation:

+

Information about the object to be copied.

+

Restrictions:

+

None

+

is_copy

+

unsigned int

+

Yes

+

Explanation:

+

Indicates whether the metadata of the destination object is copied from the source object or replaced with the metadata contained in the request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

put_properties

+

obs_put_properties*

+

No

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Server-side encryption configuration

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 12 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Value of the Expires header in the OBS request. It specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (downloading from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

If the object has not been modified after the specified time, the request is successful. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 23 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 25 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 26 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_copy_destination_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

destination_bucket

+

constchar*

+

Yes

+

Explanation:

+

Name of the destination bucket for replication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

destination_key

+

constchar*

+

Yes

+

Explanation:

+

Name of the destination object.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

constchar*

+

No

+

Explanation:

+

Version ID of the destination object.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

last_modified_return

+

int64_t *

+

Yes

+

Explanation:

+

Time when the object was last modified, in UTC.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag_return_size

+

int

+

Yes

+

Explanation:

+

Length of the returned ETag

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag_return

+

char*

+

Yes

+

Explanation:

+

128-bit MD5 digest of the Base64 code of a new object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+
+
+
+

You can call copy_object to pass the version ID (version_id) to copy a versioned object. The sample code is as follows:

+

Code Examples: Copying a Versioned Object

This example copies an object version using the copy_object function.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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); 
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to copy an object version using the copy_object function:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    char eTag[OBS_COMMON_LEN_256] = { 0 };
+    int64_t lastModified;
+    // Specify the destination object information.
+    obs_copy_destination_object_info objectinfo = { 0 };
+    objectinfo.destination_bucket = "example-dest-bucket-name";
+    objectinfo.destination_key = "example_destination_key";
+    objectinfo.etag_return = eTag;
+    objectinfo.etag_return_size = sizeof(eTag);
+    objectinfo.last_modified_return = &lastModified;
+    // Set the response callback function.
+    obs_response_handler responseHandler =
+    {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    char* source_object_key = "example_source_object_key";
+    char* source_object_version_id = "G00111934EAA2CE900004016129AC990";
+    // Copy an object.
+    copy_object(&options, source_object_key, source_object_version_id, &objectinfo, 1, NULL, NULL, &responseHandler, &ret_status);
+    if (OBS_STATUS_OK == ret_status && eTag[0] != '\0') {
+        printf("test_copy_object successfully. \n");
+    }
+    else
+    {
+        printf("test_copy_object failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    (void)callback_data;
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0806.html b/docs/obs_3rd_party/c_sdk/obs_20_0806.html new file mode 100644 index 000000000..dba62adfd --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0806.html @@ -0,0 +1,1892 @@ + + +

Restoring a Specific Cold Object Version

+

Function

To obtain the content of an object version in the Cold storage class, you need to restore the object version first and then you can download it. After an object version is restored, a copy of it is saved in the Standard storage class. By doing so, the object version in the Cold storage class and its copy in the Standard storage class co-exist in the bucket. The copy will be automatically deleted once its retention period ends.

+

This API is used to restore Cold versioned objects in a specified bucket.

+
+

Restrictions

  • To restore a Cold object version, you must be the bucket owner or have the required permission (obs:object:RestoreObject in IAM or RestoreObject in a bucket policy.)
  • To prolong the validity period of the Cold data restored, you can repeatedly restore the data, but you will be billed for each restore. After a restoration, the validity period of Standard object copies will be extended, and you need to pay for storing these copies during the extended period.
+
+

Method

void restore_object(const obs_options *options, obs_object_info *object_info, const char *days, 
+        obs_tier tier,const 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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

days

+

char *

+

Yes

+

Explanation:

+

Retention period of the restored object

+

Restrictions:

+

None

+

Value range:

+

The value ranges from 1 to 30, in days.

+

Default value:

+

None

+

tier

+

obs_tier

+

No

+

Explanation:

+

Restore options: obs_tier.OBS_TIER_EXPEDITED or obs_tier.OBS_TIER_STANDARD

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_tier.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+
  • The name of each object in a bucket must be unique.
  • The object specified must be in the Cold storage class. Otherwise, an error is reported.
+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 12 obs_tier

Value

+

Description

+

OBS_TIER_NULL

+

Default invalid value.

+

OBS_TIER_STANDARD

+

It indicates that objects can be restored from Cold storage within 3 to 5 hours.

+

OBS_TIER_EXPEDITED

+

It indicates that objects can be quickly restored from Cold storage within 1 to 5 minutes.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

You can call restore_object to restore a Cold object version by specifying obs_object_info.version_id. Sample code is as follows:

+

Code Examples: Restoring a Cold Object Version

This example calls restore_object to pass the version ID (obs_object_info.version_id) to restore a Cold object version.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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 completion callback function. 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);
+int main()
+{
+    // The following code calls restore_object to pass the version ID (obs_object_info.version_id) to restore a Cold object version:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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_object_info object_info;
+    // Set the object to be downloaded.
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "example_get_file_test_restore";
+    object_info.version_id = "G00111934ED39BD60000401401EDE57B";
+    // Set the response callback function.
+    obs_response_handler handler =
+    {
+      &response_properties_callback, &response_complete_callback
+    };
+    // Restore the object.
+    obs_tier tier = OBS_TIER_EXPEDITED; 
+    obs_status ret_status = OBS_STATUS_BUTT;
+    const char* storedDays = "1"; 
+    options.request_options.auth_switch = OBS_OBS_TYPE;
+    restore_object(&options, &object_info, storedDays, tier, &handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("restore object successfully. \n");
+    }
+    else
+    {
+        printf("restore object failed(%s).\n", obs_get_status_name(ret_status));
+        return;
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *data =
+            (obs_status *)callback_data;
+        *data = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+
+
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0807.html b/docs/obs_3rd_party/c_sdk/obs_20_0807.html new file mode 100644 index 000000000..ed6bf18da --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0807.html @@ -0,0 +1,2601 @@ + + +

Listing Object Versions in a Bucket

+

Function

This API lists some or all of the object versions in a bucket. You can use parameters such as the prefix, number of returned object versions, and start position to list the object versions that meet specified criteria. Returned object versions are listed in alphabetical order by object name.

+
+

Restrictions

  • To list object versions in a bucket, you must be the bucket owner or have the required permission (obs:bucket:ListBucketVersions in IAM or ListBucketVersions in a bucket policy).
+
+

Method

void list_versions(const obs_options *options, const char *prefix, const char *key_marker, 
+        const char *delimiter, int maxkeys, const char *version_id_marker, 
+        obs_list_versions_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

prefix

+

char *

+

No

+

Explanation:

+

Name prefix that the objects to be listed must contain

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

key_marker

+

char *

+

No

+

Explanation:

+

Object name to start with when listing object versions in a bucket. All object versions following the specified value are listed in lexicographical order by object name.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

delimiter

+

char *

+

No

+

Explanation:

+

The character used to group object names. If the object name contains the value specified by the delimiter parameter, the string from the first character to the first delimiter in the object name (excluding the prefix if prefix is specified) is grouped into one common_prefixes to be returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id_marker

+

char *

+

No

+

Explanation:

+

Version ID to start with when listing objects in a bucket. All objects are listed in alphabetical order by object name and version ID. This parameter must be used together with key_marker.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

maxkeys

+

int

+

Yes

+

Explanation:

+

Maximum number of objects that can be listed.

+

Restrictions:

+

If the specified value is greater than 1000, 1000 is used by default.

+

Value range:

+

An integer from 1 to 1000

+

Default value:

+

1000

+

handler

+

obs_list_versions_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_list_versions_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

list_versions_callback

+

obs_list_versions_callback *

+

Yes

+

Explanation:

+

The callback function pointer tag. The listed results in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_list_versions_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

is_truncated

+

int

+

Yes

+

Explanation:

+

Indicates whether the returned result list is truncated.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

next_key_marker

+

const char *

+

Yes

+

Explanation:

+

Object name to start with upon the next request for listing versioning objects in a bucket. This element is returned when not all the objects are listed. You can set key_marker to this value in the next request to list the remaining multipart uploads.

+

Restrictions:

+

This parameter is only available for listing objects with multiple versions.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

next_versionid_marker

+

const char *

+

Yes

+

Explanation:

+

Version ID to start with in the next request for listing object versions. It must be used together with next_key_marker. This parameter is returned if some listing results were not returned. You can set version_id_marker of the next request to the returned value to list the remaining results.

+

Restrictions:

+

This parameter is only available for listing objects with multiple versions.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

versions

+

const obs_list_versions*

+

Yes

+

Explanation:

+

Listed information about versions.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_list_versions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_name

+

const char *

+

No

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

prefix

+

const char *

+

No

+

Explanation:

+

Name prefix that the objects to be listed must contain

+

Restrictions:

+

None

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

key_marker

+

const char *

+

No

+

Explanation:

+

Object name to start with when listing object versions in a bucket. All object versions following the specified value are listed in lexicographical order by object name.

+

Restrictions:

+

This parameter is only available for listing objects with multiple versions.

+

Value range:

+

The value of nextKeyMarker in the response body of the last request.

+

Default value:

+

None

+

delimiter

+

const char *

+

No

+

Explanation:

+

This parameter is used to group object names. If a prefix is specified, objects with the same string from the prefix to the first delimiter are grouped into one CommonPrefixes. If no prefix is specified, objects with the same string from the first character to the first delimiter are grouped into one CommonPrefixes.

+

Assume that a bucket has objects abcd, abcde, and bbcde in it. If delimiter is set to d and prefix is set to a, objects abcd and abcde are grouped into a commonPrefix with abcd as the prefix. If only delimiter is set to d, objects abcd and abcde are grouped into a commonPrefix with abcd as the prefix, and bbcde is grouped separately into another commonPrefix with bbcd as the prefix.

+

For a parallel file system, if this parameter is not specified, all the content in the directory is recursively listed by default, including the content in subdirectories. In big data scenarios, file systems usually have multiple directory levels and each directory level has a large number of objects. In such case, you are advised to configure [delimiter=/] to list the content in the current directory but exclude the content in subdirectories, thereby making the listing more efficient.

+

Restrictions:

+

None

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

max_keys

+

const char *

+

No

+

Explanation:

+

The maximum number of object versions returned in the response in alphabetical order.

+

Restrictions:

+

If the specified value is greater than 1000, 1000 is used by default.

+

Value range:

+

An integer from 1 to 1000

+

Default value:

+

1000

+

versions

+

obs_version *

+

No

+

Explanation:

+

Object information

+

Restrictions:

+

None

+

versions_count

+

int

+

No

+

Explanation:

+

Number of versions.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

common_prefixes

+

const char **

+

No

+

Explanation:

+

List of object name prefixes grouped according to the delimiter parameter (if specified)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

common_prefixes_count

+

int

+

No

+

Explanation:

+

Number of common prefixes.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_version

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

const char *

+

No

+

Explanation:

+

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

is_latest

+

const char *

+

No

+

Explanation:

+

Whether the object is the latest version.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

last_modified

+

int64_t

+

No

+

Explanation:

+

Time when the object was last modified, in UTC.

+

Restrictions:

+

None

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag value is a hash of the object. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag after MD5 encryption.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

size

+

uint64_t

+

No

+

Explanation:

+

Object size in bytes.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

owner_id

+

const char *

+

No

+

Explanation:

+

Domain ID (account ID) of the object owner.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the account ID of the bucket owner, see How Do I Get My Account ID and User ID?

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

is_delete

+

const char *

+

No

+

Explanation:

+

Whether the object version is a delete marker.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples: Listing Object Versions

This example calls the list_versions function to list object versions in a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
+295
+296
+297
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <time.h>
+#include <sys/stat.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);
+typedef struct list_versions_callback_data
+{
+    char bucket_name[1024];
+    char prefix[1024];
+    char key_marker[1024];
+    char delimiter[1024];
+    int max_keys;
+    int is_truncated;
+    char next_key_marker[1024];
+    char next_versionId_marker[1024];
+    int keyCount;
+    int allDetails;
+    obs_status ret_status;
+} list_versions_callback_data;
+static void list_versions_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+static obs_status listVersionsCallback(int is_truncated, const char *next_key_marker, const char *next_versionId_marker,
+    const obs_list_versions *list_versions, void *callback_data);
+int main()
+{
+    // The following code shows how to use the list_versions function to list object versions in a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    char * prefix = "example";
+    char * key_marker = "";
+    char * delimiter = "/";
+    int maxkeys = 1000;
+    // Set the response callback function.
+    obs_list_versions_handler list_versions_handler =
+    {
+        { &response_properties_callback, &list_versions_complete_callback },
+        &listVersionsCallback
+    };
+    // Create and initialize callback data.
+    list_versions_callback_data data;
+    char* version_id_marker = NULL;
+    memset(&data, 0, sizeof(list_versions_callback_data));
+    data.ret_status = OBS_STATUS_BUTT;
+    snprintf(data.next_key_marker, sizeof(data.next_key_marker), "%s", key_marker);
+    if (version_id_marker)
+    {
+        snprintf(data.next_versionId_marker, sizeof(data.next_versionId_marker), "%s", version_id_marker);
+    }
+    data.keyCount = 0;
+    data.allDetails = 1;
+    data.is_truncated = 0;
+    // List object versions. Specify the object prefix using prefix and the number of versions to be listed using maxkeys. Objects can be listed in pagination.
+    // Specify delimiter as the character for listing by group. For listing by folder, set delimiter to /.
+    // Use key_marker to specify the start position for listing. Specify version_id_marker as the start version ID for listing.
+    list_versions(&options, prefix, key_marker, delimiter, maxkeys, version_id_marker,
+        &list_versions_handler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("list versions successfully. \n");
+    }
+    else
+    {
+        printf("list versions failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+static void list_versions_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    if (callback_data) {
+        list_versions_callback_data *data = (list_versions_callback_data*)callback_data;
+        data->ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+static void printListVersionsHeader(int allDetails)
+{
+    printf("%-30s  %-20s  %-5s  %-32s",
+        "              Key",
+        "    Last Modified", " Size", "           VersionId");
+    if (allDetails) {
+        printf("  %-34s  %-12s  %-12s  %-12s",
+            "               ETag",
+            "Storage Class",
+            "Owner ID",
+            "                    Display Name");
+    }
+    printf("\n");
+    printf("------------------------------  "
+        "--------------------  -----  --------------------------------");
+    if (allDetails) {
+        printf("  ----------------------------------  ------------  --------------------------------   ------------");
+    }
+    printf("\n");
+}
+static obs_status listVersionsCallback(int is_truncated, const char *next_key_marker, const char *next_versionId_marker,
+    const obs_list_versions *list_versions, void *callback_data)
+{
+    list_versions_callback_data *data =
+        (list_versions_callback_data *)callback_data;
+    data->is_truncated = is_truncated;
+    if ((!next_key_marker || !next_key_marker[0]) && list_versions->versions_count) {
+        next_key_marker = list_versions->versions[list_versions->versions_count - 1].key;
+    }
+    if (next_key_marker) {
+        snprintf(data->next_key_marker, sizeof(data->next_key_marker), "%s", next_key_marker);
+    }
+    else {
+        data->next_key_marker[0] = 0;
+    }
+    if ((!next_versionId_marker || !next_versionId_marker[0]) && list_versions->versions_count) {
+        next_versionId_marker = list_versions->versions[list_versions->versions_count - 1].version_id;
+    }
+    if (next_versionId_marker) {
+        snprintf(data->next_versionId_marker, sizeof(data->next_versionId_marker), "%s", next_versionId_marker);
+    }
+    else {
+        data->next_versionId_marker[0] = 0;
+    }
+    if (NULL != list_versions->bucket_name)
+    {
+        printf("Name = %s\n", list_versions->bucket_name);
+    }
+    if (NULL != list_versions->prefix)
+    {
+        printf("prefix = %s\n", list_versions->prefix);
+    }
+    if (NULL != list_versions->key_marker)
+    {
+        printf("key_marker = %s\n", list_versions->key_marker);
+    }
+    if (NULL != list_versions->delimiter)
+    {
+        printf("delimiter = %s\n", list_versions->delimiter);
+    }
+    if (NULL != list_versions->max_keys)
+    {
+        printf("max_keys = %s\n", list_versions->max_keys);
+    }
+    if (list_versions->versions_count && !data->keyCount) {
+        printListVersionsHeader(data->allDetails);
+    }
+    int i;
+    for (i = 0; i < list_versions->versions_count; i++) {
+        obs_version *version = &(list_versions->versions[i]);
+        char timebuf[256] = { 0 };
+        time_t t = (time_t)version->last_modified;
+        strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ",
+            gmtime(&t));
+        char sizebuf[16] = { 0 };
+        if (version->size < 100000) {
+            sprintf_s(sizebuf, sizeof(sizebuf), "%5llu", (unsigned long long) version->size);
+        }
+        else if (version->size < (1024 * 1024)) {
+            sprintf_s(sizebuf, sizeof(sizebuf), "%4lluK",
+                ((unsigned long long) version->size) / 1024ULL);
+        }
+        else if (version->size < (10 * 1024 * 1024)) {
+            float f = version->size;
+            f /= (1024 * 1024);
+            sprintf_s(sizebuf, sizeof(sizebuf), "%1.2fM", f);
+        }
+        else if (version->size < (1024 * 1024 * 1024)) {
+            sprintf_s(sizebuf, sizeof(sizebuf), "%4lluM",
+                ((unsigned long long) version->size) /
+                (1024ULL * 1024ULL));
+        }
+        else {
+            float f = (version->size / 1024);
+            f /= (1024 * 1024);
+            sprintf_s(sizebuf, sizeof(sizebuf), "%1.2fG", f);
+        }
+        printf("%-30s  %s  %s  %-32s", version->key, timebuf, sizebuf, version->version_id);
+        if (data->allDetails) {
+            printf("  %-34s  %-12s  %-32s  %-12s",
+                version->etag,
+                version->storage_class,
+                version->owner_id ? version->owner_id : "",
+                version->owner_display_name ?
+                version->owner_display_name : "");
+        }
+        printf("\n");
+    }
+    printf("versions_count=%d\n", list_versions->versions_count);
+    printf("---------------------------------------------------------------------------------");
+    printf("--------------------------------");
+    printf("---------------------------------------------------------------------------------\n");
+    for (i = 0; i < list_versions->common_prefixes_count; i++)
+    {
+        printf("commonPrefix => prefix = %s\n", *(list_versions->common_prefixes + i));
+    }
+    data->keyCount += list_versions->versions_count;
+    return OBS_STATUS_OK;
+}
+
+
+
+
  • Information about a maximum of 1000 versioning objects can be listed each time. If a bucket contains more than 1000 objects and is_truncated is true in the returned result, not all versioning objects are listed. In such cases, you can use next_key_marker and next_versionId_marker to obtain the start position for next listing.
  • If you want to obtain all versioning objects in a specified bucket, you can use the paging mode for listing objects.
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0809.html b/docs/obs_3rd_party/c_sdk/obs_20_0809.html new file mode 100644 index 000000000..ee56cb121 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0809.html @@ -0,0 +1,1833 @@ + + +

Deleting an Object Version

+

Function

This API deletes an object version in the specified bucket to save space and costs.

+
+

Restrictions

  • To delete an object version, you must be the bucket owner or have the required permission (obs:object:DeleteObject in IAM or DeleteObject in a bucket policy).
  • If versioning is not enabled for a bucket, deleted object versions cannot be restored.
+
+

Method

void delete_object(const obs_options *options, obs_object_info *object_info,
+        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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples

This example deletes an object version using delete_object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to delete a single object version using delete_object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Information about the object to be deleted.
+    obs_object_info object_info;
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "example_source_object_key";
+    object_info.version_id = "G00111934EAA2CE900004016129AC990";
+    // Set the response callback function.
+    obs_response_handler response_handler =
+    {
+        &response_properties_callback, &response_complete_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Delete the object.
+    delete_object(&options, &object_info, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("delete object successfully. \n");
+    }
+    else
+    {
+        printf("delete object failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0900.html b/docs/obs_3rd_party/c_sdk/obs_20_0900.html new file mode 100644 index 000000000..b4491744f --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0900.html @@ -0,0 +1,17 @@ + + +

Lifecycle Management

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0901.html b/docs/obs_3rd_party/c_sdk/obs_20_0901.html new file mode 100644 index 000000000..1a4dd7aea --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0901.html @@ -0,0 +1,18 @@ + + +

Overview

+

OBS allows you to set lifecycle rules for buckets to automatically transition the storage class of an object or delete expired objects, to effectively use storage features and optimize the storage space. You can set multiple lifecycle rules based on the prefix. A lifecycle rule contains:

+
  • Rule ID, which uniquely identifies the rule
  • Prefix of objects that are under the control of this rule
  • Transition policy of an object of the latest version, which can be specified in either mode:
    1. How many days after the object is created
    2. Transition date
    +
  • Expiration time of an object of the latest version, which can be specified in either mode:
    1. How many days after the object is created
    2. Expiration date
    +
  • Transition time for a historical object version, which is specified in the following mode:
    • How many days after an object version becomes historical
    +
  • Expiration time of a historical object version, which can be specified in the following mode:
    • How many days after the object becomes historical
    +
  • Identifier specifying whether the setting is effective
+
  • An object will be automatically deleted by the OBS server once it expires.
  • The time set in the transition policy of an object must be earlier than its expiration time, and the time set in the transition policy of a historical object version must be earlier than its expiration time.
  • The expiration time and transition policy for a historical object version will take effect only after versioning is enabled for buckets.
+
+
+
+
+
Parent topic: Lifecycle Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0902.html b/docs/obs_3rd_party/c_sdk/obs_20_0902.html new file mode 100644 index 000000000..6fa475462 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0902.html @@ -0,0 +1,3272 @@ + + +

Configuring Lifecycle Rules for a Bucket

+

Function

You can configure lifecycle rules to periodically delete objects or transition objects between storage classes.

+

This API configures lifecycle rules for a bucket.

+
+

Restrictions

  • There is no limit on the number of lifecycle rules in a bucket, but the total size of XML descriptions of all lifecycle rules in a bucket cannot exceed 20 KB.
  • A maximum of 20 lifecycle rules can be configured for a bucket.
  • To configure a lifecycle rule for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutLifecycleConfiguration in IAM or PutLifecycleConfiguration in a bucket policy).
+
+

Method

void set_bucket_lifecycle_configuration(const obs_options *options, 
+           obs_lifecycle_conf* bucket_lifecycle_conf, unsigned int blcc_number, 
+           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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

bucket_lifecycle_conf

+

obs_lifecycle_conf *

+

Yes

+

Explanation:

+

For details about the bucket lifecycle configuration, see the following table.

+

Restrictions:

+

None

+

blcc_number

+

unsigned int

+

Yes

+

Explanation:

+

Number of array members in the array bucket_lifecycle_conf.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

Standard storage class

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_lifecycle_conf

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

date

+

const char *

+

Yes if there is no days and no transition, noncurrent_version_days, or noncurrent_version_transition

+

Explanation:

+

Indicates the time when the object expiration rule of the latest version takes effect.

+

Restrictions:

+

The value must be compatible with the ISO 8601 format and must indicate 00:00 (UTC time).

+

Value range:

+

None

+

Default value:

+

None

+

days

+

const char *

+

Yes if there is no date and no transition, noncurrent_version_days, or noncurrent_version_transition

+

Explanation:

+

Number of days (since the object creation) after which the expiration rule will take effect.

+

Restrictions:

+

This parameter is only available for the latest object version.

+

Value range:

+

None

+

Default value:

+

None

+

id

+

const char *

+

No

+

Explanation:

+

ID of a rule.

+

Restrictions:

+

None

+

Value range:

+

The value is a string of a maximum of 255 characters.

+

Default value:

+

None

+

prefix

+

const char *

+

Yes

+

Explanation:

+

Object name prefix. It identifies the objects the rule applies to.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

status

+

const char *

+

Yes

+

Explanation:

+

Whether the rule is enabled

+

Restrictions:

+

None

+

Value range:

+
  • Enabled
  • Disabled
+

Default value:

+

None

+

noncurrent_version_days

+

const char *

+

No

+

Explanation:

+

The expiration time of objects' historical versions. If versioning is enabled or suspended for a bucket, you can set this parameter to delete historical versions of objects that match the lifecycle rule.

+

Restrictions:

+

This parameter is only available for historical object versions.

+

Value range:

+

None

+

Default value:

+

None

+

transition

+

obs_lifecycle_transtion *

+

Yes if there is no date, days, noncurrent_version_transition, or noncurrent_version_days

+

Explanation:

+

Transition time and the object storage class after transition

+

Restrictions:

+

This parameter is only available for the latest object version.

+

Value range:

+

None

+

Default value:

+

None

+

transition_num

+

unsigned int

+

Yes if transition is specified

+

Explanation:

+

Number of array members in the transition array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

noncurrent_version_transition

+

obs_lifecycle_noncurrent_transtion*

+

Yes if there is no date, days, transition, or noncurrent_version_days

+

Explanation:

+

Transition time of historical object versions and the object storage class after transition.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

noncurrent_version_transition_num

+

unsigned int

+

Yes if noncurrent_version_transition is specified

+

Explanation:

+

Number of array members in the array noncurrent_version_transition.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_lifecycle_transtion

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

date

+

const char *

+

Yes if the obs_lifecycle_transtion.days element is absent

+

Explanation:

+

Indicates the time when the object expiration rule of the latest version takes effect.

+

Restrictions:

+

The value must be compatible with the ISO 8601 format and must indicate 00:00 (UTC time).

+

Value range:

+

None

+

Default value:

+

None

+

days

+

const char *

+

Yes if the obs_lifecycle_transtion.date element is absent

+

Explanation:

+

Number of days (since the object creation) after which the expiration rule will take effect.

+

Restrictions:

+

This parameter is only available for the latest object version.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

Yes

+

Explanation:

+

The storage class to which the latest object version will be changed

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 20 obs_lifecycle_noncurrent_transtion

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

noncurrent_version_days

+

const char *

+

Yes

+

Explanation:

+

Number of days an object is historical before the specified transition rule takes effect

+

Restrictions:

+

This parameter is only available for historical object versions.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

Yes

+

Explanation:

+

The storage class to which historical versions will be changed

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 21 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 22 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 25 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 26 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Setting the Object Expiration Time

This example sets the expiration time for the latest and historical object versions.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to set the expiration time for the latest and historical object versions:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_lifecycle_conf bucket_lifecycle_conf;
+    memset(&bucket_lifecycle_conf, 0, sizeof(obs_lifecycle_conf));
+    //Lifecycle rule ID
+    bucket_lifecycle_conf.id = "test1";
+    // Specify the prefix as "test".
+    bucket_lifecycle_conf.prefix = "test";
+    // Specify that objects whose names contain the specified prefix will expire 10 days after creation.
+    bucket_lifecycle_conf.days = "10";
+    // Specify that objects whose names contain the specified prefix will expire 20 days after becoming historical versions.
+    bucket_lifecycle_conf.noncurrent_version_days = "20";
+    // Enable the lifecycle rule.
+    bucket_lifecycle_conf.status = "Enabled";
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    set_bucket_lifecycle_configuration(&options, &bucket_lifecycle_conf, 1,
+        &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("set bucket lifecycle configuration success.\n");
+    }
+    else
+    {
+        printf("set bucket lifecycle configuration failed(%s).\n",
+            obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+

Code Examples: Configuring the Object Transition Policy

This example sets the transition policy for the latest and historical object versions.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to set the transition policy for the latest and historical object versions:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_lifecycle_conf bucket_lifecycle_conf;
+    memset(&bucket_lifecycle_conf, 0, sizeof(obs_lifecycle_conf));
+    //Lifecycle rule ID
+    bucket_lifecycle_conf.id = "test3";
+    // Specify the prefix as "test".
+    bucket_lifecycle_conf.prefix = "bcd";
+    // Enable the lifecycle rule.
+    bucket_lifecycle_conf.status = "Enabled";
+    // Specify that objects whose names contain the specified prefix will expire 30 days after creation.
+    bucket_lifecycle_conf.days = "30";
+    obs_lifecycle_transtion transition;
+    memset(&transition, 0, sizeof(obs_lifecycle_transtion));
+    // Specify that objects whose names contain the specified prefix will be transitioned 10 days after creation.
+    transition.days = "10";
+    // Specify the storage class of the object after transition.
+    transition.storage_class = OBS_STORAGE_CLASS_STANDARD_IA;
+    bucket_lifecycle_conf.transition = &transition;
+    bucket_lifecycle_conf.transition_num = 1;
+    obs_lifecycle_noncurrent_transtion noncurrent_transition;
+    memset(&noncurrent_transition, 0, sizeof(obs_lifecycle_noncurrent_transtion));
+    // Specify that object versions whose names contain the specified prefix will be transitioned 30 days after becoming historical versions.
+    noncurrent_transition.noncurrent_version_days = "30";
+    // Specify the storage class of object versions whose names contain the specified prefix after transition.
+    noncurrent_transition.storage_class = OBS_STORAGE_CLASS_STANDARD_IA;
+    bucket_lifecycle_conf.noncurrent_version_transition = &noncurrent_transition;
+    bucket_lifecycle_conf.noncurrent_version_transition_num = 1;
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    set_bucket_lifecycle_configuration(&options, &bucket_lifecycle_conf, 1,
+        &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("set bucket lifecycle configuration success.\n");
+    }
+    else
+    {
+        printf("set bucket lifecycle configuration failed(%s).\n",
+            obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Lifecycle Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0903.html b/docs/obs_3rd_party/c_sdk/obs_20_0903.html new file mode 100644 index 000000000..87161fe1d --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0903.html @@ -0,0 +1,2169 @@ + + +

Obtaining the Lifecycle Rules of a Bucket

+

Function

You can configure lifecycle rules to periodically delete objects or transition objects between storage classes.

+

This API returns the lifecycle rules of a bucket.

+
+

Restrictions

  • To obtain the lifecycle configuration of a bucket, you must be the bucket owner or have the required permission (obs:bucket:GetLifecycleConfiguration in IAM or GetLifecycleConfiguration in a bucket policy).
+
+

Method

void get_bucket_lifecycle_configuration(const obs_options *options,
+                obs_lifecycle_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

handler

+

obs_lifecycle_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_lifecycle_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

get_lifecycle_callback

+

get_lifecycle_configuration_callback *

+

Yes

+

Explanation:

+

Pointer to the callback function. The details of the bucket lifecycle rule can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+
Value range:
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 19 get_lifecycle_configuration_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_lifecycle_conf

+

obs_lifecycle_conf *

+

Yes

+

Explanation:

+

Content of the bucket lifecycle rule.

+

Restrictions:

+

None

+

blcc_number

+

unsigned int

+

Yes

+

Explanation:

+

The number specified in bucket_lifecycle_conf

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_lifecycle_conf

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

date

+

const char *

+

Yes if there is no days and no transition, noncurrent_version_days, or noncurrent_version_transition

+

Explanation:

+

Indicates the time when the object expiration rule of the latest version takes effect.

+

Restrictions:

+

The value must be compatible with the ISO 8601 format and must indicate 00:00 (UTC time).

+

Value range:

+

None

+

Default value:

+

None

+

days

+

const char *

+

Yes if there is no date and no transition, noncurrent_version_days, or noncurrent_version_transition

+

Explanation:

+

Number of days (since the object creation) after which the expiration rule will take effect.

+

Restrictions:

+

This parameter is only available for the latest object version.

+

Value range:

+

None

+

Default value:

+

None

+

id

+

const char *

+

No

+

Explanation:

+

ID of a rule.

+

Restrictions:

+

None

+

Value range:

+

The value is a string of a maximum of 255 characters.

+

Default value:

+

None

+

prefix

+

const char *

+

Yes

+

Explanation:

+

Object name prefix. It identifies the objects the rule applies to.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

status

+

const char *

+

Yes

+

Explanation:

+

Whether the rule is enabled

+

Restrictions:

+

None

+

Value range:

+
  • Enabled
  • Disabled
+

Default value:

+

None

+

noncurrent_version_days

+

const char *

+

No

+

Explanation:

+

Container for the expiration time of objects' historical versions. If versioning is enabled or suspended for a bucket, you can set this parameter to delete historical versions of objects that match the lifecycle rule.

+

Restrictions:

+

This parameter is only available for historical object versions.

+

Value range:

+

None

+

Default value:

+

None

+

transition

+

obs_lifecycle_transtion *

+

Yes if there is no date, days, noncurrent_version_transition, or noncurrent_version_days

+

Explanation:

+

Transition time and the object storage class after transition

+

Restrictions:

+

This parameter is only available for the latest object version.

+

transition_num

+

unsigned int

+

Yes if transition is specified

+

Explanation:

+

Number of array members in the transition array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

noncurrent_version_transition

+

obs_lifecycle_noncurrent_transtion*

+

Yes if there is no date, days, transition, or noncurrent_version_days

+

Explanation:

+

Transition time of historical object versions and the object storage class after transition.

+

Restrictions:

+

None

+

noncurrent_version_transition_num

+

unsigned int

+

Yes if noncurrent_version_transition is specified

+

Explanation:

+

Number of array members in the array noncurrent_version_transition.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_lifecycle_transtion

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

date

+

const char *

+

Yes if the obs_lifecycle_transtion.days element is absent

+

Explanation:

+

Indicates the time when the object expiration rule of the latest version takes effect.

+

Restrictions:

+

The value must be compatible with the ISO 8601 format and must indicate 00:00 (UTC time).

+

Value range:

+

None

+

Default value:

+

None

+

days

+

const char *

+

Yes if the obs_lifecycle_transtion.date element is absent

+

Explanation:

+

Number of days (since the object creation) after which the expiration rule will take effect.

+

Restrictions:

+

This parameter is only available for the latest object version.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

Yes

+

Explanation:

+

The storage class to which the latest object version will be changed

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 22 obs_lifecycle_noncurrent_transtion

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

noncurrent_version_days

+

const char *

+

Yes

+

Explanation:

+

Number of days an object is historical before the specified transition rule takes effect

+

Restrictions:

+

This parameter is only available for historical object versions.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

Yes

+

Explanation:

+

The storage class to which historical versions will be changed

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+
+
+
+

Code Examples: Obtaining the Lifecycle Configuration of a Bucket

This example obtains the lifecycle rules of a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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); 
+obs_status getBucketLifecycleConfigurationCallbackEx(obs_lifecycle_conf* bucketLifeCycleConf,
+    unsigned int blccNumber,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to obtain the lifecycle rules of a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    // Set the callback function.
+    obs_lifecycle_handler lifeCycleHandlerEx =
+    {
+        response_handler,
+        &getBucketLifecycleConfigurationCallbackEx
+    };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    get_bucket_lifecycle_configuration(&options, &lifeCycleHandlerEx, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("get_lifecycle_config success.\n");
+    }
+    else
+    {
+        printf("get_lifecycle_config failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+obs_status getBucketLifecycleConfigurationCallbackEx(obs_lifecycle_conf* bucketLifeCycleConf,
+    unsigned int blccNumber,
+    void *callback_data)
+{
+    unsigned int i = 0;
+#define print_nonull(name, field)                                 \
+    do {                                                           \
+        if (field && field[0]) {                                  \
+            printf("%s: %s\n", name, field);          \
+        }                                                          \
+    } while (0)
+    for (i = 0; i < blccNumber; i++)
+    {
+        printf("-----------------------------------------------\n");
+        print_nonull("id", bucketLifeCycleConf[i].id);
+        print_nonull("prefix", bucketLifeCycleConf[i].prefix);
+        print_nonull("status", bucketLifeCycleConf[i].status);
+        print_nonull("days", bucketLifeCycleConf[i].days);
+        print_nonull("date", bucketLifeCycleConf[i].date);
+    }
+    printf("-----------------------------------------------\n");
+    return OBS_STATUS_OK;
+}
+
+
+
+
+
+
+
+
Parent topic: Lifecycle Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_0904.html b/docs/obs_3rd_party/c_sdk/obs_20_0904.html new file mode 100644 index 000000000..8861d0d67 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_0904.html @@ -0,0 +1,1747 @@ + + +

Deleting the Lifecycle Rules of a Bucket

+

Function

You can configure lifecycle rules to periodically delete objects or transition objects between storage classes.

+

This API deletes the lifecycle rules of a bucket.

+
+

Restrictions

  • To delete the lifecycle configuration of a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutLifecycleConfiguration in IAM or PutLifecycleConfiguration in a bucket policy).
+
+

Method

void delete_bucket_lifecycle_configuration(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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, 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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Deleting the Lifecycle Configuration of a Bucket

This example deletes the lifecycle rules of a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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); 
+obs_status getBucketLifecycleConfigurationCallbackEx(obs_lifecycle_conf* bucketLifeCycleConf,
+    unsigned int blccNumber,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to delete the lifecycle rules of a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status  ret_status = OBS_STATUS_BUTT;
+    delete_bucket_lifecycle_configuration(&options, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("test_delete_lifecycle_config success.\n");
+    }
+    else
+    {
+        printf("test_delete_lifecycle_config failed(%s).\n",
+            obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Lifecycle Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1000.html b/docs/obs_3rd_party/c_sdk/obs_20_1000.html new file mode 100644 index 000000000..17b5c5f0a --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1000.html @@ -0,0 +1,15 @@ + + +

Cross-Origin Resource Sharing

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1002.html b/docs/obs_3rd_party/c_sdk/obs_20_1002.html new file mode 100644 index 000000000..f5af0f088 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1002.html @@ -0,0 +1,1988 @@ + + +

Configuring CORS for a Bucket

+

Function

Cross-origin resource sharing (CORS) is a mechanism defined by the World Wide Web Consortium (W3C) that allows a web application program in one domain to access resources located in another one. For normal web page requests, website scripts and contents in one domain cannot interact with those in another because of Same Origin Policies (SOPs). OBS supports CORS rules that allow the resources in OBS to be requested by other domains.

+

This API configures CORS for a bucket.

+
+

Restrictions

  • To configure CORS for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutBucketCORS in IAM or PutBucketCORS in a bucket policy).
+
+

Method

void set_bucket_cors_configuration(const obs_options *options, obs_bucket_cors_conf *obs_cors_conf_info, 
+            unsigned int conf_num, 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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

obs_cors_conf_info

+

obs_bucket_cors_conf *

+

Yes

+

Explanation:

+

CORS rule content.

+

Restrictions:

+

None

+

conf_num

+

unsigned int

+

Yes

+

Explanation:

+

Number of array members in the array obs_cors_conf_info.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 4 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 obs_bucket_cors_conf

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

id

+

const char *

+

No

+

Explanation:

+

The ID of a CORS rule.

+

Restrictions:

+

None

+

Value range:

+

A string of 1 to 255 characters.

+

Default value:

+

None

+

allowed_method

+

const char **

+

Yes

+

Explanation:

+

The allowed HTTP methods (types of operations on buckets and objects) for a cross-origin request.

+

Restrictions:

+

None

+

Value range:

+

The following HTTP methods are supported:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Default value:

+

None

+

allowed_method_number

+

unsigned int

+

No

+

Explanation:

+

Number of the allowed_method elements.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allowed_origin

+

const char **

+

No

+

Explanation:

+

The origin that is allowed to access the bucket.

+

Restrictions:

+

Only English domain names are supported. Regular expressions are used to match. Each rule allows at most one asterisk (*). For example, https://*.vbs.example.com.

+

Value range:

+

The value must comply with the CORS protocol and contain 0 to 20480 characters.

+

Default value:

+

None

+

allowed_origin_number

+

unsigned int

+

No

+

Explanation:

+

Number of the allowed_origin elements.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allowed_header

+

const char **

+

No

+

Explanation:

+

The allowed headers for Access-Control-Request-Headers in a CORS configuration request. If a CORS request contains Access-Control-Request-Headers, this request is considered valid only when it matches the configuration of allowed_header. The matching is based on regular expressions.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value must comply with the CORS protocol and contain 0 to 20480 characters.

+

Default value:

+

None

+

allowed_header_number

+

unsigned int

+

No

+

Explanation:

+

Number of the allowed_header elements.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

max_age_seconds

+

const char *

+

No

+

Explanation:

+

How long the response can be cached on a client.

+

Restrictions:

+

Each CORS rule can contain at most one max_age_seconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

expose_header

+

const char **

+

No

+

Explanation:

+

It specifies additional headers a CORS rule allows in a response, which can be used to provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

expose_header_number

+

unsigned int

+

No

+

Explanation:

+

Number of the expose_header elements.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Configuring CORS for a Bucket

This example configures CORS for a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to set CORS rules for a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    char *id_1 = "1";
+    // Specify the browser's cache time for the returned results of OPTIONS requests for specific resources, in seconds.
+    char *max_age_seconds = "100";
+    // Specify the allowed CORS request methods (GET/PUT/DELETE/POST/HEAD).
+    const char* allowedMethod_1[5] = { "GET","PUT","HEAD","POST","DELETE" };
+    // Specify the allowed origins of cross-origin requests.
+    const char* allowedOrigin_1[2] = { "obs.example.com", "www.example.com" };
+    // Specify the headers that can be accessed by users from the application.
+    const char* allowedHeader_1[2] = { "header-1", "header-2" };
+    // Additional headers in the response
+    const char* exposeHeader_1[2] = { "hello", "world" };
+    obs_bucket_cors_conf bucketCorsConf;
+    memset(&bucketCorsConf, 0, sizeof(obs_bucket_cors_conf));
+    bucketCorsConf.id = id_1;
+    bucketCorsConf.max_age_seconds = max_age_seconds;
+    bucketCorsConf.allowed_method = allowedMethod_1;
+    bucketCorsConf.allowed_method_number = 5;
+    bucketCorsConf.allowed_origin = allowedOrigin_1;
+    bucketCorsConf.allowed_origin_number = 2;
+    bucketCorsConf.allowed_header = allowedHeader_1;
+    bucketCorsConf.allowed_header_number = 2;
+    bucketCorsConf.expose_header = exposeHeader_1;
+    bucketCorsConf.expose_header_number = 2;
+    set_bucket_cors_configuration(&options, &bucketCorsConf, 1, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("set_bucket_cors success.\n");
+    }
+    else {
+        printf("set_bucket_cors failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+

allowed_origin, allowed_method, and allowed_header can contain at most one wildcard (*). Wildcard characters (*) indicate that all origins, operations, or headers are allowed.

+
+
+
+
+
+
Parent topic: Cross-Origin Resource Sharing
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1003.html b/docs/obs_3rd_party/c_sdk/obs_20_1003.html new file mode 100644 index 000000000..86616e619 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1003.html @@ -0,0 +1,2087 @@ + + +

Obtaining the CORS Configuration of a Bucket

+

Function

Cross-origin resource sharing (CORS) is a mechanism defined by the World Wide Web Consortium (W3C) that allows a web application program in one domain to access resources located in another one. For normal web page requests, website scripts and contents in one domain cannot interact with those in another because of Same Origin Policies (SOPs). OBS supports CORS, allowing the resources in OBS to be requested across origins.

+

This API returns the CORS configuration of a bucket.

+
+

Restrictions

  • To obtain the CORS configuration of a bucket, you must be the bucket owner or have the required permission (obs:bucket:GetBucketCORS in IAM or GetBucketCORS in a bucket policy).
+
+

Method

void get_bucket_cors_configuration(const obs_options *options, obs_cors_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

handler

+

obs_cors_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_cors_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

get_cors_callback

+

get_cors_configuration_callback *

+

Yes

+

Explanation:

+

The callback function pointer tag. The CORS rule content in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 19 get_cors_configuration_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_cors_conf

+

obs_bucket_cors_conf *

+

Yes

+

Explanation:

+

CORS rule content.

+

Restrictions:

+

None

+

bcc_number

+

unsigned int

+

Yes

+

Explanation:

+

The number specified in bucket_cors_conf

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_bucket_cors_conf

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

id

+

const char *

+

No

+

Explanation:

+

The ID of a CORS rule.

+

Restrictions:

+

None

+

Value range:

+

A string of 1 to 255 characters.

+

Default value:

+

None

+

allowed_method

+

const char **

+

Yes

+

Explanation:

+

The allowed HTTP methods (types of operations on buckets and objects) for a cross-origin request.

+

Restrictions:

+

None

+

Value range:

+

The following HTTP methods are supported:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Default value:

+

None

+

allowed_method_number

+

unsigned int

+

No

+

Explanation:

+

Number of the allowed_method elements.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allowed_origin

+

const char **

+

No

+

Explanation:

+

The origin that is allowed to access the bucket.

+

Restrictions:

+

Only English domain names are supported. Regular expressions are used to match. Each rule allows at most one asterisk (*). For example, https://*.vbs.example.com.

+

Value range:

+

The value must comply with the CORS protocol and contain 0 to 20480 characters.

+

Default value:

+

None

+

allowed_origin_number

+

unsigned int

+

No

+

Explanation:

+

Number of the allowed_origin elements.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allowed_header

+

const char **

+

No

+

Explanation:

+

The allowed headers for Access-Control-Request-Headers in a CORS configuration request. If a CORS request contains Access-Control-Request-Headers, this request is considered valid only when it matches the configuration of allowed_header. The matching is based on regular expressions.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value must comply with the CORS protocol and contain 0 to 20480 characters.

+

Default value:

+

None

+

allowed_header_number

+

unsigned int

+

No

+

Explanation:

+

Number of the allowed_header elements.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

max_age_seconds

+

const char *

+

No

+

Explanation:

+

How long the response can be cached on a client.

+

Restrictions:

+

Each CORS rule can contain at most one max_age_seconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

expose_header

+

const char **

+

No

+

Explanation:

+

It specifies additional headers a CORS rule allows in a response, which can be used to provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

expose_header_number

+

unsigned int

+

No

+

Explanation:

+

Number of the expose_header elements.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples: Obtaining the CORS Configuration of a Bucket

This example obtains the CORS rules of a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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); 
+obs_status get_cors_info_callback(obs_bucket_cors_conf* bucket_cors_conf,
+    unsigned int bcc_number,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to obtain CORS rules of a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Set the callback function.
+    obs_cors_handler cors_handler_info =
+    {
+        response_handler,
+        &get_cors_info_callback
+    };
+    get_bucket_cors_configuration(&options, &cors_handler_info, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("get_cors_config success.\n");
+    }
+    else {
+        printf("get_cors_config failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+obs_status get_cors_info_callback(obs_bucket_cors_conf* bucket_cors_conf,
+    unsigned int bcc_number,
+    void *callback_data)
+{
+    unsigned int i = 0;
+    for (i = 0; i < bcc_number; ++i)
+    {
+        printf("------------------------------------------------------\n");
+        printf("id = %s\nmaxAgeSeconds = %s\n", bucket_cors_conf[i].id, bucket_cors_conf[i].max_age_seconds);
+        unsigned int j;
+        for (j = 0; j < bucket_cors_conf[i].allowed_method_number; j++)
+        {
+            printf("allowedMethodes = %s\n", bucket_cors_conf[i].allowed_method[j]);
+        }
+        for (j = 0; j < bucket_cors_conf[i].allowed_origin_number; j++)
+        {
+            printf("allowedOrigines = %s\n", bucket_cors_conf[i].allowed_origin[j]);
+        }
+        for (j = 0; j < bucket_cors_conf[i].allowed_header_number; j++)
+        {
+            printf("allowedHeaderes = %s\n", bucket_cors_conf[i].allowed_header[j]);
+        }
+        for (j = 0; j < bucket_cors_conf[i].expose_header_number; j++)
+        {
+            printf("exposeHeaderes = %s\n", bucket_cors_conf[i].expose_header[j]);
+        }
+    }
+    printf("------------------------------------------------------\n");
+    return OBS_STATUS_OK;
+}
+
+
+
+
+
+
+
+
Parent topic: Cross-Origin Resource Sharing
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1004.html b/docs/obs_3rd_party/c_sdk/obs_20_1004.html new file mode 100644 index 000000000..1608aafd6 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1004.html @@ -0,0 +1,1745 @@ + + +

Deleting the CORS Configuration of a Bucket

+

Function

Cross-origin resource sharing (CORS) is a mechanism defined by the World Wide Web Consortium (W3C) that allows a web application program in one domain to access resources located in another one. For normal web page requests, website scripts and contents in one domain cannot interact with those in another because of Same Origin Policies (SOPs). OBS supports CORS rules that allow the resources in OBS to be requested by other domains.

+

This API deletes the CORS rules of a bucket.

+
+

Restrictions

  • To delete the CORS configuration of a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutBucketCORS in IAM or PutBucketCORS in a bucket policy).
+
+

Method

void delete_bucket_cors_configuration(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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, 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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+
Value range:
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Deleting the CORS Configuration of a Bucket

This example deletes the CORS rules of a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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); 
+obs_status get_cors_info_callback(obs_bucket_cors_conf* bucket_cors_conf,
+    unsigned int bcc_number,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to delete the CORS rules of a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    delete_bucket_cors_configuration(&options, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("delete_cors_config success.\n");
+    }
+    else
+    {
+        printf("delete_cors_config failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Cross-Origin Resource Sharing
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1100.html b/docs/obs_3rd_party/c_sdk/obs_20_1100.html new file mode 100644 index 000000000..0c9b555e4 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1100.html @@ -0,0 +1,13 @@ + + +

Logging

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1102.html b/docs/obs_3rd_party/c_sdk/obs_20_1102.html new file mode 100644 index 000000000..b9a023bdb --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1102.html @@ -0,0 +1,2590 @@ + + +

Configuring Logging for a Bucket

+

Function

This API enables logging for a bucket (source) and configures another bucket (target) to store the log files. When a bucket is created, logging is not enabled by default. You can call this API to enable logging for the bucket. With logging enabled, a log message is generated for each operation on the bucket. Multiple log messages are packed into a file. The target bucket for storing log files must be specified when logging is enabled. It can be the bucket logging is enabled for, or any other bucket you have access to. If you specify another bucket for storing logs, the bucket must be in the same region as the logged bucket. You can also specify access permissions and name prefixes for log files.

+
+

Restrictions

  • OBS creates log files and uploads them to the bucket. Before enabling logging for a bucket, you need to create an IAM agency to delegate OBS to upload log files to the specified bucket.
  • To configure logging for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutBucketLogging in IAM or PutBucketLogging in a bucket policy).
+
+

Method

void set_bucket_logging_configuration_obs(const obs_options *options, char *target_bucket, 
+        char *target_prefix, char *agency, obs_acl_group *acl_group, 
+        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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

target_bucket

+

char *

+

Yes

+

Explanation:

+

When enabling the logging function, the owner of the bucket being logged can specify a target bucket to store the generated log files.

+

Log files generated for multiple buckets can be stored in the same target bucket. If you do so, you need to specify different target_prefix to classify logs for different buckets.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

target_prefix

+

char *

+

Yes

+

Explanation:

+

You can specify a prefix using this element so that log files are named with this prefix.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

agency

+

char *

+

Yes only when you enable the logging function

+

Explanation:

+

Name of the agency created by the owner of the logging bucket for uploading log files by OBS.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

acl_group

+

obs_acl_group *

+

No

+

Explanation:

+

Structure of the permission information group

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 4 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_acl_group

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

acl_grant_count

+

int

+

No

+

Explanation:

+

Number of elements in the acl_grants array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

acl_grants

+

obs_acl_grant *

+

No

+

Explanation:

+

Permission information structure.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_acl_grant

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

grantee_type

+

obs_grantee_type

+

Yes

+

Explanation:

+

Description of the authorized user type

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_grantee_type.

+

grantee.canonical_user.id

+

char[]

+

No

+

Explanation:

+

User ID of the authorized user.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the ID of an authorized user, see How Do I Get My Account ID and User ID?.

+

Default value:

+

None

+

permission

+

obs_permission

+

Yes

+

Explanation:

+

Bucket ACL

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_permission.

+

bucket_delivered

+

obs_bucket_delivered

+

Yes

+

Explanation:

+

Whether the bucket ACL is applied to the objects in the bucket

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_bucket_delivered.

+

Default value:

+

BUCKET_DELIVERED_FALSE (The ACL of the bucket does not apply to its objects.)

+
+
+ +
+ + + + + + + + + + +
Table 13 obs_grantee_type

Value

+

Description

+

OBS_GRANTEE_TYPE_CANONICAL_USER

+

An OBS user. Bucket or object permissions can be granted to any user who has an OBS account.

+

Authorized users can use the AK and SK to access OBS.

+

OBS_GRANTEE_TYPE_ALL_USERS

+

All users can access buckets or objects, including anonymous users.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
Table 14 obs_permission

Value

+

Description

+

OBS_PERMISSION_READ

+

Read permission. A grantee with this permission for a bucket can obtain the list of objects in and metadata of the bucket.

+

A grantee with this permission for an object can obtain the object content and metadata.

+

OBS_PERMISSION_WRITE

+

Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object in the bucket.

+

This permission is not available for objects.

+

OBS_PERMISSION_READ_ACP

+

ACP read permission. A grantee with this permission can obtain the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

OBS_PERMISSION_WRITE_ACP

+

ACP write permission. A grantee with this permission can update the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object.

+

OBS_PERMISSION_FULL_CONTROL

+

Full control permission. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.

+

A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object.

+
+
+ +
+ + + + + + + + + + +
Table 15 obs_bucket_delivered

Value

+

Description

+

BUCKET_DELIVERED_FALSE

+

A bucket ACL is not applied to the objects in the bucket.

+

BUCKET_DELIVERED_TRUE

+

A bucket ACL is applied to the objects in the bucket.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 21 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Enabling Bucket Logging

This example enables bucket logging.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to enable bucket logging:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Name of the IAM agency for OBS created by the target bucket owner
+    char *agency = "storageSDK";
+    //Specify the name of the target bucket for storing logs.
+    char * bucket_name_target = "example-dest-bucket-name";
+    // Configure logging for the bucket.
+    set_bucket_logging_configuration_obs(&options, bucket_name_target, "prefix-log", agency,
+        NULL, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("set bucket (%s) logging successfully. \n", bucketName);
+    }
+    else
+    {
+        printf("set bucket logging failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+

Code Examples: Granting Permissions on Log Objects

This example sets permissions for log objects.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to set permissions for log objects:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    int aclGrantCount = 2;
+    obs_acl_grant acl_grants[2] = { 0 };
+    // Grant full permissions on log files to the authorized users.
+    acl_grants[0].grantee_type = OBS_GRANTEE_TYPE_CANONICAL_USER;
+    strcpy(acl_grants[0].grantee.canonical_user.id, "userid1");
+    strcpy(acl_grants[0].grantee.canonical_user.display_name, "dis1");
+    acl_grants[0].permission = OBS_PERMISSION_READ;
+    // Grant the read permission on log objects to all users.
+    acl_grants[1].grantee_type = OBS_GRANTEE_TYPE_ALL_OBS_USERS;
+    acl_grants[1].permission = OBS_PERMISSION_READ;
+    obs_acl_group acl_group;
+    acl_group.acl_grants = acl_grants;
+    acl_group.acl_grant_count = aclGrantCount;
+    // Name of the IAM agency for OBS created by the target bucket owner
+    char *agency = "storageSDK";
+    //Specify the name of the target bucket for storing logs.
+    char * bucket_name_target = "example-dest-bucket-name";
+    // Configure logging for the bucket.
+    // Set the prefix of the log files, that is, the name of the folder where the log files are stored. If the prefix is not set, the log files are stored in the root directory of the target bucket by default.
+    set_bucket_logging_configuration_obs(&options, bucket_name_target, "prefix-log", agency,
+        &acl_group, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("set bucket(%s) logging successfully. \n", bucketName);
+    }
+    else
+    {
+        printf("set bucket logging failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+

Code Examples: Disabling Bucket Logging

This example disables bucket logging.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to disable bucket logging:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    char * agency = NULL;
+    char * bucket_name_target = NULL;
+    // Configure logging for the bucket.
+    set_bucket_logging_configuration_obs(&options, bucket_name_target, NULL, agency,
+        NULL, &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("close bucket(%s) logging successfully. \n", bucketName);
+    }
+    else
+    {
+        printf("close bucket logging failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Logging
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1103.html b/docs/obs_3rd_party/c_sdk/obs_20_1103.html new file mode 100644 index 000000000..bbf501b51 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1103.html @@ -0,0 +1,2247 @@ + + +

Obtaining the Logging Configuration of a Bucket

+

Function

This API returns the logging configuration of a bucket.

+
+

Restrictions

  • To obtain the logging configuration of a bucket, you must be the bucket owner or have the required permission (obs:bucket:GetBucketLogging in IAM or GetBucketLogging in a bucket policy).
+
+

Method

void get_bucket_logging_configuration(const obs_options *options, obs_response_handler *handler, 
+        bucket_logging_message *logging_message_data, void *callback_data);
+
+

Request Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1 List of request parameters

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

options

+

const obs_options*

+

Yes

+

Explanation:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

logging_message_data

+

bucket_logging_message *

+

Yes

+

Explanation:

+

Logging configuration of the current bucket.

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 4 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 bucket_logging_message

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

target_bucket

+

char *

+

No

+

Explanation:

+

When enabling the logging function, the owner of the bucket being logged can specify a target bucket to store the generated log files.

+

Log files generated for multiple buckets can be stored in the same target bucket. If you do so, you need to specify different target_prefix to classify logs for different buckets.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

target_bucket_size

+

int

+

No

+

Explanation:

+

Number of elements in the target_bucket array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

target_prefix

+

char *

+

No

+

Explanation:

+

You can specify a prefix using this element so that log files are named with this prefix.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

target_prefix_size

+

int

+

No

+

Explanation:

+

Number of elements in the target_prefix array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

acl_grants

+

obs_acl_grant *

+

No

+

Explanation:

+

Permission information structure.

+

Restrictions:

+

None

+

acl_grant_count

+

int

+

No

+

Explanation:

+

Number of elements in the acl_grants array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

agency

+

char *

+

No

+

Explanation:

+

Name of the agency created by the owner of the logging bucket for uploading log files by OBS.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

agency_size

+

int

+

No

+

Explanation:

+

Number of elements in the agency array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_acl_grant

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

grantee_type

+

obs_grantee_type

+

Yes

+

Explanation:

+

Description of the authorized user type

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_grantee_type.

+

grantee.canonical_user.id

+

char[]

+

No

+

Explanation:

+

User ID of the authorized user.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the ID of an authorized user, see How Do I Get My Account ID and User ID?.

+

Default value:

+

None

+

permission

+

obs_permission

+

Yes

+

Explanation:

+

Bucket ACL

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_permission.

+

bucket_delivered

+

obs_bucket_delivered

+

Yes

+

Explanation:

+

Whether the bucket ACL is applied to the objects in the bucket.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_bucket_delivered.

+

Default value:

+

BUCKET_DELIVERED_FALSE (The ACL of the bucket does not apply to its objects.)

+
+
+ +
+ + + + + + + + + + +
Table 13 obs_grantee_type

Value

+

Description

+

OBS_GRANTEE_TYPE_CANONICAL_USER

+

An OBS user. Bucket or object permissions can be granted to any user who has an OBS account.

+

Authorized users can use the AK and SK to access OBS.

+

OBS_GRANTEE_TYPE_ALL_USERS

+

All users can access buckets or objects, including anonymous users.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
Table 14 obs_permission

Value

+

Description

+

OBS_PERMISSION_READ

+

Read permission. A grantee with this permission for a bucket can obtain the list of objects in and metadata of the bucket.

+

A grantee with this permission for an object can obtain the object content and metadata.

+

OBS_PERMISSION_WRITE

+

Write permission. A grantee with this permission for a bucket can upload, overwrite, and delete any object in the bucket.

+

This permission is not available for objects.

+

OBS_PERMISSION_READ_ACP

+

ACP read permission. A grantee with this permission can obtain the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

OBS_PERMISSION_WRITE_ACP

+

ACP write permission. A grantee with this permission can update the ACL of a bucket or object.

+

A bucket or object owner has this permission for their bucket or object ACL by default.

+

This permission allows the grantee to change the access control policies, meaning the grantee has full control over a bucket or object.

+

OBS_PERMISSION_FULL_CONTROL

+

Full control permission. A grantee with this permission for a bucket has READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.

+

A grantee with this permission for an object has READ, READ_ACP, and WRITE_ACP permissions for the object.

+
+
+ +
+ + + + + + + + + + +
Table 15 obs_bucket_delivered

Value

+

Description

+

BUCKET_DELIVERED_FALSE

+

A bucket ACL is not applied to the objects in the bucket.

+

BUCKET_DELIVERED_TRUE

+

A bucket ACL is applied to the objects in the bucket.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 21 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Obtaining the Logging Configuration of a Bucket

This example obtains the bucket logging configuration.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+void init_bucket_get_logging_message(bucket_logging_message *logging_message); 
+void print_grant_info(int acl_grant_count, obs_acl_grant *acl_grants);
+void destroy_logging_message(bucket_logging_message *logging_message);
+int main()
+{
+    // The following code shows how to view the bucket logging configuration:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Initialize the logging configuration structure.
+    bucket_logging_message logging_message;
+    init_bucket_get_logging_message(&logging_message);
+    // Obtain the bucket logging configuration.
+    get_bucket_logging_configuration(&options, &response_handler, &logging_message, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        if (logging_message.target_bucket)
+        {
+            printf("Target_Bucket: %s\n", logging_message.target_bucket);
+            if (logging_message.target_prefix)
+            {
+                printf("Target_Prefix: %s\n", logging_message.target_prefix);
+            }
+            if (logging_message.agency && logging_message.agency[0] != '\0')
+            {
+                printf("Agency: %s\n", logging_message.agency);
+            }
+            // Print the ACL configuration.
+            print_grant_info(*logging_message.acl_grant_count, logging_message.acl_grants);
+        }
+        else
+        {
+            printf("Service logging is not enabled for this bucket.\n");
+        }
+    }
+    else
+    {
+        printf("Get bucket logging failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Destroy the logging configuration structure.
+    destroy_logging_message(&logging_message);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("Error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("Error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    } else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                   error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void init_bucket_get_logging_message(bucket_logging_message *logging_message)
+{
+    memset(logging_message, 0, sizeof(bucket_logging_message));
+    logging_message->target_bucket = (char *)malloc(sizeof(char)*OBS_MAX_HOSTNAME_SIZE);
+    memset(logging_message->target_bucket, 0, OBS_MAX_HOSTNAME_SIZE);
+    logging_message->target_bucket_size = OBS_MAX_HOSTNAME_SIZE;
+    logging_message->target_prefix = (char *)malloc(sizeof(char)*OBS_MAX_KEY_SIZE);
+    memset(logging_message->target_prefix, 0, OBS_MAX_KEY_SIZE);
+    logging_message->target_prefix_size = OBS_MAX_KEY_SIZE;
+    
+    logging_message->agency = (char *)malloc(sizeof(char)*OBS_MAX_KEY_SIZE);
+    memset(logging_message->agency, 0, OBS_MAX_KEY_SIZE);
+    logging_message->agency_size = OBS_MAX_KEY_SIZE;
+    logging_message->acl_grants = (obs_acl_grant*)malloc(sizeof(obs_acl_grant)*OBS_MAX_ACL_GRANT_COUNT);
+    memset(logging_message->acl_grants, 0, sizeof(obs_acl_grant)*OBS_MAX_ACL_GRANT_COUNT);
+    logging_message->acl_grant_count = (int *)malloc(sizeof(int));
+    *(logging_message->acl_grant_count) = 0;
+}
+void destroy_logging_message(bucket_logging_message *logging_message)
+{
+    free(logging_message->target_bucket);
+    free(logging_message->target_prefix);
+    free(logging_message->acl_grants);
+    free(logging_message->agency);
+    free(logging_message->acl_grant_count);
+}
+void print_grant_info(int acl_grant_count, obs_acl_grant *acl_grants)
+{
+    int i;
+    for (i = 0; i < acl_grant_count; i++)
+    {
+        obs_acl_grant *grant = acl_grants + i;
+        const char *type;
+        char composedId[OBS_MAX_GRANTEE_USER_ID_SIZE +
+            OBS_MAX_GRANTEE_DISPLAY_NAME_SIZE + 16] = { 0 };
+        const char *id;
+        switch (grant->grantee_type) {
+        case OBS_GRANTEE_TYPE_CANONICAL_USER:
+            type = "UserID";
+            snprintf(composedId, sizeof(composedId), 
+                "%s (%s)", grant->grantee.canonical_user.id,
+                grant->grantee.canonical_user.display_name);
+            id = composedId;
+            break;
+        case OBS_GRANTEE_TYPE_ALL_OBS_USERS:
+            type = "Group";
+            id = "Authenticated Users";
+            break;
+        default:
+            type = "Group";
+            id = "All Users";
+            break;
+        }
+        const char *perm;
+        switch (grant->permission) {
+        case OBS_PERMISSION_READ:
+            perm = "READ";
+            break;
+        case OBS_PERMISSION_WRITE:
+            perm = "WRITE";
+            break;
+        case OBS_PERMISSION_READ_ACP:
+            perm = "READ_ACP";
+            break;
+        case OBS_PERMISSION_WRITE_ACP:
+            perm = "WRITE_ACP";
+            break;
+        default:
+            perm = "FULL_CONTROL";
+            break;
+        }
+        printf("%-6s  %-90s  %-12s\n", type, id, perm);
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Logging
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1200.html b/docs/obs_3rd_party/c_sdk/obs_20_1200.html new file mode 100644 index 000000000..2169f8d5d --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1200.html @@ -0,0 +1,17 @@ + + +

Static Website Hosting

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1202.html b/docs/obs_3rd_party/c_sdk/obs_20_1202.html new file mode 100644 index 000000000..8f851c568 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1202.html @@ -0,0 +1,383 @@ + + +

Hosting Website Files in a Bucket

+

You can perform the following to implement website file hosting:

+
  1. Upload a website file to your bucket in OBS as an object and set the MIME type for the object.
  2. Set the object ACL to public read.
  3. Access the object using a browser.
+

Code Examples: Website File Hosting

This example implements website file hosting.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data);
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct put_file_object_callback_data
+{
+    FILE *infile;
+    uint64_t content_length;
+    obs_status ret_status;
+} put_file_object_callback_data;
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data);
+int main()
+{
+    // The following code shows how to implement website file hosting:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Initialize the properties of the object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Name of the object to be uploaded
+    char *key = "example_put_file_html_test.html";
+    // Uploaded file
+    char file_name[256] = "./example_local_file_test.html";
+    // Set the MIME type.
+    put_properties.content_type = "text/html";
+    // Set the object ACL to public read.
+    put_properties.canned_acl = OBS_CANNED_ACL_PUBLIC_READ;
+    put_properties.content_disposition_filename = "";
+    uint64_t content_length = 0;
+    // Initialize the structure for storing the uploaded data.
+    put_file_object_callback_data data;
+    memset(&data, 0, sizeof(put_file_object_callback_data));
+    // Open the file and obtain the file length.
+    content_length = open_file_and_get_length(file_name, &data);
+    // Set the callback function.
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_file_complete_callback },
+        &put_file_data_callback
+    };
+    put_object(&options, key, content_length, &put_properties, 0, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from file successfully. \n");
+    }
+    else
+    {
+        printf("put object failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    if (data.infile != NULL) {
+        fclose(data.infile);
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data)
+{
+    put_file_object_callback_data *data =
+        (put_file_object_callback_data *)callback_data;
+    int ret = 0;
+    if (data->content_length) {
+        int toRead = ((data->content_length > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->content_length);
+        ret = fread(buffer, 1, toRead, data->infile);
+    }
+    uint64_t originalContentLength = data->content_length;
+    data->content_length -= ret;
+    if (data->content_length) {
+        printf("%llu bytes remaining ", (unsigned long long)data->content_length);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->content_length) * 100) / originalContentLength));
+    }
+    return ret;
+}
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    put_file_object_callback_data *data = (put_file_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data)
+{
+    uint64_t content_length = 0;
+    const char *body = 0;
+    if (!content_length)
+    {
+        struct stat statbuf;
+        if (stat(localfile, &statbuf) == -1)
+        {
+            fprintf(stderr, "\nERROR: Failed to stat file %s: ",
+                localfile);
+            return 0;
+        }
+        content_length = statbuf.st_size;
+    }
+    if (!(data->infile = fopen(localfile, "rb")))
+    {
+        fprintf(stderr, "\nERROR: Failed to open input file %s: ",
+            localfile);
+        return 0;
+    }
+    data->content_length = content_length;
+    return content_length;
+}
+
+
+
+
+
+
+
+
Parent topic: Static Website Hosting
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1203.html b/docs/obs_3rd_party/c_sdk/obs_20_1203.html new file mode 100644 index 000000000..64c684361 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1203.html @@ -0,0 +1,2430 @@ + + +

Configuring Static Website Hosting for a Bucket

+

Function

You can host static website resources such as HTML web pages, flash files, or audio and video files in an OBS bucket, so that you can provide these hosted resources using the bucket's website endpoint to end users. Typical use cases include:

+
  • Redirecting all requests to another website
  • Redirecting specific requests
+

This API configures static website hosting for a bucket.

+
+

Restrictions

  • Periods (.) should be avoided in the target bucket name, or there may be certificate verification failures on the client when using HTTPS for access.
  • The request body of the website configuration cannot exceed 10 KB.
  • To configure static website hosting for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutBucketWebsite in IAM or PutBucketWebsite in a bucket policy).
+
+

Method

void set_bucket_website_configuration(const obs_options *options, 
+        obs_set_bucket_redirect_all_conf *set_bucket_redirect_all,
+        obs_set_bucket_website_conf *set_bucket_website_conf,
+        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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

set_bucket_redirect_all

+

obs_set_bucket_redirect_all_conf *

+

Yes

+

Explanation:

+

Indicates the redirection configuration.

+

Restrictions:

+

None

+

set_bucket_redirect_all->host_name

+

const char *

+

Yes

+

Explanation:

+

Indicates the name of the host where requests will be redirected.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

set_bucket_redirect_all->protocol

+

const char *

+

No

+

Explanation:

+

Indicates the protocol used for redirecting requests.

+

Restrictions:

+

None

+

Value range:

+
  • http
  • https
+

Default value:

+

http

+

set_bucket_website_conf

+

obs_set_bucket_website_conf *

+

Yes

+

Explanation:

+

The configuration of the website element in the redirection rules.

+

Restrictions:

+

None

+

set_bucket_website_conf->suffix

+

const char *

+

Yes

+

Explanation:

+

The suffix that is appended to the requested directory. For example, if the suffix is index.html and samplebucket/images/ is requested, the data that is returned will be the content under the object name images/index.html in the samplebucket bucket.

+

Restrictions:

+

The suffix cannot be empty or contain slashes (/).

+

Value range:

+

None

+

Default value:

+

None

+

set_bucket_website_conf->key

+

const char *

+

No

+

Explanation:

+

Indicates the object name that is used when a 4XX error occurs. This element identifies the page that is returned when an error occurs.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

set_bucket_website_conf->routingrule_info

+

bucket_website_routingrule *

+

No

+

Explanation:

+

Description of the redirection rule.

+

Restrictions:

+

None

+

set_bucket_website_conf->routingrule_count

+

int

+

No

+

Explanation:

+

Total size of set_bucket_website_conf.routingrule_info

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 4 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_set_bucket_redirect_all_conf

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

const char *

+

Yes

+

Explanation:

+

Indicates the name of the host where requests will be redirected.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

protocol

+

const char *

+

Yes

+

Explanation:

+

Indicates the protocol used for redirecting requests.

+

Restrictions:

+

None

+

Value range:

+
  • http
  • https
+

Default value:

+

http

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12 obs_set_bucket_website_conf

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

suffix

+

const char *

+

Yes

+

Explanation:

+

The suffix element is appended to the requested directory.

+

Restrictions:

+

The suffix cannot be empty or contain slashes (/).

+

Value range:

+

None

+

Default value:

+

None

+

key

+

constchar*

+

No

+

Explanation:

+

Indicates the object name that is used when a 4XX error occurs. This element identifies the page that is returned when an error occurs.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

routingrule_info

+

bucket_website_routingrule *

+

No

+

Explanation:

+

Elements of the redirection rule.

+

Restrictions:

+

None

+

routingrule_count

+

int

+

Yes

+

Explanation:

+

Number of routingrule_info records.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 13 bucket_website_routingrule

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key_prefix_equals

+

const char *

+

Yes

+

Explanation:

+

Indicates the object name prefix which the redirection applies to.

+

For example, to redirect the requests for the object ExamplePage.html, set key_prefix_equals to ExamplePage.html.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

http_errorcode_returned_equals

+

const char *

+

Yes

+

Explanation:

+

The HTTP error code for redirection to take effect. If an error code returned is the same as the value specified for this parameter, the redirection rule takes effect.

+

Examples:

+

If you want to redirect requests to NotFound.html when an HTTP error code 404 is returned, set http_errorcode_returned_equals to 404 and replace_key_with to NotFound.html.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

protocol

+

const char *

+

Yes

+

Explanation:

+

Indicates the protocol (http or https) used for redirecting requests.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

host_name

+

const char *

+

Yes

+

Explanation:

+

Indicates the name of the host where requests will be redirected.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

replace_key_prefix_with

+

const char *

+

Yes

+

Explanation:

+

The object name prefix used in the redirection. OBS replaces the value of key_prefix_equals with the value of replace_key_prefix_with.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

replace_key_with

+

const char *

+

Yes

+

Explanation:

+

The object name prefix used in the redirection. OBS replaces the entire object name in the request with the value of replace_key_with.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

http_redirect_code

+

const char *

+

Yes

+

Explanation:

+

Indicates the HTTP status code returned for the redirection request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 15 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 19 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Configuring the Default Page, Error Page, and Redirection Rules

This example configures the default page, error page, and redirection rules.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to configure hosting for a bucket:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    obs_set_bucket_website_conf set_bucket_website_conf;
+    // Configure the default page.
+    set_bucket_website_conf.suffix = "index.html";
+    // Configure the error page.
+    set_bucket_website_conf.key = "Error.html";
+    // Define redirection rules.
+    set_bucket_website_conf.routingrule_count = 2;
+    bucket_website_routingrule temp[2];
+    memset(&temp[0], 0, sizeof(bucket_website_routingrule));
+    memset(&temp[1], 0, sizeof(bucket_website_routingrule));
+    set_bucket_website_conf.routingrule_info = temp;
+    temp[0].key_prefix_equals = "key_prefix1";
+    temp[0].replace_key_prefix_with = "replace_key_prefix1";
+    temp[0].http_errorcode_returned_equals = "404";
+    temp[0].http_redirect_code = NULL;
+    temp[0].host_name = "www.example.com";
+    temp[0].protocol = "http";
+    temp[1].key_prefix_equals = "key_prefix2";
+    temp[1].replace_key_prefix_with = "replace_key_prefix2";
+    temp[1].http_errorcode_returned_equals = "404";
+    temp[1].http_redirect_code = NULL;
+    temp[1].host_name = "www.example.com";
+    temp[1].protocol = "http";
+    // Set the redirection rules.
+    set_bucket_website_configuration(&options, NULL, &set_bucket_website_conf,
+        &response_handler, &ret_status);
+    // Check whether the request is successful.
+    if (ret_status == OBS_STATUS_OK) {
+        printf("create bucket %s successfully. \n", bucketName);
+    }
+    else {
+        printf("create bucket %s failed(%s).\n", bucketName, obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+

Code Examples: Configuring Redirection for All Requests

This example configures redirection for all requests.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to configure redirection for all requests:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Set redirection for all requests.
+    obs_set_bucket_redirect_all_conf set_bucket_redirect_all;
+    set_bucket_redirect_all.host_name = "www.example.com";
+    set_bucket_redirect_all.protocol = "https";
+    set_bucket_website_configuration(&options, &set_bucket_redirect_all, NULL,
+        &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("set bucket redirect all successfully. \n");
+    }
+    else
+    {
+        printf("set bucket redirect all failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Static Website Hosting
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1204.html b/docs/obs_3rd_party/c_sdk/obs_20_1204.html new file mode 100644 index 000000000..026c874e6 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1204.html @@ -0,0 +1,2103 @@ + + +

Obtaining the Static Website Hosting Configuration of a Bucket

+

Function

You can host static website resources such as HTML web pages, flash files, or audio and video files in an OBS bucket, so that you can provide these hosted resources using the bucket's website endpoint to end users. Typical use cases include:

+
  • Redirecting all requests to another website
  • Redirecting specific requests
+

This API returns the static website hosting configurations of the bucket.

+
+

Restrictions

  • To obtain the static website hosting configurations of a bucket, you must be the bucket owner or have the required permission (obs:bucket:GetBucketWebsite in IAM or GetBucketWebsite in a bucket policy).
+
+

Method

void get_bucket_website_configuration(const obs_options *options, 
+        obs_get_bucket_websiteconf_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

handler

+

obs_get_bucket_websiteconf_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 your custom callback_data.

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_get_bucket_websiteconf_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

get_bucket_website_conf_callback

+

obs_get_bucket_websiteconf_callback *

+

Yes

+

Explanation:

+

The pointer to the callback function, where the callback parameters can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_get_bucket_websiteconf_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

hostname

+

const char *

+

Yes

+

Explanation:

+

Indicates the name of the host where requests will be redirected.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

protocol

+

const char *

+

Yes

+

Explanation:

+

The HTTP or HTTPS protocol used in redirecting requests. The default protocol is HTTP.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

suffix

+

const char *

+

Yes

+

Explanation:

+

The suffix that is appended to the requested directory. For example, if the suffix is index.html and samplebucket/images/ is requested, the data that is returned will be the content under the object name images/index.html in the samplebucket bucket.

+

Restrictions:

+

The suffix cannot be empty or contain slashes (/).

+

Value range:

+

None

+

Default value:

+

None

+

key

+

const char *

+

Yes

+

Explanation:

+

Indicates the object name that is used when a 4XX error occurs. This element identifies the page that is returned when an error occurs.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

routingrule

+

const bucket_website_routingrule *

+

Yes

+

Explanation:

+

Description of the redirection rule.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 bucket_website_routingrule

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key_prefix_equals

+

const char *

+

Yes

+

Explanation:

+

Indicates the object name prefix which the redirection applies to.

+

For example, to redirect the requests for the object ExamplePage.html, set key_prefix_equals to ExamplePage.html.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

http_errorcode_returned_equals

+

const char *

+

Yes

+

Explanation:

+

The HTTP error code for redirection to take effect. If an error code returned is the same as the value specified for this parameter, the redirection rule takes effect.

+

Examples:

+

If you want to redirect requests to NotFound.html when an HTTP error code 404 is returned, set http_errorcode_returned_equals to 404 and replace_key_with to NotFound.html.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

protocol

+

const char *

+

Yes

+

Explanation:

+

Indicates the protocol (http or https) used for redirecting requests.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

host_name

+

const char *

+

Yes

+

Explanation:

+

Indicates the name of the host where requests will be redirected.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

replace_key_prefix_with

+

const char *

+

Yes

+

Explanation:

+

The object name prefix used in the redirection. OBS replaces the value of key_prefix_equals with the value of replace_key_prefix_with.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

replace_key_with

+

const char *

+

Yes

+

Explanation:

+

The object name prefix used in the redirection. OBS replaces the entire object name in the request with the value of replace_key_with.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

http_redirect_code

+

const char *

+

Yes

+

Explanation:

+

Indicates the HTTP status code returned for the redirection request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples: Obtaining the Website Hosting Configurations of a Bucket

This example obtains the website hosting configuration of a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+obs_status get_bucket_websiteconf_callback(const char *hostname,
+    const char *protocol,
+    const char *suffix,
+    const char *key,
+    const bucket_website_routingrule *websiteconf,
+    int webdatacount,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to view the hosting configuration:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Set the response callback function.
+    obs_get_bucket_websiteconf_handler get_bucket_websiteconf_handler =
+    {
+        response_handler,
+        &get_bucket_websiteconf_callback
+    };
+    // Obtain the hosting configuration.
+    get_bucket_website_configuration(&options, &get_bucket_websiteconf_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("get bucket website successfully.\n");
+    }
+    else
+    {
+        printf("get bucket website failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+obs_status get_bucket_websiteconf_callback(const char *hostname,
+    const char *protocol,
+    const char *suffix,
+    const char *key,
+    const bucket_website_routingrule *websiteconf,
+    int webdatacount,
+    void *callback_data)
+{
+    (void)callback_data;
+    int i = 0;
+    printf("redirectAllRequestsTo hostname : %s\n", hostname);
+    printf("redirectAllRequestsTo protocol : %s\n", protocol);
+    printf("suffix : %s\n", suffix);
+    printf("key : %s\n", key);
+    for (i = 0; i < webdatacount; i++)
+    {
+        printf("key_prefix_equals : %s\n", websiteconf[i].key_prefix_equals);
+        printf("http_errorcode_returned_equals : %s\n", websiteconf[i].http_errorcode_returned_equals);
+        printf("replace_key_prefix_with : %s\n", websiteconf[i].replace_key_prefix_with);
+        printf("replace_key_with : %s\n", websiteconf[i].replace_key_with);
+        printf("http_redirect_code : %s\n", websiteconf[i].http_redirect_code);
+        printf("hostname : %s\n", websiteconf[i].host_name);
+        printf("protocol : %s\n", websiteconf[i].protocol);
+    }
+    return OBS_STATUS_OK;
+}
+
+
+
+
+
+
+
+
Parent topic: Static Website Hosting
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1205.html b/docs/obs_3rd_party/c_sdk/obs_20_1205.html new file mode 100644 index 000000000..daca35832 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1205.html @@ -0,0 +1,1746 @@ + + +

Deleting the Static Website Hosting Configuration of a Bucket

+

Function

You can host static website resources such as HTML web pages, flash files, or audio and video files in an OBS bucket, so that you can provide these hosted resources using the bucket's website endpoint to end users. Typical use cases include:

+
  • Redirecting all requests to another website
  • Redirecting specific requests
+

This API deletes the static website hosting configurations of a bucket.

+
+

Restrictions

  • To delete the static website hosting configurations of a bucket, you must be the bucket owner or have the required permission (obs:bucket:DeleteBucketWebsite in IAM or DeleteBucketWebsite in a bucket policy).
+
+

Method

void delete_bucket_website_configuration(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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, 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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 4 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+
Value range:
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Deleting the Website Hosting Configurations of a Bucket

This example deletes the website hosting configuration of a bucket.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+int main()
+{
+    // The following code shows how to delete the hosting configuration:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Delete the hosting configuration.
+    delete_bucket_website_configuration(&options, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("delete bucket website successfully.\n");
+    }
+    else
+    {
+        printf("delete bucket website failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Static Website Hosting
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1300.html b/docs/obs_3rd_party/c_sdk/obs_20_1300.html new file mode 100644 index 000000000..904422563 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1300.html @@ -0,0 +1,15 @@ + + +

Tagging

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1302.html b/docs/obs_3rd_party/c_sdk/obs_20_1302.html new file mode 100644 index 000000000..ae9ff9db2 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1302.html @@ -0,0 +1,1795 @@ + + +

Adding Bucket Tags

+

Function

If you add tags to a bucket, SDRs generated for the requests sent to this bucket will include these tags, so you can use the tags to classify SDRs for detailed cost analysis. For example, if you have an application that uploads its running data to a bucket, you can tag the bucket with the application name. Then, you can analyze the cost of this application by using that tag.

+

This API adds tags to a bucket.

+
+

Restrictions

  • A bucket can have a maximum of 10 tags.
  • A tag key and its value can contain a maximum of 36 and 43 characters, respectively.
  • Tag keys and values cannot contain commas (,), asterisks (*), vertical bars (|), slashes (/), less-than signs (<), greater-than signs (>), equal signs (=), backslashes (\), or ASCII codes (0x00 to 0x1F).
  • To add tags to a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutBucketTagging in IAM or PutBucketTagging in a bucket policy).
+
+

Method

void set_bucket_tagging(const obs_options *options,obs_name_value * tagging_list, 
+        unsigned int number, 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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

tagging_list

+

obs_name_value *

+

Yes

+

Explanation:

+

Tag list

+

Restrictions:

+

None

+

number

+

unsigned int

+

Yes

+

Explanation:

+

Number of tags

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 4 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+
Value range:
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Adding Bucket Tags

This example sets bucket tags.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+#define TAG_LIST_LENGTH 10
+int main()
+{
+    // The following code shows how to set bucket tags using set_bucket_tagging:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Define bucket tags.
+    char tagKey[][OBS_COMMON_LEN_256] = { {"k1"},{"k2"},{"k3"},{"k4"},{"k5"},{"k6"},{"k7"},{"k8"},{"k9"},{"k10"} };
+    char tagValue[][OBS_COMMON_LEN_256] = { {"v1"},{"v2"},{"v3"},{"v4"},{"v5"},{"v6"},{"v7"},{"v8"},{"v9"},{"v10"} };
+    obs_name_value tagginglist[TAG_LIST_LENGTH] = { 0 };
+    int i = 0;
+    for (; i < TAG_LIST_LENGTH; i++)
+    {
+        tagginglist[i].name = tagKey[i];
+        tagginglist[i].value = tagValue[i];
+    }
+    // Set the bucket tags.
+    set_bucket_tagging(&options, tagginglist, TAG_LIST_LENGTH, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("set bucket tagging successfully. \n");
+    }
+    else
+    {
+        printf("set bucket tagging failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
  • A bucket can have up to 10 tags.
  • The name and value of a tag can contain Unicode characters.
+
+
+
+
+
Parent topic: Tagging
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1303.html b/docs/obs_3rd_party/c_sdk/obs_20_1303.html new file mode 100644 index 000000000..0acc18198 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1303.html @@ -0,0 +1,1931 @@ + + +

Obtaining Bucket Tags

+

Function

If you add tags to a bucket, SDRs generated for the requests sent to this bucket will include these tags, so you can use the tags to classify SDRs for detailed cost analysis. For example, if you have an application that uploads its running data to a bucket, you can tag the bucket with the application name. Then, you can analyze the cost of this application by using that tag.

+

This API returns the tags of a bucket.

+
+

Restrictions

  • To obtain the bucket tags, you must be the bucket owner or have the required permission (obs:bucket:GetBucketTagging in IAM or GetBucketTagging in a bucket policy).
+
+

Method

void get_bucket_tagging(const obs_options *options, obs_get_bucket_tagging_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

handler

+

obs_get_bucket_tagging_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 4 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+
Value range:
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_get_bucket_tagging_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

get_bucket_tagging_callback

+

obs_get_bucket_tagging_callback *

+

Yes

+

Explanation:

+

The callback function pointer tag. The content of tagging_count and tagging_list in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_get_bucket_tagging_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

tagging_count

+

int

+

Yes

+

Explanation:

+

Number of tags in the tag list.

+

Restrictions:

+

None

+

Value range:

+

[0,10]

+

Default value:

+

None

+

tagging_list

+

obs_name_value *

+

Yes

+

Explanation:

+

The tag list

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples: Obtaining Bucket Tags

This example obtains the bucket tags.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+obs_status get_bucket_tagging_callback(int tagging_count, obs_name_value *tagging_list, void *callback_data);
+typedef struct tagkv
+{
+    char key[250];
+    char value[250];
+}tagkv;
+typedef struct TaggingInfo
+{
+    int tagCount;
+    tagkv taglist[10];
+    obs_status ret_status;
+}TaggingInfo;
+int main()
+{
+    // The following code shows how to use get_bucket_tagging to view bucket tags:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    // Set the response callback function.
+    obs_get_bucket_tagging_handler get_bucket_tagging_handler =
+    {
+        response_handler,
+        &get_bucket_tagging_callback
+    };
+    // Create callback data.
+    TaggingInfo tagging_info;
+    memset(&tagging_info, 0, sizeof(TaggingInfo));
+    tagging_info.ret_status = OBS_STATUS_BUTT;
+    // Obtain bucket tags.
+    get_bucket_tagging(&options, &get_bucket_tagging_handler, &tagging_info);
+    if (OBS_STATUS_OK == tagging_info.ret_status) {
+        printf("get bucket tagging successfully.\n");
+    }
+    else
+    {
+        printf("get bucket tagging failed(%s).\n", obs_get_status_name(tagging_info.ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+void printTagInfo(TaggingInfo* infoToPrint)
+{
+    int i;
+    printf("etag number is %d\n", infoToPrint->tagCount);
+    for (i = 0; i < infoToPrint->tagCount; i++)
+    {
+        printf("key:[%s], value[%s]\n", infoToPrint->taglist[i].key, infoToPrint->taglist[i].value);
+    }
+}
+obs_status get_bucket_tagging_callback(int tagging_count, obs_name_value *tagging_list, void *callback_data)
+{
+    int tag_num = 0;
+    TaggingInfo * tag_info = (TaggingInfo *)callback_data;
+    tag_info->tagCount = tagging_count;
+    if (tagging_count > 0)
+    {
+        for (tag_num = 0; tag_num < tagging_count; tag_num++)
+        {
+            memcpy_s(tag_info->taglist[tag_num].key, sizeof(tag_info->taglist[tag_num].key), (&tagging_list[tag_num])->name, strlen((&tagging_list[tag_num])->name) + 1);
+            memcpy_s(tag_info->taglist[tag_num].value, sizeof(tag_info->taglist[tag_num].value), (&tagging_list[tag_num])->value, strlen((&tagging_list[tag_num])->value) + 1);
+        }
+    }
+    printTagInfo(tag_info);
+    return OBS_STATUS_OK;
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        TaggingInfo *taggingInfo = (TaggingInfo *)callback_data;
+        taggingInfo->ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Tagging
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1304.html b/docs/obs_3rd_party/c_sdk/obs_20_1304.html new file mode 100644 index 000000000..28f88cd79 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1304.html @@ -0,0 +1,1745 @@ + + +

Deleting Bucket Tags

+

Function

If you add tags to a bucket, SDRs generated for the requests sent to this bucket will include these tags, so you can use the tags to classify SDRs for detailed cost analysis. For example, if you have an application that uploads its running data to a bucket, you can tag the bucket with the application name. Then, you can analyze the cost of this application by using that tag.

+

This API deletes the tags of a bucket.

+
+

Restrictions

  • To delete bucket tags, you must be the bucket owner or have the required permission (obs:bucket:DeleteBucketTagging in IAM or DeleteBucketTagging in a bucket policy).
+
+

Method

void delete_bucket_tagging(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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, 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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 4 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + + + + + + + +
Table 5 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + +
Table 6 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 7 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+
Value range:
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+
+ +

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket resources related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Deleting Bucket Tags

This example deletes bucket tags.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
#include "eSDKOBS.h"
+#include <stdio.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 completion callback function. 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);
+#define TAG_LIST_LENGTH 10
+int main()
+{
+    // The following code shows how to use delete_bucket_tagging to delete bucket tags:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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 };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Delete bucket tags.
+    delete_bucket_tagging(&options, &response_handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("delete bucket tagging successfully.\n");
+    }
+    else
+    {
+        printf("delete bucket tagging failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Tagging
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1500.html b/docs/obs_3rd_party/c_sdk/obs_20_1500.html new file mode 100644 index 000000000..1f0d39880 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1500.html @@ -0,0 +1,15 @@ + + +

Other APIs

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1501.html b/docs/obs_3rd_party/c_sdk/obs_20_1501.html new file mode 100644 index 000000000..20ac21281 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1501.html @@ -0,0 +1,810 @@ + + +

Server-Side Encryption

+

Function

This API configures server-side encryption for objects, so that they will be encrypted or decrypted when you upload them to or download them from a bucket.

+

The encryption and decryption happen on the server side.

+

OBS supports the following two server-side encryption methods, which use the same industry-standard AES256 encryption algorithm but provide different ways to manage keys:

+
  • SSE-KMS is based on the key provided by Key Management Service (KMS).
  • SSE-C is based on the key and its MD5 value provided by the customer.
+

When server-side encryption is used, the returned ETag value is not the object's MD5 value. OBS will verify the object's MD5 value as long as the upload request includes the Content-MD5 header, no matter whether server-side encryption is used or not.

+
+

Restrictions

  • To use server-side encryption, you must have the PutEncryptionConfiguration permission. The bucket owner has this permission by default and can grant it to others.
+
+

Supported APIs

The following table lists APIs related to server-side encryption:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

API Method in OBS C SDK

+

Description

+

Supported Encryption Method

+

put_object

+

Sets the encryption algorithm and key during object upload to enable server-side encryption.

+

SSE-KMS

+

SSE-C

+

get_object

+

Sets the decryption algorithm and key during object download to decrypt the object.

+

SSE-C

+

copy_object

+
  1. Sets the decryption algorithm and key for decrypting the source object during object copy.
  2. Sets the encryption algorithm and key during object copy to enable the encryption algorithm for the target object.
+

SSE-KMS

+

SSE-C

+

get_object_metadata

+

Sets the decryption algorithm and key when obtaining the object metadata to decrypt the object.

+

SSE-C

+

initiate_multi_part_upload

+

Sets the encryption algorithm and key when initiating a multipart upload to enable server-side encryption for the final object generated.

+

SSE-KMS

+

SSE-C

+

upload_part

+

Sets the encryption algorithm and key during multipart upload to enable server-side encryption for parts.

+

SSE-C

+

copy_part

+
  1. Sets the decryption algorithm and key for decrypting the source object during object copy.
  2. Sets the encryption algorithm and key during part copy to enable the encryption for the target part.
+

SSE-C

+
+
+
+

Code Examples: Object Encryption and Upload

This example uses server-side encryption when uploading an object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data);
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct put_file_object_callback_data
+{
+    FILE *infile;
+    uint64_t content_length;
+    obs_status ret_status;
+} put_file_object_callback_data;
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data);
+int main()
+{
+    // The following code shows how to use server-side encryption when uploading an object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // When server-side encryption is used, HTTPS must be used.
+    options.bucket_options.protocol = OBS_PROTOCOL_HTTPS;
+    // Initialize the properties of the object to be uploaded.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Name of the object to be uploaded
+    char *key = "example_put_file_test";
+    // Uploaded file
+    char file_name[256] = "./example_local_file_test.txt";
+    uint64_t content_length = 0;
+    // Initialize the structure for storing the uploaded data.
+    put_file_object_callback_data data;
+    memset(&data, 0, sizeof(put_file_object_callback_data));
+    // Open the file and obtain the file length.
+    content_length = open_file_and_get_length(file_name, &data);
+    // Set the callback function.
+    obs_put_object_handler putobjectHandler =
+    {
+        { &response_properties_callback, &put_file_complete_callback },
+        &put_file_data_callback
+    };
+    //Configure server-side encryption.
+    server_side_encryption_params encryption_params;
+    memset(&encryption_params, 0, sizeof(server_side_encryption_params));
+    encryption_params.ssec_customer_algorithm = "AES256";
+    encryption_params.ssec_customer_key =
+        "K7QkYpBkM5+hcs27fsNkUnNVaobncnLht/rCB2o/9Cw=";
+    put_object(&options, key, content_length, &put_properties, &encryption_params, &putobjectHandler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("put object from file successfully. \n");
+    }
+    else
+    {
+        printf("put object failed(%s).\n",
+            obs_get_status_name(data.ret_status));
+    }
+    if (data.infile != NULL) {
+        fclose(data.infile);
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+int put_file_data_callback(int buffer_size, char *buffer,
+    void *callback_data)
+{
+    put_file_object_callback_data *data =
+        (put_file_object_callback_data *)callback_data;
+    int ret = 0;
+    if (data->content_length) {
+        int toRead = ((data->content_length > (unsigned)buffer_size) ?
+            (unsigned)buffer_size : data->content_length);
+        ret = fread(buffer, 1, toRead, data->infile);
+    }
+    uint64_t originalContentLength = data->content_length;
+    data->content_length -= ret;
+    if (data->content_length) {
+        printf("%llu bytes remaining ", (unsigned long long)data->content_length);
+        printf("(%d%% complete) ...\n",
+            (int)(((originalContentLength - data->content_length) * 100) / originalContentLength));
+    }
+    return ret;
+}
+void put_file_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    put_file_object_callback_data *data = (put_file_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+uint64_t open_file_and_get_length(char *localfile, put_file_object_callback_data *data)
+{
+    uint64_t content_length = 0;
+    const char *body = 0;
+    if (!content_length)
+    {
+        struct stat statbuf;
+        if (stat(localfile, &statbuf) == -1)
+        {
+            fprintf(stderr, "\nERROR: Failed to stat file %s: ",
+                localfile);
+            return 0;
+        }
+        content_length = statbuf.st_size;
+    }
+    if (!(data->infile = fopen(localfile, "rb")))
+    {
+        fprintf(stderr, "\nERROR: Failed to open input file %s: ",
+            localfile);
+        return 0;
+    }
+    data->content_length = content_length;
+    return content_length;
+}
+
+
+
+
+

Code Examples: Object Decryption and Download

This example uses the server-side decryption function when downloading an object.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data);
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+typedef struct get_object_callback_data
+{
+    FILE *outfile;
+    obs_status ret_status;
+}get_object_callback_data;
+FILE * write_to_file(char *localfile);
+int main()
+{
+    // The following code shows how to use server-side decryption when downloading an object:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // When server-side encryption is used, HTTPS must be used.
+    options.bucket_options.protocol = OBS_PROTOCOL_HTTPS;
+    // Set the name of the local file to which the object is downloaded.
+    char *file_name = "./example_get_file_test";
+    obs_object_info object_info;
+    // Set the object to be downloaded.
+    memset(&object_info, 0, sizeof(obs_object_info));
+    object_info.key = "example_get_file_test";
+    object_info.version_id = NULL;
+    //Set the structure for storing the downloaded object data based on service requirements.
+    get_object_callback_data data;
+    data.ret_status = OBS_STATUS_BUTT;
+    data.outfile = write_to_file(file_name);
+    // Define parameters for range-based download.
+    obs_get_conditions getcondition;
+    memset(&getcondition, 0, sizeof(obs_get_conditions));
+    init_get_properties(&getcondition);
+    // Define the download callback function.
+    obs_get_object_handler get_object_handler =
+    {
+        { &response_properties_callback,
+          &get_object_complete_callback},
+        &get_object_data_callback
+    };
+    //Server-side encryption (SSE-C)
+    server_side_encryption_params encryption_params;
+    memset(&encryption_params, 0, sizeof(server_side_encryption_params));
+    encryption_params.ssec_customer_algorithm = "AES256";
+    encryption_params.ssec_customer_key =
+        "K7QkYpBkM5+hcs27fsNkUnNVaobncnLht/rCB2o/9Cw=";
+    get_object(&options, &object_info, &getcondition, &encryption_params, &get_object_handler, &data);
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("get object successfully. \n");
+    }
+    else
+    {
+        printf("get object failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    fclose(data.outfile);
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+// Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+obs_status get_object_data_callback(int buffer_size, const char *buffer,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    size_t wrote = fwrite(buffer, 1, buffer_size, data->outfile);
+    return ((wrote < (size_t)buffer_size) ?
+        OBS_STATUS_AbortedByCallback : OBS_STATUS_OK);
+}
+void get_object_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    get_object_callback_data *data = (get_object_callback_data *)callback_data;
+    data->ret_status = status;
+}
+FILE * write_to_file(char *localfile)
+{
+    FILE *outfile = 0;
+    if (localfile) {
+        struct stat buf;
+        if (stat(localfile, &buf) == -1) {
+            outfile = fopen(localfile, "wb");
+        }
+        else {
+            outfile = fopen(localfile, "a");
+        }
+        if (!outfile) {
+            fprintf(stderr, "\nERROR: Failed to open output file %s: ",
+                localfile);
+            return outfile;
+        }
+    } else {
+        fprintf(stderr, "\nERROR: Failed to open output file, it's NULL, write object to stdout.",
+            localfile);
+        outfile = stdout;
+    }
+    return outfile;
+}
+
+
+
+
+
+
+
+
Parent topic: Other APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1600.html b/docs/obs_3rd_party/c_sdk/obs_20_1600.html new file mode 100644 index 000000000..b541e9f95 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1600.html @@ -0,0 +1,15 @@ + + +

Troubleshooting

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1601.html b/docs/obs_3rd_party/c_sdk/obs_20_1601.html new file mode 100644 index 000000000..b1c586454 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1601.html @@ -0,0 +1,728 @@ + + +

OBS Server-Side Error Codes

+

If the OBS server encounters an error when processing a request, a response containing the error code and error description is returned. The following table lists details about each error code and HTTP status code:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

HTTP Status Code

+

Error Code

+

Error Message

+

Solution

+

301 Moved Permanently

+

PermanentRedirect

+

The requested bucket has been permanently redirected to a new address. All future requests must be sent to the new address.

+

Send the request to the returned redirection address.

+

301 Moved Permanently

+

WebsiteRedirect

+

The website request lacks bucketName.

+

Put the bucket name in the request and try again.

+

307 Moved Temporarily

+

TemporaryRedirect

+

Temporary redirection. If the DNS is updated, the request is redirected to the bucket.

+

The system automatically redirects the request, or the client needs to send the request to the redirection address.

+

400 Bad Request

+

BadDigest

+

The client-specified value of Content-MD5 does not match the value received by OBS.

+

Check whether the MD5 value carried in the header is the same as that calculated based on the message body.

+

400 Bad Request

+

BadDomainName

+

The domain name is invalid.

+

Use a valid domain name.

+

400 Bad Request

+

BadRequest

+

Invalid request parameters.

+

Modify the parameter based on the error details returned in the message body.

+

400 Bad Request

+

CustomDomainAreadyExist

+

The configured domain already exists.

+

The domain has been configured and does not need to be configured again.

+

400 Bad Request

+

CustomDomainNotExist

+

The domain to be deleted does not exist.

+

The domain is not configured or has been deleted. You do not need to delete it.

+

400 Bad Request

+

EntityTooLarge

+

The size of the object uploaded using the POST method exceeds the upper limit.

+

Modify the conditions specified in the upload policy or reduce the object size.

+

400 Bad Request

+

EntityTooSmall

+

The size of the object uploaded using the POST method does not reach the lower limit.

+

Modify the conditions specified in the upload policy or increase the object size.

+

400 Bad Request

+

IllegalLocationConstraintException

+

A request without Location is sent for creating a bucket in a non-default region.

+

Send the bucket creation request to the default region, or send the request with the Location of the non-default region.

+

400 Bad Request

+

IncompleteBody

+

The request body received is incomplete due to network or other problems.

+

Upload the object again.

+

400 Bad Request

+

IncorrectNumberOfFilesInPost Request

+

Each POST request must contain a file to be uploaded.

+

Carry a file to be uploaded.

+

400 Bad Request

+

InvalidArgument

+

Invalid parameter.

+

Modify the parameter based on the error details returned in the message body.

+

400 Bad Request

+

InvalidBucket

+

The bucket to be accessed does not exist.

+

Try another bucket name.

+

400 Bad Request

+

InvalidBucketName

+

The bucket name specified in the request is invalid because it has exceeded the maximum allowed length or contains special characters that are not allowed.

+

Try another bucket name.

+

400 Bad Request

+

InvalidEncryptionAlgorithmError

+

Incorrect encryption algorithm. The object cannot be decrypted due to incorrect encryption header carried when downloading the SSE-C encrypted object.

+

Carry the correct encryption header when downloading the object.

+

400 Bad Request

+

InvalidLocationConstraint

+

The specified Location in the bucket creation request is invalid or does not exist.

+

Specify the correct Location in the bucket creation request.

+

400 Bad Request

+

InvalidPart

+

One or more specified parts are not found. The parts may not be uploaded or the specified entity tags do not match those of the parts.

+

Specify the correct parts and entity tags.

+

400 Bad Request

+

InvalidPartOrder

+

Parts are not listed in ascending order by part number.

+

Sort the parts in ascending order and assemble them again.

+

400 Bad Request

+

InvalidPolicyDocument

+

The content of the form does not meet the conditions specified in the policy document.

+

Modify the policy in the form based on the error details in the message body and try again.

+

400 Bad Request

+

InvalidRedirectLocation

+

Invalid redirection address.

+

Specify the correct address.

+

400 Bad Request

+

InvalidRequest

+

Invalid request.

+

Modify the parameter based on the error details returned in the message body.

+

400 Bad Request

+

InvalidRequestBody

+

The request body is invalid. The request requires a message body but no message body is included.

+

Upload the message body in the correct format.

+

400 Bad Request

+

InvalidTargetBucketForLogging

+

The delivery group has no ACL permission for the target bucket.

+

Configure the target bucket ACL and try again.

+

400 Bad Request

+

KeyTooLongError

+

The provided key is too long.

+

Use a shorter key.

+

400 Bad Request

+

KMS.DisabledException

+

The master key is disabled in SSE-KMS.

+

Replace the key and try again, or contact the technical support.

+

400 Bad Request

+

KMS.NotFoundException

+

The master key does not exist in SSE-KMS.

+

Retry with the correct master key.

+

400 Bad Request

+

MalformedACLError

+

The provided XML file has syntax errors or does not meet the format requirements.

+

Use the correct XML format and retry.

+

400 Bad Request

+

MalformedError

+

The XML format in the request is incorrect.

+

Use the correct XML format and retry.

+

400 Bad Request

+

MalformedLoggingStatus

+

The XML format of Logging is incorrect.

+

Use the correct XML format and retry.

+

400 Bad Request

+

MalformedPolicy

+

The bucket policy fails the check.

+

Modify the bucket policy based on the error details returned in the message body.

+

400 Bad Request

+

MalformedQuotaError

+

The Quota XML format is incorrect.

+

Use the correct XML format and retry.

+

400 Bad Request

+

MalformedXML

+

A configuration item is in the wrong XML format.

+

Use the correct XML format and retry.

+

400 Bad Request

+

MaxMessageLengthExceeded

+

A message body is carried in the request for copying an object.

+

Remove the message body and retry.

+

400 Bad Request

+

MetadataTooLarge

+

The size of the metadata header exceeds the upper limit.

+

Reduce the size of the metadata header.

+

400 Bad Request

+

MissingRegion

+

The region information is missing in the request, and no default region is defined in the system.

+

Carry the region information in the request.

+

400 Bad Request

+

MissingRequestBodyError

+

An empty XML file is sent in a request.

+

Provide the correct XML file.

+

400 Bad Request

+

MissingRequiredHeader

+

A required header is missing in the request.

+

Provide required headers.

+

400 Bad Request

+

MissingSecurityHeader

+

A required header is missing in the request.

+

Provide required headers.

+

400 Bad Request

+

TooManyBuckets

+

You have attempted to create more buckets than allowed.

+

Delete some buckets and try again.

+

400 Bad Request

+

TooManyCustomDomains

+

The number of user domains exceeds the upper limit.

+

Delete some user domains and try again.

+

400 Bad Request

+

TooManyWrongSignature

+

The request is rejected due to too many signature errors.

+

Use the correct AK and try again.

+

400 Bad Request

+

UnexpectedContent

+

The request requires a message body, which is not carried by the client. Or the request does not require a message body but the client carried one.

+

Try again according to the instruction.

+

400 Bad Request

+

UserKeyMustBeSpecified

+

This operation is only available to some users.

+

Contact the technical support.

+

403 Forbidden

+

AccessDenied

+

Access is denied because the request does not carry a date header or the header format is incorrect.

+

Provide a correct date header in the request.

+

403 Forbidden

+

AccessForbidden

+

Insufficient permissions. No CORS rule is configured for the bucket, or the CORS rule is not matched.

+

Modify the CORS configuration of the bucket or send the OPTIONS request that matches the CORS configuration of the bucket.

+

403 Forbidden

+

AllAccessDisabled

+

You have no permission to perform the operation. The bucket name is forbidden.

+

Try another bucket name.

+

403 Forbidden

+

DeregisterUserId

+

The user has been deregistered.

+

Top up the account or register a new account.

+

403 Forbidden

+

InArrearOrInsufficientBalance

+

The user account is in arrears, or the account balance insufficient.

+

Top up the account.

+

403 Forbidden

+

InsufficientStorageSpace

+

Insufficient storage space.

+

If the quota is exceeded, increase the quota or delete some objects.

+

403 Forbidden

+

InvalidAccessKeyId

+

The access key ID provided by the customer does not exist in the system.

+

Provide the correct access key ID.

+

403 Forbidden

+

RequestTimeTooSkewed

+

The request time and the server time differ a lot.

+

Check whether there is a large difference between the client time and the current time.

+

403 Forbidden

+

SignatureDoesNotMatch

+

The provided signature does not match the signature calculated by OBS.

+

Check your secret access key and signature calculation method.

+

403 Forbidden

+

Unauthorized

+

You have not been authenticated in real name.

+

Complete real-name authentication and try again.

+

404 Not Found

+

NoSuchBucket

+

The specified bucket does not exist.

+

Create a bucket and perform the operation again.

+

404 Not Found

+

NoSuchBucketPolicy

+

No bucket policy exists.

+

Configure a bucket policy.

+

404 Not Found

+

NoSuchCORSConfiguration

+

No CORS configuration exists.

+

Configure CORS first.

+

404 Not Found

+

NoSuchCustomDomain

+

The requested custom domain does not exist.

+

Set a custom domain first.

+

404 Not Found

+

NoSuchKey

+

The specified key does not exist.

+

Upload an object first.

+

404 Not Found

+

NoSuchLifecycleConfiguration

+

The requested lifecycle rule does not exist.

+

Configure a lifecycle rule first.

+

404 Not Found

+

NoSuchUpload

+

The specified multipart upload does not exist. The upload ID does not exist or the multipart upload has been aborted or completed.

+

Use the existing part or reinitialize the part.

+

404 Not Found

+

NoSuchVersion

+

The specified version ID does not match any existing version.

+

Use a correct version ID.

+

404 Not Found

+

NoSuchWebsiteConfiguration

+

The requested website does not exist.

+

Configure the website first.

+

405 Method Not Allowed

+

MethodNotAllowed

+

The specified method is not allowed against the requested resource.

+

The message "Specified method is not supported." is returned.

+

The method is not allowed.

+

408 Request Timeout

+

RequestTimeout

+

No read or write operation is performed within the timeout period of the socket connection between the user and the server.

+

Check the network and try again, or contact technical support.

+

409 Conflict

+

BucketAlreadyExists

+

The requested bucket name already exists. The bucket namespace is shared by all users of OBS. Select another name and retry.

+

Try another bucket name.

+

409 Conflict

+

BucketAlreadyOwnedByYou

+

You already have a bucket with the same name.

+

You do not need to create this bucket again.

+

409 Conflict

+

BucketNotEmpty

+

The bucket that you tried to delete is not empty.

+

Delete the objects in the bucket and then delete the bucket.

+

409 Conflict

+

OperationAborted

+

A conflicting operation is being performed on this resource. Try again later.

+

Try again later.

+

409 Conflict

+

ServiceNotSupported

+

The request method is not supported by the server.

+

Not supported by the server. Contact the technical support.

+

411 Length Required

+

MissingContentLength

+

The HTTP header Content-Length is not provided.

+

Provide the Content-Length header.

+

412 Precondition Failed

+

PreconditionFailed

+

At least one of the specified preconditions is not met.

+

Modify the request based on Condition in the returned message body.

+

416 Client Requested Range Not Satisfiable

+

InvalidRange

+

The requested range cannot be obtained.

+

Replace the range value and try again.

+

500 Internal Server Error

+

InternalError

+

An internal error occurs. Retry later.

+

Contact the technical support.

+

501 Not Implemented

+

ServiceNotImplemented

+

The request method is not implemented by the server.

+

Not supported currently. Contact the technical support.

+

503 Service Unavailable

+

ServiceUnavailable

+

The server is overloaded or has internal errors.

+

Try again later or contact the technical support.

+

503 Service Unavailable

+

SlowDown

+

Too frequent requests. Reduce your request frequency.

+

Too frequent requests. Reduce your request frequency.

+
+
+
+
+
+
Parent topic: Troubleshooting
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1602.html b/docs/obs_3rd_party/c_sdk/obs_20_1602.html new file mode 100644 index 000000000..85be613da --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1602.html @@ -0,0 +1,13 @@ + + +

SDK Error Handling

+

SDK errors include the errors returned during the check of function parameters and those returned by the OBS server.

+

SDK error handling information:

+
  • obs_status: Error code
  • obs_get_status_name(): Obtaining the error description
  • obs_status_is_retryable(): Checking whether the error code requires service retry
+
+
+
+
Parent topic: Troubleshooting
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1603.html b/docs/obs_3rd_party/c_sdk/obs_20_1603.html new file mode 100644 index 000000000..7ed91b8d7 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1603.html @@ -0,0 +1,75 @@ + + +

Log Analysis

+

Log Path

The OBS C SDK log path is specified by the LogPath field in OBS.ini. By default, logs are stored in the logs directory at the same level as the lib directory of the C SDK dynamic library. To locate a fault, view eSDK-OBS-API-*-C.run.log or obs-sdk-c.run.log in the logs directory.

+

OBS.ini must be in the same directory as libeSDKLogAPI.so.

+

+
+

Log Format

The SDK log format is: Log time|log level|thread ID|log content. The following are example logs:

+
Run logs
+2018-05-15 22:22:54 803| INFO|[140677572568864]|request_perform start
+
+

Log Levels

When current logs cannot be used to troubleshoot system faults, you can change the log level to obtain more information. You can obtain the most information in DEBUG(0) logs and the least information in ERROR(3) logs.

+

Log level description:

+
  • DEBUG(0): Debug level. If this level is set, logs at the INFO level and some debugging information will be printed.
  • INFO(1): Information level. If this level is set, logs at the WARN level, calling process and key information of OBS APIs will be printed.
  • WARN(2): Warning level. If this level is set, logs at the ERROR level and some critical events, such as curl_global_init initialization fail, will be printed.
  • ERROR(3): Error level. If this level is set, only error information will be printed.
+
+

Enabling System Logging

In the lib directory, modify OBS.ini, modify the size, number, and level of logs. (The *_Run parameter is the most common configuration item.)

+
;Every line must be less than 1024
+[LogConfig]
+;Log Size: unit=KB, 10MB = 10KB * 1024 = 10240KB
+LogSize_Interface=10240
+LogSize_Operation=10240
+LogSize_Run=10240
+;Log Num
+LogNum_Interface=10
+LogNum_Operation=10
+LogNum_Run=10
+;Log level: debug = 0,info = 1,warn = 2,error = 3
+LogLevel_Interface=0
+LogLevel_Operation=0
+LogLevel_Run=0
+;LogFilePermission
+LogFilePermission=0600
+[ProductConfig]
+;Product Name
+sdkname=eSDK-OBS-API-Linux-C
+[LogPath]
+;Log Path is relative to the path of configuration file
+LogPath=../logs
+
+

Other Configurations

In Windows, the LogPath field in the OBS.ini can be read in type wchar_t. To do that, you need to set the encoding for the file path first. An example is given here:

+

set_file_path_code(UNICODE_CODE);//ANSI_CODE is used by default.

+

In addition, the local file path for functions listed in the table below must also be in type wchar_t (parameters are passed in type char* and processed into type wchar_t internally).

+ +
+ + + + + + + + + + + + + +
Table 1

Related Function

+

Description

+

download_file

+

The downLoad_file and check_point_file members of the download_file_config parameter must be in type wchar_t. Pass them in type char*.

+

upload_file

+

The upload_file and check_point_file members of the upload_file_config parameter must be in type wchar_t. Pass them in type char*.

+

set_obs_log_path

+

The log_path parameter must be in type wchar_t. Pass it in type char*.

+
+
+
+
+
+
+
Parent topic: Troubleshooting
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1702.html b/docs/obs_3rd_party/c_sdk/obs_20_1702.html new file mode 100644 index 000000000..3e8c5d320 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1702.html @@ -0,0 +1,20 @@ + + +

Change History

+
+
+ + + + + + + +

Date

+

What's New

+

2025-04-30

+

This is the first official release.

+
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1800.html b/docs/obs_3rd_party/c_sdk/obs_20_1800.html new file mode 100644 index 000000000..a9da8968f --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1800.html @@ -0,0 +1,13 @@ + + +

FAQs

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1804.html b/docs/obs_3rd_party/c_sdk/obs_20_1804.html new file mode 100644 index 000000000..68b4c4da5 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1804.html @@ -0,0 +1,20 @@ + + +

Invalid Proxy Settings

+
  • When the proxy is configured in a Windows SDK demo, the program reports the following error and the proxy configuration fails.

    +

    Root cause: Due to asynchronous updates, the demo header file eSDKOBS.h of certain SDK versions diverges from the SDK eSDKOBS.h, rendering the proxy settings in the option invalid.

    +

    Solution:

    +
    1. Replace yourSDKpath\source\eSDK_OBS_API\eSDK_OBS_API_C++\inc\eSDKOBS.h with yourSDKpath\source\eSDK_OBS_API\eSDK_OBS_API_C++\build\obs\demo\eSDKOBS.h.
    2. Modify the demo as instructed here to adapt to the changes of eSDKOBS.h. (The adaptation of version 3.22.7 is used as an example. The adaptation process of other versions may differ.)

      In the yourSDKpath\source\eSDK_OBS_API\eSDK_OBS_API_C++\build\obs\demo\ demo_windows.cpp file, in line 4749, add obs_upload_file_server_callback server_callback; in line 4750, add , server_callback after the fourth parameter in the upload_file function. See the following figure.

      +

      +
    +
  • The proxy is configured but the connection still fails.

    Root cause: The proxy might not be configured in the get_api_version function of the SDK request.c.

    +

    Solution:

    +

    Configure the proxy (add the CURLOPT_PROXY and CURLOPT_PROXYUSERPWD items for curl) in the get_api_version function by referring to the method for configuring the proxy in the setup_curl function of the SDK request.c.

    +
+
+
+
+
Parent topic: FAQs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1805.html b/docs/obs_3rd_party/c_sdk/obs_20_1805.html new file mode 100644 index 000000000..2361fbbca --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1805.html @@ -0,0 +1,22 @@ + + +

Initializing the SDK

+

ObsClient functions as the C client for accessing OBS. It offers callers a series of APIs for interaction with OBS. These APIs are used for managing and operating resources, such as buckets and objects, stored in OBS.

+

Before using the OBS C SDK to initiate an OBS request, you need to call the initialization API. When you are exiting the process, you need to call the initialization cancellation API to release resources.

+

Before using the C SDK, you must first call obs_initialize to complete the initialization. This API only needs to called once in a process.

+
obs_status  ret_status = OBS_STATUS_BUTT;
+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 ret_status;
+}
+obs_deinitialize();
+// Do not repeatedly call obs_initialize or obs_deinitialize, because these operations may lead to invalid memory access.
+
+
+
+
Parent topic: Getting Started
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1806.html b/docs/obs_3rd_party/c_sdk/obs_20_1806.html new file mode 100644 index 000000000..f9f5d1087 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1806.html @@ -0,0 +1,1795 @@ + + +

Aborting a Multipart Upload

+

Function

This API aborts a multipart upload, which is specified by its ID.

+

After a multipart upload is aborted, its upload ID cannot be used to upload any part. And the space occupied by all uploaded parts will be freed up. If any parts are being uploaded when you abort the upload, they may or may not be uploaded successfully. To free up the space occupied by all uploaded parts, you must abort the multipart upload after all parts have been uploaded.

+
+

Restrictions

  • To abort a multipart upload, you must be the bucket owner or have the required permission (obs:object:AbortMultipartUpload in IAM or AbortMultipartUpload in a bucket policy).
+
+

Method

1
+2
void abort_multi_part_upload(const obs_options *options, char *key, const char *upload_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

upload_id

+

char *

+

Yes

+

Explanation:

+

Identifies a multipart upload.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+
+

Code Examples: Aborting a Multipart Upload

This example aborts a multipart upload task.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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 completion callback function. 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);
+int main()
+{
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Object name in the multipart upload
+    char *key = "example_multi_part_upload_object_key";
+    // Multipart upload ID
+    char *upload_id = "00000194178F7ACE4014F60E75720850";
+    // Set the response callback function.
+    obs_response_handler handler = {
+        &response_properties_callback,
+        &response_complete_callback
+    };
+    // Abort the multipart upload task.
+    obs_status ret_status; 
+    abort_multi_part_upload(&options, key, upload_id, &handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("test abort_multi_part_upload successfully.\n");
+    }
+    else
+    {
+        printf("test abort_multi_part_upload failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Multipart Upload APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1807.html b/docs/obs_3rd_party/c_sdk/obs_20_1807.html new file mode 100644 index 000000000..3ae514854 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1807.html @@ -0,0 +1,2241 @@ + + +

Listing Uploaded Parts

+

Function

This API lists the uploaded parts in a specified bucket. This request must contain the multipart upload ID.

+

You can list the uploaded parts of a specified multipart upload or of all ongoing multipart uploads. For each listing request, OBS can list a maximum of 1,000 uploaded parts. If more than 1,000 parts were uploaded for a multipart upload, you need to send more than one request to list all uploaded parts. Assembled parts will not be listed.

+
+

Restrictions

  • To list uploaded parts, you must be the bucket owner or have the required permission (obs:object:ListMultipartUploadParts in IAM or ListMultipartUploadParts in a bucket policy).
+
+

Method

1
+2
void list_parts (const obs_options *options, char *key, list_part_info *listpart,
+        obs_list_parts_handler *handler, void *callback_data);
+
+
+
+

Request Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1 List of request parameters

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

options

+

constobs_options*

+

Yes

+

Explanation:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

constchar *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

listpart

+

list_part_info *

+

Yes

+

Explanation:

+

Identifies a multipart upload.

+

Restrictions:

+

None

+

handler

+

obs_list_parts_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 11 list_part_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

upload_id

+

char *

+

No

+

Explanation:

+

Multipart upload ID

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

max_parts

+

unsigned int

+

No

+

Explanation:

+

Maximum number of parts that can be listed

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

part_number_marker

+

unsigned int

+

No

+

Explanation:

+

Part after which the part listing begins. OBS lists only parts with greater numbers than that specified by this parameter.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_list_parts_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

list_parts_callback_ex

+

obs_list_parts_callback_ex *

+

Yes

+

Explanation:

+

Callback for listing parts, which is used to obtain the information about the listed parts.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_list_parts_callback_ex

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

uploaded_parts

+

obs_uploaded_parts_total_info *

+

Yes

+

Explanation:

+

Information about the multipart task.

+

Restrictions:

+

None

+

parts

+

obs_list_parts *

+

Yes

+

Explanation:

+

Part information array

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_uploaded_parts_total_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

is_truncated

+

int

+

Yes

+

Explanation:

+

Whether the result list is truncated in the response.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

nextpart_number_marker

+

unsigned int

+

Yes

+

Explanation:

+

If not all results are returned, this parameter is returned to specify the part_number_marker value of the next request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

initiator_id

+

char *

+

Yes

+

Explanation:

+

Specifies the domain ID (account ID) of the initiator of the multipart upload task.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the account ID, see How Do I Get My Account ID and User ID?

+

Default value:

+

None

+

owner_id

+

char *

+

Yes

+

Explanation:

+

The value of this parameter is the same as that of initiator_id.

+

Restrictions:

+

None

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

char *

+

Yes

+

Explanation:

+

Storage class.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

parts_count

+

int

+

Yes

+

Explanation:

+

Number of parts in obs_list_parts

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_list_parts

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

part_number

+

unsigned int

+

No

+

Explanation:

+

Number of an uploaded part.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

last_modified

+

int64_t

+

No

+

Explanation:

+

Time when a part was uploaded

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

ETag value of the uploaded part. It is the unique identifier of the part content and is used to verify data consistency when parts are assembled.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

size

+

uint64_t

+

Yes

+

Explanation:

+

Size of the uploaded part.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Storage class.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples: Listing Uploaded Parts

This example lists parts using list_parts.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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 completion callback function. 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);
+// The callback function for listing parts. The information about the listed parts in the callback can be recorded in callback_data (custom callback data).
+obs_status list_parts_callback(obs_uploaded_parts_total_info* uploaded_parts,
+    obs_list_parts *parts, void *callback_data);
+int main()
+{
+    // The following code shows how to list the uploaded parts using list_parts:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // List the object names of the parts.
+    char *key = "example_multi_part_upload_object_key";
+    list_part_info list_part_infos = { 0 };
+    list_part_infos.upload_id = "00000194178F94B64016E9C3BD03E89B";
+    list_part_infos.max_parts = 1000;
+    list_part_infos.part_number_marker = 0;
+    // Set the response callback function.
+    obs_list_parts_handler handler = {
+        {
+            &response_properties_callback,
+            &response_complete_callback
+        },
+        &list_parts_callback
+    };
+    obs_status ret_status;
+    list_parts(&options, key, &list_part_infos, &handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("test list_parts successfully.\n");
+    }
+    else
+    {
+        printf("test list_parts failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// The callback function for listing parts. The information about the listed parts in the callback can be recorded in callback_data (custom callback data).
+obs_status list_parts_callback(obs_uploaded_parts_total_info* uploaded_parts,
+    obs_list_parts *parts, void *callback_data) {
+    if (uploaded_parts == NULL) {
+        printf("uploaded_parts is NULL.\n");
+    }
+    else {
+        printf("uploaded_parts->initiator_id is %s\n", uploaded_parts->initiator_id);
+        printf("uploaded_parts->initiator_display_name is %s\n", uploaded_parts->initiator_display_name);
+        printf("uploaded_parts->is_truncated is %d\n", uploaded_parts->is_truncated);
+        printf("uploaded_parts->nextpart_number_marker is %u\n", uploaded_parts->nextpart_number_marker);
+        printf("uploaded_parts->owner_id is %s\n", uploaded_parts->owner_id);
+        printf("uploaded_parts->owner_display_name is %s\n", uploaded_parts->owner_display_name);
+        printf("uploaded_parts->storage_class is %s\n", uploaded_parts->storage_class);
+        printf("uploaded_parts->parts_count is %d\n", uploaded_parts->parts_count);
+        if (parts == NULL) {
+            printf("parts is NULL.\n");
+        }
+        else {
+            for (int i = 0; i < uploaded_parts->parts_count; ++i) {
+                printf("parts%d->part_number is %u\n", i + 1, (parts + i)->part_number);
+                printf("parts%d->last_modified is %lld\n", i + 1, (parts + i)->last_modified);
+                printf("parts%d->etag is %s\n", i + 1, (parts + i)->etag);
+                printf("parts%d->size is %llu\n", i + 1, (parts + i)->size);
+                printf("parts%d->storage_class is %s\n", i + 1, (parts + i)->storage_class);
+            }
+        }
+    }
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Multipart Upload APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1808.html b/docs/obs_3rd_party/c_sdk/obs_20_1808.html new file mode 100644 index 000000000..fc77045dc --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1808.html @@ -0,0 +1,2211 @@ + + +

Listing Multipart Uploads

+

Function

This API lists multipart uploads that have been initiated but not completed or cancelled.

+

For each listing request, OBS can list a maximum of 1,000 multipart upload tasks. If there are more than 1,000 tasks, you need to send more than one request to list all of them.

+
+

Restrictions

  • To list multipart uploads, you must be the bucket owner or have the required permission (obs:bucket:ListBucketMultipartUploads in IAM or ListBucketMultipartUploads in a bucket policy).
  • This API requires you have the ListBucketMultipartUploads permission.
  • A bucket owner can grant others the ListBucketMultipartUploads permission.
+
+

Method

1
+2
+3
void list_multipart_uploads(const obs_options *options, const char *prefix, const char *marker, 
+        const char *delimiter, const char* uploadid_marker, int max_uploads, 
+        obs_list_multipart_uploads_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

prefix

+

const char *

+

Yes

+

Explanation:

+

Prefix that the object names in the multipart uploads to be listed must contain.

+

Assume that you have the following objects: logs/day1, logs/day2, logs/day3, and ExampleObject.jpg. If you specify logs/ as the prefix, the multipart uploads that contain logs/day1, logs/day2, or logs/day3 will be returned. If this parameter is left blank and there are no other filtering criteria, all multipart uploads in the bucket will be returned.

+

Restrictions:

+

The value can contain 1 to 1,024 characters.

+

Value range:

+

None

+

Default value:

+

None

+

marker

+

const char *

+

Yes

+

Explanation:

+

Object name after which the multipart upload listing begins.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

delimiter

+

const char *

+

Yes

+

Explanation:

+

Object names are grouped by this parameter, which is often used with prefix. If a prefix is specified, objects with the same string from the prefix to the first delimiter are grouped into one commonPrefixes. If no prefix is specified, objects with the same string from the first character to the first delimiter are grouped into one commonPrefixes.

+

Assume that a bucket has objects abcd, abcde, and bbcde in it. If delimiter is set to d and prefix is set to a, objects abcd and abcde are grouped into a commonPrefixes with abcd as the prefix. If only delimiter is set to d, objects abcd and abcde are grouped into a commonPrefixes with abcd as the prefix, and bbcde is grouped separately into another commonPrefixes with bbcd as the prefix.

+

Restrictions:

+

None

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

uploadid_marker

+

const char *

+

Yes

+

Explanation:

+

Upload ID to start with when listing multipart uploads.

+

Restrictions:

+

This parameter must be used together with keyMarker, indicating multipart uploads with IDs greater than the specified uploadIdMarker for the specified keyMarker are listed.

+

Value range:

+

None

+

Default value:

+

None

+

max_uploads

+

int

+

Yes

+

Explanation:

+

Maximum number of multipart uploads to list.

+

Restrictions:

+

If the specified value is greater than 1000, 1000 is used by default.

+

Value range:

+

An integer from 1 to 1000

+

Default value:

+

1000

+

handler

+

obs_list_multipart_uploads_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_list_multipart_uploads_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

list_mulpu_callback

+

obs_list_multipart_uploads_callback *

+

Yes

+

Explanation:

+

Callback function pointer, which is used to copy the listed data to the custom callback data.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_list_multipart_uploads_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

is_truncated

+

int

+

Yes

+

Explanation:

+

Whether the result list is truncated in the response.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

next_marker

+

const char *

+

Yes

+

Explanation:

+

If not all results are returned, this parameter is returned to specify the marker value of the next request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

next_uploadId_marker

+

const char *

+

Yes

+

Explanation:

+

If not all results are returned, this parameter is returned to specify the uploadid_marker value of the next request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

uploads_count

+

int

+

Yes

+

Explanation:

+

Number of uploads.

+

Restrictions:

+

This parameter is only available for listing objects with multiple versions.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

uploads

+

const obs_list_multipart_upload *

+

Yes

+

Explanation:

+

Listed information.

+

Restrictions:

+

None

+

common_prefixes_count

+

int

+

Yes

+

Explanation:

+

Number of common prefixes.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

common_prefixes

+

const char **

+

Yes

+

Explanation:

+

List of object name prefixes grouped according to the delimiter parameter (if specified)

+

Restrictions:

+

None

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_list_multipart_upload

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

const char *

+

No

+

Explanation:

+

Object name An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

None

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

upload_id

+

const char *

+

No

+

Explanation:

+

Multipart upload ID

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

initiator_id

+

const char *

+

No

+

Explanation:

+

Initiator of the multipart upload

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

owner_id

+

const char *

+

No

+

Explanation:

+

Domain ID (account ID) of the object owner.

+

Restrictions:

+

None

+

Value range:

+

For details about how to obtain the account ID of the bucket owner, see How Do I Get My Account ID and User ID?

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

initiated

+

int64_t

+

No

+

Explanation:

+

Time when the multipart upload was initiated.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples: Listing Multipart Uploads

This example lists multipart upload tasks using list_multipart_uploads.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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 completion callback function. 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);
+// The callback function for listing multipart upload tasks. The information about the listed multipart upload tasks in the callback can be recorded in callback_data (custom callback data).
+obs_status list_multipart_uploads_callback(int is_truncated, const char *next_marker,
+    const char *next_uploadId_marker, int uploads_count,
+    const obs_list_multipart_upload *uploads, int common_prefixes_count,
+    const char **common_prefixes, void *callback_data);
+int main()
+{
+    // The following code shows how to list multipart upload tasks using list_multipart_uploads:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Specify the prefix that the listed tasks must contain in their object names.
+    char *prefix = "example_multi_part_upload_object_key";
+    // Specify key-marker whose following tasks will be listed.
+    char *marker = "";
+    // Used to group the listing results.
+    char *delimiter = "/"; 
+    // The parameter below is valid only when it is used together with key-marker. The tasks with the IDs following the upload-id-marker of the specified key-marker are returned.
+    char *uploadid_marker = "";
+    // Maximum number of multipart upload tasks that can be listed. The value should be from 1 to 1000. If the specified value is beyond this range, the default value 1000 is used.
+    int max_uploads = 1000;
+    // Set the response callback function.
+    obs_list_multipart_uploads_handler handler = {
+        {
+            &response_properties_callback,
+            &response_complete_callback
+        },
+        &list_multipart_uploads_callback
+    };
+    // List multipart upload tasks.
+    obs_status ret_status;
+    list_multipart_uploads(&options, prefix, marker, delimiter, NULL, NULL, &handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status)
+    {
+        printf("test list_multipart_uploads successfully.\n");
+    }
+    else
+    {
+        printf("test list_multipart_uploads failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// The callback function for listing multipart upload tasks. The information about the listed multipart upload tasks in the callback can be recorded in callback_data (custom callback data).
+obs_status list_multipart_uploads_callback(int is_truncated, const char *next_marker,
+    const char *next_uploadId_marker, int uploads_count,
+    const obs_list_multipart_upload *uploads, int common_prefixes_count,
+    const char **common_prefixes, void *callback_data) {
+    printf("is_truncated ? %s\n", is_truncated ? "yes" : "no");
+    printf("next_marker is %s\n", next_marker);
+    printf("next_uploadId_marker is %s\n", next_uploadId_marker);
+    for (int i = 0; i < uploads_count; ++i) {
+        printf("multipart upload task %d. object key is %s\n", i, uploads[i].key);
+        printf("multipart upload task %d. object upload_id is %s\n", i, uploads[i].upload_id);
+        printf("multipart upload task %d. object initiator_id is %s\n", i, uploads[i].initiator_id);
+        printf("multipart upload task %d. object initiator_display_name is %s\n", i, uploads[i].initiator_display_name);
+        printf("multipart upload task %d. object owner_id is %s\n", i, uploads[i].owner_id);
+        printf("multipart upload task %d. object owner_display_name is %s\n", i, uploads[i].owner_display_name);
+        printf("multipart upload task %d. object storage_class is %s\n", i, uploads[i].storage_class);
+        printf("multipart upload task %d. object initiated is %lld\n", i, uploads[i].initiated);
+    }
+    for (int i = 0; i < common_prefixes_count; ++i) {
+        printf("common_prefixes %d is %s\n", i, common_prefixes[i]);
+    }
+    return OBS_STATUS_OK;
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+
+
+
+
+
+
+
+
Parent topic: Multipart Upload APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1809.html b/docs/obs_3rd_party/c_sdk/obs_20_1809.html new file mode 100644 index 000000000..0edf41b7d --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1809.html @@ -0,0 +1,2726 @@ + + +

Assembling Parts

+

Function

This API assembles the uploaded parts to complete the multipart upload. Before performing this operation, you cannot download the uploaded data. When assembling parts, you need to copy the additional message header information recorded during the multipart upload initiation to the object metadata. Such information is processed in the same way the information in a regular object upload is processed. In the case of assembling parts concurrently, the Last Write Wins strategy applies, but the time of Last Write is defined as the time when a multipart upload was initiated.

+

As long as the multipart upload is not aborted, all uploaded parts occupy the space. However, after you assembled the specified parts, those uploaded but not assembled will be deleted to free up space.

+

When assembling parts, OBS arranges parts in ascending order by part number. If any object metadata is provided during the initiation of the multipart upload, OBS will associate this metadata with the object. When the multipart upload is complete, the individual parts will no longer exist. A part assembling request must contain the upload ID, part numbers, and ETag values. OBS responses include the ETag that uniquely identifies the object data. This ETag is not required to be the MD5 hash value of the object data.

+
+

Restrictions

  • To assemble parts, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • After a multipart upload is complete, the uploaded parts that were not assembled will be automatically deleted and cannot be restored. Before assembling parts, use the API for listing uploaded parts to check all parts to ensure no parts were left out.
+
+

Method

1
+2
+3
+4
void complete_multi_part_upload(const obs_options *options, char *key, const char *upload_id, 
+        unsigned int part_number, 
+        obs_complete_upload_Info *complete_upload_Info, obs_put_properties *put_properties,
+        obs_complete_multi_part_upload_handler *handler, void *callback_data); 
+
+
+
+

Request Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1 List of request parameters

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

options

+

constobs_options*

+

Yes

+

Explanation:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

upload_id

+

char *

+

Yes

+

Explanation:

+

Identifies a multipart upload.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

part_number

+

unsigned int

+

Yes

+

Explanation:

+

Number of parts (the length of the complete_upload_Info array)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

complete_upload_Info

+

obs_complete_upload_Info *

+

Yes

+

Explanation:

+

Part information array

+

Restrictions:

+

None

+

put_properties

+

obs_put_properties*

+

No

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

handler

+

obs_complete_multi_part_upload_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_complete_multi_part_upload_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

complete_multipart_upload_callback

+

obs_complete_multi_part_upload_callback *

+

Yes

+

Explanation:

+

Pointer to the callback function for assembling parts, which is used to obtain information about assembling parts.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 17 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 19 obs_complete_upload_Info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

part_number

+

unsigned int

+

Yes

+

Explanation:

+

Part number.

+

Restrictions:

+

None

+

Value range:

+

An integer ranging from 1 to 10000.

+

Default value:

+

None

+

etag

+

char *

+

Yes

+

Explanation:

+

ETag value of a part

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Value of the Expires header in the OBS request. It specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (downloading from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length of the file to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

If the object has not been modified after the specified time, the request is successful. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Specifies a preset ETag value. If the ETag value of the object to be downloaded or copied is different from the value of this parameter, the request is successful. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 23 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 25 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 26 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_complete_multi_part_upload_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

location

+

const char *

+

Yes

+

Explanation:

+

Path of the object the parts are assembled into.

+

Restrictions:

+

Format: /bucketName/objectName

+

Value range:

+

None

+

Default value:

+

None

+

bucket

+

const char *

+

Yes

+

Explanation:

+

Bucket where parts are assembled

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

key

+

const char *

+

Yes

+

Explanation:

+

The name of the object the parts are assembled into. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

etag

+

const char *

+

Yes

+

Explanation:

+

The ETag that uniquely identifies the object after its parts were assembled, calculated based on the ETag of each part.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

Format: /bucketName/objectName

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples: Assembling Parts

This example assembles parts using complete_multi_part_upload.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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 completion callback function. 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);
+obs_status CompleteMultipartUploadCallback_Intern(const char *location,
+    const char *bucket,
+    const char *key,
+    const char *etag,
+    void *callback_data);
+int main()
+{
+    // The following code shows how to assemble parts using complete_multi_part_upload:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    
+    // Initialize the put_properties structure.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Name of the object with parts that need to be assembled
+    char *key = "example_multi_part_upload_object_key";
+    // Specify the part information.
+    char *uploadId = "000001930065F7C64014C38C138D654B";
+    obs_complete_upload_Info info[2];
+    info[0].part_number = 1;
+    info[0].etag = "4662995f27b37f9e3cdd42f682f29b27";
+    info[1].part_number = 2;
+    info[1].etag = "cd37aa94cf614fe5cded93707cbf7f88";
+    unsigned int part_count = sizeof(info) / sizeof(obs_complete_upload_Info);
+    // Set the response callback function.
+    obs_complete_multi_part_upload_handler Handler =
+    {
+        {&response_properties_callback,
+         &response_complete_callback},
+        &CompleteMultipartUploadCallback_Intern
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Assemble the parts.
+    complete_multi_part_upload(&options, key, uploadId, part_count, info, &put_properties,
+        &Handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("test complete upload successfully. \n");
+    }
+    else
+    {
+        printf("test complete upload failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        obs_status *data =
+            (obs_status *)callback_data;
+        *data = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+obs_status CompleteMultipartUploadCallback_Intern(const char *location,
+    const char *bucket,
+    const char *key,
+    const char *etag,
+    void *callback_data)
+{
+    printf("location = %s \nbucket = %s \nkey = %s \neTag = %s \n", location, bucket, key, etag);
+    return OBS_STATUS_OK;
+}
+
+
+
+
  • In this example, the info structure array indicates the list of part numbers and ETags of uploaded parts.
  • Part numbers can be inconsecutive.
+
+
+
+
+
+
Parent topic: Multipart Upload APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1810.html b/docs/obs_3rd_party/c_sdk/obs_20_1810.html new file mode 100644 index 000000000..dab8a63d0 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1810.html @@ -0,0 +1,3041 @@ + + +

Uploading a Part

+

Function

After a multipart upload is initiated, this API uploads a part to a specified bucket. In the upload request, the multipart upload ID must be included. The last part uploaded ranges from 0 to 5 GB, while the other parts range from 100 KB to 5 GB. Parts are numbered from 1 to 10000.

+

When uploading a part, you must specify its upload ID and part number. You can select any part number between 1 and 10000. A part number uniquely identifies a part and its location in the object you are uploading. If the number of an uploaded part is used to upload a new part, the uploaded part will be overwritten. Whenever you upload a part, OBS returns the ETag header in the response. For each part upload, you must record the part number and the ETag value. These values are required in subsequent requests to complete a multipart upload.

+
+

Restrictions

  • To upload a part, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy).
  • After initiating a multipart upload and uploading one or more parts, you must assemble the parts or abort the multipart upload to stop being charged for the storage of the uploaded parts.
  • A part number uniquely identifies a part. If you upload the same numbered part, the new part overwrites the old one. If multiple users upload the same numbered part of the same object at the same time, the "last write wins" policy applies. The time of last write is defined as the creation time in the part metadata. To ensure data accuracy, the client must be locked to address concurrent uploads of the same part of the same object. No locking is needed for concurrent uploads of different parts of the same object.
  • Except the part last uploaded, other parts must be larger than 100 KB. Part sizes will not be verified during upload because which one is last uploaded is not identified until parts are combined.
  • OBS will return ETags (MD5 values) of the received parts to users.
  • To ensure data integrity, set the value of MD5 and add the MD5 value to the Content-MD5 request header. The OBS server will compare the MD5 value contained by each part and that calculated by SDK to verify the data integrity.
  • Part numbers range from 1 to 10000. If a part number exceeds this range, OBS will return error 400 Bad Request.
  • The minimum part size supported by an OBS 3.0 bucket is 100 KB, and the minimum part size supported by an OBS 2.0 bucket is 5 MB. You are advised to perform multipart upload to OBS 3.0 buckets.
+
+

Method

void upload_part(const obs_options *options, char *key, obs_upload_part_info *upload_part_info, 
+        uint64_t content_length, obs_put_properties *put_properties,
+        server_side_encryption_params *encryption_params,
+        obs_upload_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

key

+

char *

+

Yes

+

Explanation:

+

Object name. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

upload_part_info

+

obs_upload_part_info *

+

Yes

+

Explanation:

+

Information about the part upload

+

Restrictions:

+

None

+

content_length

+

uint64_t

+

Yes

+

Explanation:

+

Length of the object content

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

If this parameter is not specified, the SDK automatically calculates the size of the object.

+

put_properties

+

obs_put_properties*

+

No

+

Explanation:

+

Properties of the uploaded object

+

Restrictions:

+

None

+

encryption_params

+

server_side_encryption_params *

+

No

+

Explanation:

+

Encryption setting of the uploaded object

+

Restrictions:

+

None

+

handler

+

obs_upload_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11 server_side_encryption_params

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

encryption_type

+

obs_encryption_type

+

No

+

Explanation:

+

Encryption type.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_encryption_type.

+

kms_server_side_encryption

+

char *

+

No

+

Explanation:

+

Indicates that SSE-KMS is used for server-side encryption.

+

Restrictions:

+

None

+

Value range:

+
  • kms
  • AES256
+

Default value:

+

None

+

kms_key_id

+

char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the kms_server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

AES256 (AES256 encryption algorithm)

+

Default value:

+

None

+

ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to encrypt an object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

Base64-encoded 256-bit key

+

Default value:

+

None

+

des_ssec_customer_algorithm

+

char *

+

No

+

Explanation:

+

Indicates the algorithm used to decrypt a source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+

des_ssec_customer_key

+

char *

+

No

+

Explanation:

+

Indicates the key used to decrypt the source object.

+

Restrictions:

+

The header is used only in SSE-C mode.

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 12 obs_encryption_type

Value

+

Description

+

OBS_ENCRYPTION_KMS

+

Use the KMS encryption.

+

OBS_ENCRYPTION_SSEC

+

Use the SSE-C encryption.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 13 obs_upload_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

upload_data_callback

+

obs_upload_data_callback *

+

Yes

+

Explanation:

+

Callback function pointer, which is used to copy the data to be uploaded to the data upload buffer.

+

Restrictions:

+

None

+

progress_callback

+

obs_progress_callback_internal *

+

Yes

+

Explanation:

+

Pointer to the progress callback function.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 14 obs_progress_callback_internal

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

now

+

uint64_t

+

Yes

+

Explanation:

+

Number of bytes that have been uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

total

+

uint64_t

+

Yes

+

Explanation:

+

Total number of bytes to be uploaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 15 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 16 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 20 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 22 obs_upload_part_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

part_number

+

unsigned int

+

Yes

+

Explanation:

+

Number of the uploaded part.

+

Restrictions:

+

None

+

Value range:

+

An integer ranging from 1 to 10000.

+

Default value:

+

None

+

upload_id

+

int

+

Yes

+

Explanation:

+

ID of a multipart upload task.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Base64-encoded MD5 value of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Value of the Expires header in the OBS request. It specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 24 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 25 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (downloading from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

If the object has not been modified after the specified time, the request is successful. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Specifies a preset ETag value. If the ETag value of the object to be downloaded or copied is different from the value of this parameter, the request is successful. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 26 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 28 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 29 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 30 obs_upload_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

buffer_size

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

buffer

+

char *

+

Yes

+

Explanation:

+

Buffer for storing the data to be uploaded. The data to be uploaded is copied to this buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Example: Uploading a Part

This example uploads parts using upload_part.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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 completion callback function. 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 test_upload_file_callback_data
+{
+    obs_status ret_status;
+    FILE *infile;
+    int part_num;
+    uint64_t part_size;
+    uint64_t start_byte;
+} test_upload_file_callback_data;
+uint64_t get_file_info(char *localfile, test_upload_file_callback_data *data);
+int test_upload_file_data_callback(int buffer_size, char *buffer, void *callback_data);
+int main()
+{
+    // The following code shows how to upload parts using upload_part:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Name of the object to be uploaded in multiparts
+    char *key = "example_multi_part_upload_object_key";
+    // Multipart upload ID
+    char* uploadID = "00000194178F94B64016E9C3BD03E89B";
+    // Define the part size as 5 MB.
+    uint64_t uploadSliceSize = 5L * 1024 * 1024; 
+    // Name of the file to be uploaded
+    char file_name[256] = "./example_local_file_to_upload.tar";
+    // Define and initialize the size of the parts to be uploaded.
+    uint64_t uploadSize = uploadSliceSize; 
+    // Define and initialize the length variable of the uploaded file.
+    uint64_t fileSize = 0;                                         
+    //Initialize put_properties.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    //Callback function
+    obs_upload_handler handler =
+    { 
+        {&response_properties_callback, &response_complete_callback},
+        &test_upload_file_data_callback
+    };   
+    //Initialize the callback data.
+    test_upload_file_callback_data data;
+    memset(&data, 0, sizeof(test_upload_file_callback_data));
+    // Because two parts need to be uploaded, the file size must be greater than the value of uploadSliceSize.
+    fileSize = get_file_info(file_name,&data);
+    if (fileSize == 0) {
+        // Failure to open the file
+        return -1;
+    }
+    data.part_size = uploadSize;
+    data.part_num = (fileSize % uploadSize == 0) ? (fileSize / uploadSize) : (fileSize / uploadSize +1);
+    obs_upload_part_info uploadPartInfo;
+    memset(&uploadPartInfo, 0, sizeof(obs_upload_part_info));
+    //Upload the first part.
+    uploadPartInfo.part_number = 1;
+    uploadPartInfo.upload_id = uploadID;
+    data.start_byte  = 0;
+    data.ret_status = OBS_STATUS_BUTT;
+    upload_part(&options,key,&uploadPartInfo,uploadSize,
+                                      &put_properties,0,&handler,&data);
+    if (data.infile != NULL) {
+        fclose(data.infile);
+        data.infile = NULL;
+    }
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("test upload part 1 successfully. \n");
+    }
+    else
+    {
+        printf("test upload part 1 failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    //Upload the second part.
+    uploadPartInfo.part_number = 2;
+    uploadPartInfo.upload_id = uploadID;
+    fileSize = get_file_info(file_name, &data);
+    uploadSize = fileSize - uploadSize;
+    data.part_size = uploadSize;
+    data.start_byte = uploadSliceSize;
+    data.ret_status = OBS_STATUS_BUTT;
+    upload_part(&options,key,&uploadPartInfo,uploadSize, &put_properties,0,&handler,&data);
+    if (data.infile != NULL) {
+        fclose(data.infile);
+        data.infile = NULL;
+    }
+    if (OBS_STATUS_OK == data.ret_status) {
+        printf("test upload part 2 successfully. \n");
+    }
+    else
+    {
+        printf("test upload part 2 failed(%s).\n", obs_get_status_name(data.ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+// The completion callback function. 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)
+{
+    if (callback_data) {
+        test_upload_file_callback_data *data =
+            (test_upload_file_callback_data *)callback_data;
+        data->ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+int test_upload_file_data_callback(int buffer_size, char *buffer, void *callback_data)
+{
+    test_upload_file_callback_data *data =
+        (test_upload_file_callback_data *)callback_data;
+    int ret = 0;
+    fseek(data->infile, data->start_byte, SEEK_SET);
+    int toRead = ((data->part_size > (unsigned)buffer_size) ?
+        (unsigned)buffer_size : data->part_size);
+    ret = fread(buffer, 1, toRead, data->infile);
+    data->start_byte += ret;
+    return ret;
+}
+uint64_t get_file_info(char *localfile, test_upload_file_callback_data *data)
+{
+    data->infile = 0;
+    uint64_t content_length = 0;
+    if (!content_length)
+    {
+        struct stat statbuf;
+        if (stat(localfile, &statbuf) == -1)
+        {
+            fprintf(stderr, "\nERROR: Failed to stat file %s: ",
+                localfile);
+            return 0;
+        }
+        content_length = statbuf.st_size;
+    }
+    if (!(data->infile = fopen(localfile, "rb")))
+    {
+        fprintf(stderr, "\nERROR: Failed to open input file %s: ",
+            localfile);
+        return 0;
+    }
+    return content_length;
+}
+
+
+
+
+
+
+
+
Parent topic: Multipart Upload APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1811.html b/docs/obs_3rd_party/c_sdk/obs_20_1811.html new file mode 100644 index 000000000..236c1a259 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1811.html @@ -0,0 +1,108 @@ + + +

Multipart Upload APIs

+

You can upload a large file using multipart upload. Multipart upload is applicable to many scenarios. Below are some examples.

+
  • A file to be uploaded is larger than 100 MB.
  • The network connection to the OBS server breaks often.
  • The size of a file to be uploaded is unknown.
+

A multipart upload consists of the following steps:

+
  1. Initiating a Multipart Upload
  2. Uploading a Part
  3. Assembling Parts or Aborting a Multipart Upload
+

Multipart upload is mainly used for large file upload or when the network connection is poor. This example uploads a large file in parts concurrently:

+
static void test_concurrent_upload_part(char *filename, char *key, uint64_t uploadSliceSize)
+{
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Create and initialize option.
+    obs_options option;
+    init_obs_options(&option);
+    option.bucket_options.host_name = "<your-endpoint>";
+    option.bucket_options.bucket_name = "<Your bucketname>";
+
+    //Read the AK/SK from environment variables.
+    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
+    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
+    char *concurrent_upload_id;
+    uint64_t uploadSize = uploadSliceSize;                             
+    uint64_t filesize =0;                                          
+    // Initialize the put_properties structure.
+    obs_put_properties put_properties;
+    init_put_properties(&put_properties);
+    // Large file information: file pointer, file size, number of parts determined by part size
+    test_upload_file_callback_data data;
+    memset(&data, 0, sizeof(test_upload_file_callback_data));
+    filesize = get_file_info(filename,&data);
+    data.noStatus = 1;
+    data.part_size = uploadSize;
+    data.part_num = (filesize % uploadSize == 0) ? (filesize / uploadSize) : (filesize / uploadSize +1);
+    // Initialize the callback function of the uploading part.
+    obs_response_handler Handler =
+    { 
+         &response_properties_callback, &response_complete_callback 
+    };
+    // Callback function for assembling parts
+    obs_complete_multi_part_upload_handler complete_multi_handler =
+    { 
+        {&response_properties_callback,
+         &response_complete_callback},
+        &CompleteMultipartUploadCallback
+    };
+    //Initiating the multipart upload returns uploadId: uploadIdReturn.
+    char uploadIdReturn[256] = {0};
+    int upload_id_return_size = 255;
+    initiate_multi_part_upload(&option,key,upload_id_return_size,uploadIdReturn, &putProperties,
+            0,&Handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("test init upload part return uploadIdReturn(%s). \n", uploadIdReturn);
+        strcpy(concurrent_upload_id,uploadIdReturn);
+    }
+    else
+    {
+        printf("test init upload part failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Concurrent upload
+    test_concurrent_upload_file_callback_data *concurrent_upload_file;
+    concurrent_upload_file =(test_concurrent_upload_file_callback_data *)malloc(
+                    sizeof(test_concurrent_upload_file_callback_data)*(data.part_num+1));
+    if(concurrent_upload_file == NULL)
+    {
+         printf("malloc test_concurrent_upload_file_callback_data failed!!!");
+         return ;
+    }
+    test_concurrent_upload_file_callback_data *concurrent_upload_file_complete =   
+                              concurrent_upload_file;
+    start_upload_threads(data, concurrent_upload_id,filesize, key, option, concurrent_upload_file_complete);
+    // Assemble parts.
+    obs_complete_upload_Info *upload_Info = (obs_complete_upload_Info *)malloc(
+                sizeof(obs_complete_upload_Info)*data.part_num);
+    for(i=0; i<data.part_num; i++)
+    {
+        upload_Info[i].part_number = concurrent_upload_file_complete[i].part_num;
+        upload_Info[i].etag = concurrent_upload_file_complete[i].etag;
+    }
+    complete_multi_part_upload(&option, key, uploadIdReturn, data.part_num,upload_Info,&putProperties,&complete_multi_handler,&ret_status);
+    if (ret_status == OBS_STATUS_OK) {
+        printf("test complete upload successfully. \n");
+    }
+    else
+    {
+        printf("test complete upload failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    if(concurrent_upload_file)
+    {
+        free(concurrent_upload_file);
+        concurrent_upload_file = NULL;
+    }
+    if(upload_Info)
+    {
+        free(upload_Info);
+        upload_Info = NULL;
+    }
+}
+

When uploading a large file in parts, you need to use the Offset and PartSize parameters to specify the start and end positions of each part in the file.

+
+

If the concurrency value is too great, timeout may occur due to network instability. In such case, you need to reduce that value.

+
+
+
+
+
Parent topic: Multipart Upload APIs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1812.html b/docs/obs_3rd_party/c_sdk/obs_20_1812.html new file mode 100644 index 000000000..167258ddc --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1812.html @@ -0,0 +1,26 @@ + + +

Multipart Upload APIs

+

+
+
+ +
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_20_1813.html b/docs/obs_3rd_party/c_sdk/obs_20_1813.html new file mode 100644 index 000000000..288393af3 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_20_1813.html @@ -0,0 +1,2786 @@ + + +

Batch Deleting Objects

+

Function

This API deletes objects in a batch from a specific bucket. Deleted objects cannot be restored.

+

In a batch deletion, OBS concurrently deletes the specified objects and returns the deletion result of each object.

+
+

Restrictions

  • To delete objects in a batch, you must be the bucket owner or have the required permission (obs:object:DeleteObject in IAM or DeleteObject in a bucket policy).
  • If versioning is not enabled for a bucket, deleted objects cannot be restored.
  • A maximum of 1,000 objects can be deleted at a time. If you send a request for deleting more than 1,000 objects, OBS returns an error message.
  • After concurrent tasks are assigned, if an internal error occurs during cyclic deletion of multiple objects, an object may be deleted in the index data but still exist in the metadata.
+
+

Method

void batch_delete_objects(const obs_options *options, obs_object_info *object_info,
+	obs_delete_object_info *delobj, 
+	obs_put_properties *put_properties, 
+	obs_delete_object_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

delobj

+

obs_delete_object_info*

+

Yes

+

Explanation:

+

Specifies the number of objects to be deleted and the quiet mode.

+

Restrictions:

+

None

+

put_properties

+

obs_put_properties*

+

No

+

Explanation:

+

Sets the verification properties of the object to be deleted.

+

Restrictions:

+

None

+

handler

+

obs_delete_object_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_delete_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

keys_number

+

unsigned int

+

Yes

+

Explanation:

+

Number of deleted object names.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

quiet

+

int

+

No

+

Explanation:

+

Specifies whether to use the quiet mode.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_delete_object_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

delete_object_data_callback

+

obs_delete_object_data_callback *

+

Yes

+

Explanation:

+

The pointer to the callback function, where the callback parameters can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 20 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Value of the Expires header in the OBS request. It specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 24 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 25 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 26 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 27 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 28 obs_delete_object_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

contents_count

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

contents

+

obs_delete_objects *

+

Yes

+

Explanation:

+

Buffer for storing the data to be uploaded. The data to be uploaded is copied to this buffer.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 29 obs_delete_objects

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

constchar*

+

Yes

+

Explanation:

+

Each object name in the deletion result. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

code

+

constchar*

+

No

+

Explanation:

+

Error code of a deletion failure.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

message

+

constchar*

+

No

+

Explanation:

+

Error message of a deletion failure.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

delete_marker

+

constchar*

+

No

+

Explanation:

+

OBS returns true for this parameter in the response when a delete marker is created or deleted for a versioning-enabled bucket.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

delete_marker_version_id

+

constchar*

+

No

+

Explanation:

+

Version ID of a delete marker to create or delete.

+

OBS returns this element in the response when a delete marker is created or deleted for a versioning-enabled bucket. This element will be returned in either of the following cases:

+
  • You send a delete request specifying an object's name without providing a version ID. In this case, OBS creates a delete marker and returns its version ID in the response.
  • You send a delete request specifying both an object's name and its version ID, but this version ID points to a delete marker. In this case, OBS deletes the delete marker and returns its version ID in the response.
+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples: Batch Deleting Objects

This example calls batch_delete_objects to delete multiple objects.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+obs_status delete_objects_data_callback(int contentsCount,
+    obs_delete_objects *delobjs,
+    void *callbackData);
+int main()
+{
+    // The following code shows how to use batch_delete_objects to delete multiple objects:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Information about the objects to be deleted in a batch.
+    obs_object_info objectinfo[100];
+    objectinfo[0].key = "example_get_file_test_delete1";
+    objectinfo[0].version_id = NULL;
+    objectinfo[1].key = "example_get_file_test_delete2";
+    objectinfo[1].version_id = "versionid2";
+    obs_delete_object_info delobj;
+    memset(&delobj, 0, sizeof(obs_delete_object_info));
+    delobj.keys_number = 2;
+    // Set the response callback function.
+    obs_delete_object_handler handler =
+    {
+        {&response_properties_callback, &response_complete_callback},
+        &delete_objects_data_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Delete the objects in a batch.
+    batch_delete_objects(&options, objectinfo, &delobj, 0, &handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("test batch_delete_objects successfully. \n");
+    }
+    else
+    {
+        printf("test batch_delete_objects failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+obs_status delete_objects_data_callback(int contentsCount,
+    obs_delete_objects *delobjs,
+    void *callbackData)
+{
+    int i;
+    for (i = 0; i < contentsCount; i++) {
+        const obs_delete_objects*content = &(delobjs[i]);
+        printf("delete object result:\nobject key:%s\nerror code:%s\nerror message:%s\ndelete marker:%s\ndelete marker version_id:%s\n",
+                content->key, content->code, content->message, content->delete_marker, content->delete_marker_version_id);
+    }
+    return OBS_STATUS_OK;
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Object Management
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_23_1712.html b/docs/obs_3rd_party/c_sdk/obs_23_1712.html new file mode 100644 index 000000000..ee702ae18 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_23_1712.html @@ -0,0 +1,14 @@ + + +

How Do I Get My Account ID and User ID?

+

Obtaining the Account ID and User ID

When calling APIs, you may need to specify the account ID (DomainID) and user ID (UserID) in some requests. You need to obtain them from the console in advance. To obtain them from the console, do as follows:

+
  1. Log in to the management console.
  2. Hover the mouse pointer over the username and choose My Credentials from the drop-down list.

    On the My Credentials page, view the account ID and user ID.

    +

+
+
+
+
+
Parent topic: FAQs
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/obs_23_1713.html b/docs/obs_3rd_party/c_sdk/obs_23_1713.html new file mode 100644 index 000000000..e41b23050 --- /dev/null +++ b/docs/obs_3rd_party/c_sdk/obs_23_1713.html @@ -0,0 +1,2782 @@ + + +

Batch Deleting Object Versions

+

Function

This API deletes object versions in a batch in the specified bucket to save space and costs.

+
+

Restrictions

  • To delete object versions, you must be the bucket owner or have the required permission (obs:object:DeleteObject in IAM or DeleteObject in a bucket policy).
  • If versioning is not enabled for a bucket, deleted object versions cannot be restored.
+
+

Method

void batch_delete_objects(const obs_options *options, obs_object_info *object_info,obs_delete_object_info *delobj,     
+                                  obs_put_properties *put_properties, obs_delete_object_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:

+

The context of the requested bucket. Refer to Configuring option to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

+

Restrictions:

+

None

+

object_info

+

obs_object_info *

+

Yes

+

Explanation:

+

Object name and version ID.

+

Restrictions:

+

For a non-versioned object, set the version ID to 0.

+

delobj

+

obs_delete_object_info*

+

Yes

+

Explanation:

+

Specifies the number of objects to be deleted and the quiet mode.

+

Restrictions:

+

None

+

put_properties

+

obs_put_properties*

+

No

+

Explanation:

+

Sets the verification properties of the object to be deleted.

+

Restrictions:

+

None

+

handler

+

obs_delete_object_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 your custom callback_data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

No

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 2 obs_options

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

bucket_options

+

obs_bucket_context

+

Yes

+

Explanation:

+

Bucket settings.

+

Restrictions:

+

None

+

request_options

+

obs_http_request_option

+

Yes

+

Explanation:

+

Request-related settings.

+

Restrictions:

+

None

+

temp_auth

+

temp_auth_configure*

+

No

+

Explanation:

+

The structure used to calculate a temporary signature. Set it to NULL if it is not used.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3 obs_bucket_context

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

host_name

+

char *

+

Yes

+

Explanation:

+

The requested host name, used as an address for connecting to OBS. It is the domain name (the endpoint) of the server where the requested resource is stored.

+

+

+

+

Restrictions:

+

The value does not need to contain http:// or https:// as a prefix, which is controlled using obs_protocol.

+

Default value:

+

None

+

bucket_name

+

char *

+

Yes

+

Explanation:

+

Bucket name.

+

Restrictions:

+
  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
    +
  • If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.
+

Value range:

+

None

+

Default value:

+

None

+

useCname

+

bool

+

No

+

Explanation:

+

Whether to use a custom domain name to access OBS.

+

Restrictions:

+

None

+

Value range:

+

true: A custom domain name is used.

+

false: A custom domain name is not used.

+

Default value:

+

false

+

protocol

+

obs_protocol

+

No

+

Explanation:

+

Whether to use the HTTP or HTTPS protocol.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_protocol.

+

Default value:

+

OBS_PROTOCOL_HTTPS (HTTPS is used by default.)

+

access_key

+

char *

+

Yes

+

Explanation:

+

Access key ID (AK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

secret_access_key

+

char *

+

Yes

+

Explanation:

+

Secret access key (SK).

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

storage_class

+

obs_storage_class

+

No

+

Explanation:

+

Bucket storage class that can be specified at bucket creation.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_storage_class.

+

Default value:

+

OBS_STORAGE_CLASS_STANDARD (Standard storage class)

+

token

+

char *

+

No

+

Explanation:

+

The security token in temporary credentials.

+

Restrictions:

+

None

+

Value range:

+

For details, see Creating Access Keys.

+

Default value:

+

None

+

epid

+

char *

+

No

+

Explanation:

+

Enterprise project ID that can be specified during bucket creation. If you have enabled EPS, you can obtain the project ID from the EPS console.

+

Restrictions:

+

The value needs to be represented as a UUID. This parameter is not required if EPS is not enabled.

+

Example: 9892d768-2d13-450f-aac7-ed0e44c2585f

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 4 obs_storage_class

Value

+

Description

+

OBS_STORAGE_CLASS_STANDARD

+

Standard storage class.

+

This class features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

+

OBS_STORAGE_CLASS_STANDARD_IA

+

Warm storage class.

+

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

+

OBS_STORAGE_CLASS_GLACIER

+

Cold storage class.

+

Used for storing rarely accessed (once a year) data.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5 obs_http_request_option

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

connect_time

+

int

+

Yes

+

Explanation:

+

Timeout period for establishing an HTTP/HTTPS connection, in ms.

+

Restrictions:

+

None

+

Value range:

+

[10000, 60000]

+

Default value:

+

60000

+

max_connected_time

+

int

+

Yes

+

Explanation:

+

Timeout period (in seconds) of a request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

0 (There is never automatic disconnection.)

+

proxy_auth

+

char*

+

No

+

Explanation:

+

Proxy authentication information, in the format username:password

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

proxy_host

+

char*

+

No

+

Explanation:

+

IP address or host name of the proxy server.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + +
Table 6 obs_protocol

Value

+

Description

+

OBS_PROTOCOL_HTTPS

+

HTTPS is used for access.

+

OBS_PROTOCOL_HTTP

+

HTTP is used for access.

+
+
+ +
+ + + + + + + +
Table 7 obs_bucket_type

Value

+

Description

+

OBS_BUCKET_OBJECT

+

Object bucket

+
+
+ +
+ + + + + + + + + + +
Table 8 obs_bucket_list_type

Value

+

Description

+

OBS_BUCKET_LIST_ALL

+

Lists all buckets.

+

OBS_BUCKET_LIST_OBJECT

+

Lists all object buckets.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 9 temp_auth_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

expires

+

long long int

+

Yes

+

Explanation:

+

Validity period of the temporary credentials, in seconds.

+

Restrictions:

+

None

+

Value range:

+

[0-630720000]

+

Default value:

+

None

+

temp_auth_callback

+

void(*temp_auth_callback)(char *temp_auth_url,

+

uint64_t temp_auth_url_len,

+

char*temp_auth_headers,

+

uint64_t temp_auth_headers_len,

+

void*callback_data)

+

Yes

+

Explanation:

+

The pointer to the custom callback function, which is used to record the temporary URL and involved signature header to the custom callback data.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10 temp_auth_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

temp_auth_url

+

char *

+

Yes

+

Explanation:

+

Temporary URL. OBS allows you to construct a URL for a specific operation. In such a URL, you use Query parameters to provide authentication information including the user AK, signature, and validity period. Anyone who has the URL can perform the specified operation. After receiving a request made using such a URL, OBS treats the requester as the user who issued the URL and processes the request. For example, if you construct a pre-signed URL for downloading an object and provide it to various users, they can use the URL to download the object without authentication, but they must do so within the validity period specified by the Expires parameter.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_url_len

+

uint64_t

+

Yes

+

Explanation:

+

Length of the temporary URL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers

+

char *

+

Yes

+

Explanation:

+

Headers for temporary authentication.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

temp_auth_headers_len

+

uint64_t

+

Yes

+

Explanation:

+

Number of temporary authentication headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

Custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 11 obs_delete_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

keys_number

+

unsigned int

+

Yes

+

Explanation:

+

Number of deleted object names.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

quiet

+

int

+

No

+

Explanation:

+

Specifies whether to use the quiet mode.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 12 obs_delete_object_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

response_handler

+

obs_response_handler *

+

Yes

+

Explanation:

+

Response callback function structure.

+

Restrictions:

+

None

+

delete_object_data_callback

+

obs_delete_object_data_callback *

+

Yes

+

Explanation:

+

The pointer to the callback function, where the callback parameters can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 13 obs_response_handler

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties_callback

+

obs_response_properties_callback *

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

complete_callback

+

obs_response_complete_callback *

+

Yes

+

Explanation:

+

The pointer to the completion callback function. The content of obs_status and obs_error_details in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 14 obs_response_properties_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

properties

+

const obs_response_properties*

+

Yes

+

Explanation:

+

Parameters in the response headers. You are advised to record them to callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 15 obs_response_complete_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

status

+

obs_status

+

Yes

+

Explanation:

+

Internal request status code of the SDK.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_status.

+

error_details

+

const obs_error_details*

+

Yes

+

Explanation:

+

The pointer to the response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16 obs_response_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

request_id

+

const char *

+

No

+

Explanation:

+

The value created by OBS to uniquely identify the request. OBS uses this value to locate the fault.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

request_id2

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_type

+

const char *

+

No

+

Explanation:

+

MIME type of the object. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

content_length

+

uint64_t

+

No

+

Explanation:

+

The size (in bytes) of the response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

server

+

const char *

+

No

+

Explanation:

+

Server header in an HTTP request.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

etag

+

const char *

+

No

+

Explanation:

+

Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag.

+

Restrictions:

+

If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

expiration

+

const char *

+

No

+

Explanation:

+

Expiration details of the object.

+

Restrictions:

+

None

+

Value range:

+

An integer greater than 0, in days.

+

Default value:

+

None

+

website_redirect_location

+

const char *

+

No

+

Explanation:

+

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

+

Restrictions:

+
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.
  • OBS only supports redirection of objects that are in the root directory.
+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

const char *

+

No

+

Explanation:

+

Object version ID.

+

Restrictions:

+

If the object has no version ID, the value is NULL.

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

const obs_name_value *

+

No

+

Explanation:

+

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+

None

+

use_server_side_encryption

+

char

+

No

+

Explanation:

+

If server-side encryption is enabled, this parameter is set to '\1'.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

allow_origin

+

const char *

+

No

+

Explanation:

+

Returned if the request origin meets the CORS configured on the server.

+

Restrictions:

+

None

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

allow_headers

+

const char *

+

No

+

Explanation:

+

Returned if the request headers meet the CORS configured on the server.

+

Restrictions:

+

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

The value that complies with the CORS

+

Default value:

+

None

+

max_age

+

const char *

+

No

+

Explanation:

+

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

+

Restrictions:

+

Each CORS rule can contain at most one MaxAgeSeconds.

+

Value range:

+

An integer greater than or equal to 0, in seconds.

+

Default value:

+

3000

+

allow_methods

+

const char *

+

No

+

Explanation:

+

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

+

Restrictions:

+

None

+

Value range:

+
  • GET
  • PUT
  • HEAD
  • POST
  • DELETE
+

Value range:

+

None

+

expose_headers

+

const char *

+

No

+

Explanation:

+

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule. These headers provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

+

Restrictions:

+

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

+

Value range:

+

None

+

Default value:

+

None

+

storage_class

+

const char *

+

No

+

Explanation:

+

Object storage class.

+

Restrictions:

+

This header is returned only when the storage class of an object is not Standard.

+

Value range:

+
  • WARM (Warm storage class)
  • COLD (Cold storage class)
+

Default value:

+

None

+

server_side_encryption

+

const char *

+

No

+

Explanation:

+

The encryption method used by the server.

+

Example: x-obs-server-side-encryption:kms

+

Restrictions:

+

This header is included in a response if SSE-KMS is used.

+

Value range:

+
  • kms (SSE-KMS encryption)
+

Default value:

+

None

+

kms_key_id

+

const char *

+

No

+

Explanation:

+

Key ID. If the SSE-KMS encryption is used with a specified key, the key ID is required.

+

Restrictions:

+

This header can only be used when you specify kms for the server_side_encryption header.

+

Value range:

+

None

+

Default value:

+

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

+

customer_algorithm

+

const char *

+

No

+

Explanation:

+

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

+

Restrictions:

+

None

+

Value range:

+

AES256 (AES256 decryption algorithm)

+

Default value:

+

None

+

customer_key_md5

+

const char *

+

No

+

Explanation:

+

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

+

Restrictions:

+

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

+

Value range:

+

Base64-encoded MD5 value of the key ID.

+

Default value:

+

None

+

bucket_location

+

const char *

+

No

+

Explanation:

+

Indicates the region where the bucket resides.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_version

+

const char *

+

No

+

Explanation:

+

OBS version of the bucket.

+

Restrictions:

+

None

+

Value range:

+
  • 3.0: bucket of the latest version
  • --: bucket of an earlier version
+

Default value:

+

None

+

restore

+

const char *

+

No

+

Explanation:

+

Restoration status of an object.

+

Examples: ongoing-request="true" (the object is being restored); ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" (the object has been restored) expiry-date indicates when the restored object will expire.

+

Restrictions:

+

For a Cold object that is being restored or has been restored, this header is returned.

+

Value range:

+

None

+

Default value:

+

None

+

obs_object_type

+

const char *

+

No

+

Explanation:

+

Type of the object.

+

Restrictions:

+

This header is returned only when the object is not a Normal object.

+

Value range:

+

Appendable

+

Default value:

+

None

+

obs_next_append_position

+

const char *

+

No

+

Explanation:

+

Indicates the position to be provided for the next request.

+

Restrictions:

+

This header is returned only when the object is an Appendable object.

+

Value range:

+

None

+

Default value:

+

None

+

obs_head_epid

+

const char *

+

No

+

Explanation:

+

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

+

Restrictions:

+

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

+

Value range:

+

None

+

Default value:

+

None

+

reserved_indicator

+

const char *

+

No

+

Explanation:

+

A special symbol that helps troubleshoot.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 17 obs_error_details

Parameter

+

Type

+

Description

+

message

+

const char*

+

Explanation:

+

Error details in the XML error response body.

+

Restrictions:

+

None

+

Default value:

+

None

+

resource

+

const char*

+

Explanation:

+

Bucket or object related to the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

further_details

+

const char*

+

Explanation:

+

The value of the FurtherDetails element in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details_count

+

int

+

Explanation:

+

The number of other elements in the XML error response body.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

extra_details

+

obs_name_value*

+

Explanation:

+

Values of other elements in the XML error response body.

+

Restrictions:

+

None

+

error_headers_count

+

int

+

Explanation:

+

Number of headers in error_headers.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

error_headers

+

char**

+

Explanation:

+

All response headers that contain the error.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 18 obs_name_value

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

name

+

char *

+

No

+

Explanation:

+

Key of a property.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

value

+

char *

+

No

+

Explanation:

+

Property value.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19 obs_status

Value

+

Description

+

OBS_STATUS_OK

+

The request is successful.

+

OBS_STATUS_InitCurlFailed

+

Failed to initialize curl.

+

OBS_STATUS_InternalError

+

Internal error.

+

OBS_STATUS_OutOfMemory

+

The local memory is insufficient.

+

OBS_STATUS_FailedToIInitializeRequest

+

Failed to initialize the request.

+

OBS_STATUS_ConnectionFailed

+

Network connection failed.

+

OBS_STATUS_XmlParseFailure

+

Failed to parse the XML file.

+

OBS_STATUS_NameLookupError

+

Domain name resolution failed.

+

OBS_STATUS_FailedToConnect

+

Failed to connect to the server.

+

OBS_STATUS_PartialFile

+

Network transmission.

+

OBS_STATUS_InvalidParameter

+

Invalid parameter.

+

OBS_STATUS_NoToken

+

The current number of concurrent tasks exceeds the maximum number (1000 by default). Use the set_online_request_max_count function to adjust the maximum number of concurrent tasks.

+

OBS_STATUS_OpenFileFailed

+

Failed to open the file.

+

OBS_STATUS_AccessDenied

+

The request is rejected.

+

OBS_STATUS_MalformedPolicy

+

The format of the request policy is incorrect.

+

OBS_STATUS_MalformedXML

+

The XML request format is incorrect.

+

OBS_STATUS_MethodNotAllowed

+

The request method is not allowed.

+

OBS_STATUS_SignatureDoesNotMatch

+

The signatures do not match. Check whether the AK, SK, and token are correct.

+

OBS_STATUS_ServiceUnavailable

+

Server exception.

+

OBS_STATUS_SlowDown

+

The request frequency is too high.

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 20 obs_object_info

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

char *

+

Yes

+

Explanation:

+

Object name

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

version_id

+

char *

+

No

+

Explanation:

+

Object version ID. If the object is not a versioned object, set version_id to NULL.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21 obs_put_properties

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

content_type

+

char *

+

Yes

+

Explanation:

+

It specifies the file type of an object when it is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Type values defined in HTTP.

+

Default value:

+

None

+

md5

+

char *

+

Yes

+

Explanation:

+

Indicates the base64-encoded digest of the object data. It is provided for the OBS server to verify data integrity. The OBS server will compare this MD5 value with the MD5 value calculated based on the object data. If the two values are not the same, HTTP status code 400 is returned.

+

Restrictions:

+

The MD5 value of the object must be Base64 encoded. If the MD5 value is not specified, the OBS server will not verify the MD5 value of the object.

+

Value range:

+

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

+

Example: n58IG6hfM7vqI4K0vnWpog==

+

Default value:

+

None

+

cache_control

+

char *

+

Yes

+

Explanation:

+

It specifies the cache behavior of the web page when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Cache-Control values defined in HTTP.

+

Default value:

+

None

+

content_disposition_filename

+

char *

+

Yes

+

Explanation:

+

It specifies the name of an object when it is downloaded. For example, if the value is set to test.txt, that is equivalent to adding the Content-Disposition: attachment; filename=test.txt header.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Disposition values defined in HTTP.

+

Default value:

+

None

+

content_encoding

+

char *

+

Yes

+

Explanation:

+

It specifies the content encoding format when an object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

See the Content-Encoding values defined in HTTP.

+

Default value:

+

None

+

website_redirect_location

+

char *

+

Yes

+

Explanation:

+

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

+

To another object in the same bucket:

+

x-obs-website-redirect-location:/anotherPage.html

+

To an external URL:

+

x-obs-website-redirect-location:http://www.example.com/

+

Restrictions:

+

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

+

Value range:

+

None

+

Default value:

+

None

+

get_conditions

+

obs_get_conditions *

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Where the copy starts in the object

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (The copy starts from the first byte of the object.)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the copy length.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

upload_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

expires

+

int64_t

+

No

+

Explanation:

+

Value of the Expires header in the OBS request. It specifies the cache expiration time of the web page when the object is downloaded.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

obs_expires

+

int64_t

+

No

+

Explanation:

+

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

+

Restrictions:

+

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

+

Value range:

+

The value is an integer greater than 0.

+

Default value:

+

None

+

canned_acl

+

obs_canned_acl

+

No

+

Explanation:

+

Access control policy

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_canned_acl.

+

az_redundancy

+

obs_az_redundancy

+

No

+

Explanation:

+

Specifies a series of parameters for copying an object.

+

Restrictions:

+

None

+

Value range:

+

For details, see obs_az_redundancy.

+

meta_data_count

+

int

+

No

+

Explanation:

+

Number of elements in the meta_data array.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

meta_data

+

obs_name_value*

+

No

+

Explanation:

+

Custom metadata of the object. OBS allows you to use custom metadata to manage objects. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

+

Restrictions:

+
  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.
+

metadata_action

+

metadata_action_indicator

+

No

+

Explanation:

+

Metadata operation directive.

+

Restrictions:

+

None

+

Value range:

+

For details, see metadata_action_indicator.

+

server_callback

+

obs_upload_file_server_callback

+

No

+

Explanation:

+

Parameters related to server callback.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
Table 22 obs_canned_acl

Value

+

Description

+

OBS_CANNED_ACL_PRIVATE

+

Private read and write. A bucket or object can only be accessed by its owner.

+

OBS_CANNED_ACL_PUBLIC_READ

+

Public read and private write. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE

+

Public read and write. If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, metadata of the bucket; upload objects; delete objects; initialize multipart uploads; upload parts; combine parts; copy parts; and abort multipart uploads.

+

If this permission is set for an object, everyone can obtain the content and metadata of the object.

+

OBS_CANNED_ACL_PUBLIC_READ_DELIVERED

+

Public read on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, and bucket metadata, and can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED

+

Public read and write on a bucket and its objects. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of the objects in the bucket.

+

This permission cannot be granted on objects.

+

OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL

+

If this permission is granted on an object, only the bucket and object owners have the full control over the object.

+

By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this permission to the bucket owner, the bucket owner can have full control over your object.

+

For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets bucket-owner-full-control for object x, user B then has the control over object x.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 23 obs_get_conditions

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

start_byte

+

uint64_t

+

No

+

Explanation:

+

Start position for object download.

+

Restrictions:

+

None

+

Value range:

+

0 (included) to the object length minus 1 (not included), in bytes

+

Default value:

+

0 (indicating that the download starts from the first byte of the object)

+

byte_count

+

uint64_t

+

No

+

Explanation:

+

Specifies the length to be downloaded.

+

Restrictions:

+
  • Value: an integer greater than 0
  • If the sum of start_byte and byte_count is greater than the object length minus 1, the object length minus 1 is used. The unit is byte.
+

Value range:

+

None

+

Default value:

+

None

+

download_limit

+

uint64_t

+

No

+

Explanation:

+

Bandwidth limit for single connection requests.

+

Restrictions:

+

None

+

Value range:

+

819200 to 838860800, in bit/s

+

Default value:

+

None

+

if_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_not_modified_since

+

int64_t

+

No

+

Explanation:

+

The request succeeds if the object has not been modified since the specified time; otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

if_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is the same as the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

if_not_match_etag

+

char *

+

No

+

Explanation:

+

Preset ETag. If the ETag of the object to be downloaded or copied is different from the preset ETag, the request succeeds. Otherwise, an error is returned.

+

Restrictions:

+

None

+

Value range:

+

The value must contain 32 characters.

+

Default value:

+

None

+

image_process_config

+

image_process_configure *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 24 metadata_action_indicator

Value

+

Description

+

OBS_NO_METADATA_ACTION

+

Default invalid value.

+

OBS_REPLACE

+

Uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.

+

OBS_REPLACE_NEW

+

The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 25 obs_upload_file_server_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

callback_url

+

char *

+

Yes

+

Explanation:

+

After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method.

+

You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs.

+

URL-encoding is required.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_host

+

char *

+

No

+

Explanation:

+

Value of the host header in the callback request. If this parameter is not specified, the value of host parsed from the callbackUrl parameter is used.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body

+

char *

+

Yes

+

Explanation:

+

Body of the callback request. The body format must comply with the media type specified in the callbackBodyType field.

+

The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

callback_body_type

+

char *

+

No

+

Explanation:

+

Value of the Content-Type header in the callback request. application/x-www-form-urlencoded and application/json are supported. If this parameter is not specified, the default value is as follows:

+

application/json

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + +
Table 26 image_process_configure

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

image_process_mode

+

image_process_mode_type

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

For details, see image_process_mode_type.

+

cmds_stylename

+

char *

+

No

+

Explanation:

+

Image processing parameters.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + +
Table 27 image_process_mode_type

Value

+

Description

+

obs_image_process_invalid_mode

+

Default invalid value.

+

obs_image_process_cmd

+

Image processing parameters start with image.

+

obs_image_process_style

+

Image processing parameters start with style.

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
Table 28 obs_delete_object_data_callback

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

contents_count

+

int

+

Yes

+

Explanation:

+

Length of the buffer.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

contents

+

obs_delete_objects *

+

Yes

+

Explanation:

+

Buffer for storing the data to be uploaded. The data to be uploaded is copied to this buffer.

+

Restrictions:

+

None

+

callback_data

+

void *

+

Yes

+

Explanation:

+

The pointer to the custom callback data.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 29 obs_delete_objects

Parameter

+

Type

+

Mandatory (Yes/No)

+

Description

+

key

+

constchar*

+

Yes

+

Explanation:

+

Each object name in the deletion result. An object name is a complete path that does not contain the bucket name.

+

Restrictions:

+

The name of each object in a bucket must be unique.

+

Value range:

+

The value can contain 1 to 1,024 characters.

+

Default value:

+

None

+

code

+

constchar*

+

No

+

Explanation:

+

Error code of a deletion failure.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

message

+

constchar*

+

No

+

Explanation:

+

Error message of a deletion failure.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

delete_marker

+

constchar*

+

No

+

Explanation:

+

OBS returns true for this parameter in the response when a delete marker is created or deleted for a versioning-enabled bucket.

+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+

delete_marker_version_id

+

constchar*

+

No

+

Explanation:

+

Version ID of a delete marker to create or delete.

+

OBS returns this element in the response when a delete marker is created or deleted for a versioning-enabled bucket. This element will be returned in either of the following cases:

+
  • You send a delete request specifying an object's name without providing a version ID. In this case, OBS creates a delete marker and returns its version ID in the response.
  • You send a delete request specifying both an object's name and its version ID, but this version ID points to a delete marker. In this case, OBS deletes the delete marker and returns its version ID in the response.
+

Restrictions:

+

None

+

Value range:

+

None

+

Default value:

+

None

+
+
+
+

Code Examples

This example deletes multiple versions of an object using batch_delete_objects.
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
#include "eSDKOBS.h"
+#include <stdio.h>
+#include <sys/stat.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);
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data);
+obs_status delete_objects_data_callback(int contentsCount,
+    obs_delete_objects *delobjs,
+    void *callbackData);
+int main()
+{
+    // The following code shows how to delete multiple versions of an object using batch_delete_objects:
+    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
+    obs_initialize(OBS_INIT_ALL); 
+    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);
+    // For host_name, enter the endpoint of the region where the bucket is located.
+    options.bucket_options.host_name = "your-endpoint";
+    // 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;
+    // Information about the object versions to be deleted in a batch.
+    obs_object_info objectinfo[100];
+    objectinfo[0].key = "example_get_file_test_delete1";
+    objectinfo[0].version_id = "G00111934EAA2CE900004016129AC991";
+    objectinfo[1].key = "example_get_file_test_delete2";
+    objectinfo[1].version_id = "G00111934EAA2CE900004016129AC992";
+    obs_delete_object_info delobj;
+    memset(&delobj, 0, sizeof(obs_delete_object_info));
+    delobj.keys_number = 2;
+    // Set the response callback function.
+    obs_delete_object_handler handler =
+    {
+        {&response_properties_callback, &response_complete_callback},
+        &delete_objects_data_callback
+    };
+    obs_status ret_status = OBS_STATUS_BUTT;
+    // Delete object versions in a batch.
+    batch_delete_objects(&options, objectinfo, &delobj, 0, &handler, &ret_status);
+    if (OBS_STATUS_OK == ret_status) {
+        printf("test batch_delete_objects successfully. \n");
+    }
+    else
+    {
+        printf("test batch_delete_objects failed(%s).\n", obs_get_status_name(ret_status));
+    }
+    // Release the allocated global resources.
+    obs_deinitialize();
+}
+obs_status delete_objects_data_callback(int contentsCount,
+    obs_delete_objects *delobjs,
+    void *callbackData)
+{
+    int i;
+    for (i = 0; i < contentsCount; i++) {
+        const obs_delete_objects*content = &(delobjs[i]);
+        printf("delete object result:\nobject key:%s\nerror code:%s\nerror message:%s\ndelete marker:%s\ndelete marker version_id:%s\n",
+                content->key, content->code, content->message, content->delete_marker, content->delete_marker_version_id);
+    }
+    return OBS_STATUS_OK;
+}
+// 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)
+{
+    if (properties == NULL)
+    {
+        printf("error! obs_response_properties is null!");
+        if (callback_data != NULL)
+        {
+            obs_sever_callback_data *data = (obs_sever_callback_data *)callback_data;
+            printf("server_callback buf is %s, len is %llu",
+                data->buffer, data->buffer_len);
+            return OBS_STATUS_OK;
+        }
+        else {
+            printf("error! obs_sever_callback_data is null!");
+            return OBS_STATUS_OK;
+        }
+    }
+    // Print the response.
+#define print_nonnull(name, field)                                 \
+    do {                                                           \
+        if (properties-> field) {                                  \
+            printf("%s: %s\n", name, properties->field);          \
+        }                                                          \
+    } while (0)
+    print_nonnull("request_id", request_id);
+    print_nonnull("request_id2", request_id2);
+    print_nonnull("content_type", content_type);
+    if (properties->content_length) {
+        printf("content_length: %llu\n", properties->content_length);
+    }
+    print_nonnull("server", server);
+    print_nonnull("ETag", etag);
+    print_nonnull("expiration", expiration);
+    print_nonnull("website_redirect_location", website_redirect_location);
+    print_nonnull("version_id", version_id);
+    print_nonnull("allow_origin", allow_origin);
+    print_nonnull("allow_headers", allow_headers);
+    print_nonnull("max_age", max_age);
+    print_nonnull("allow_methods", allow_methods);
+    print_nonnull("expose_headers", expose_headers);
+    print_nonnull("storage_class", storage_class);
+    print_nonnull("server_side_encryption", server_side_encryption);
+    print_nonnull("kms_key_id", kms_key_id);
+    print_nonnull("customer_algorithm", customer_algorithm);
+    print_nonnull("customer_key_md5", customer_key_md5);
+    print_nonnull("bucket_location", bucket_location);
+    print_nonnull("obs_version", obs_version);
+    print_nonnull("restore", restore);
+    print_nonnull("obs_object_type", obs_object_type);
+    print_nonnull("obs_next_append_position", obs_next_append_position);
+    print_nonnull("obs_head_epid", obs_head_epid);
+    print_nonnull("reserved_indicator", reserved_indicator);
+    int i;
+    for (i = 0; i < properties->meta_data_count; i++) {
+        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
+            properties->meta_data[i].value);
+    }
+    return OBS_STATUS_OK;
+}
+void print_error_details(const obs_error_details *error) {
+    if (error && error->message) {
+        printf("Error Message: \n   %s\n", error->message);
+    }
+    if (error && error->resource) {
+        printf("Error Resource: \n  %s\n", error->resource);
+    }
+    if (error && error->further_details) {
+        printf("Error further_details: \n   %s\n", error->further_details);
+    }
+    if (error && error->extra_details_count) {
+        int i;
+        for (i = 0; i < error->extra_details_count; i++) {
+            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
+                error->extra_details[i].value);
+        }
+    }
+    if (error && error->error_headers_count) {
+        int i;
+        for (i = 0; i < error->error_headers_count; i++) {
+            const char *errorHeader = error->error_headers[i];
+            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
+        }
+    }
+}
+void response_complete_callback(obs_status status,
+    const obs_error_details *error,
+    void *callback_data)
+{
+    if (callback_data)
+    {
+        obs_status *ret_status = (obs_status *)callback_data;
+        *ret_status = status;
+    }
+    else {
+        printf("Callback_data is NULL");
+    }
+    print_error_details(error);
+}
+
+
+
+
+
+
+
+
Parent topic: Versioning
+
+
+ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/caution_3.0-en-us.png b/docs/obs_3rd_party/c_sdk/public_sys-resources/caution_3.0-en-us.png new file mode 100644 index 000000000..60f607621 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/caution_3.0-en-us.png differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/danger_3.0-en-us.png b/docs/obs_3rd_party/c_sdk/public_sys-resources/danger_3.0-en-us.png new file mode 100644 index 000000000..47a9c7235 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/danger_3.0-en-us.png differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/delta.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/delta.gif new file mode 100644 index 000000000..0d1b1f674 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/delta.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/deltaend.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/deltaend.gif new file mode 100644 index 000000000..cc7da0fc8 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/deltaend.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-arrowdn.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-arrowdn.gif new file mode 100644 index 000000000..379428032 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-arrowdn.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-arrowrt.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-arrowrt.gif new file mode 100644 index 000000000..6aaaa11c2 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-arrowrt.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-caution.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-caution.gif new file mode 100644 index 000000000..079c79b26 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-caution.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-danger.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-danger.gif new file mode 100644 index 000000000..079c79b26 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-danger.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-huawei.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-huawei.gif new file mode 100644 index 000000000..a31d60f89 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-huawei.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-note.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-note.gif new file mode 100644 index 000000000..31be2b039 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-note.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-notice.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-notice.gif new file mode 100644 index 000000000..409070650 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-notice.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-tip.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-tip.gif new file mode 100644 index 000000000..c47bae05c Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-tip.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-warning.gif b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-warning.gif new file mode 100644 index 000000000..079c79b26 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/icon-warning.gif differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/note_3.0-en-us.png b/docs/obs_3rd_party/c_sdk/public_sys-resources/note_3.0-en-us.png new file mode 100644 index 000000000..57a0e1f53 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/note_3.0-en-us.png differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/notice_3.0-en-us.png b/docs/obs_3rd_party/c_sdk/public_sys-resources/notice_3.0-en-us.png new file mode 100644 index 000000000..fa4b64990 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/notice_3.0-en-us.png differ diff --git a/docs/obs_3rd_party/c_sdk/public_sys-resources/warning_3.0-en-us.png b/docs/obs_3rd_party/c_sdk/public_sys-resources/warning_3.0-en-us.png new file mode 100644 index 000000000..def5c3565 Binary files /dev/null and b/docs/obs_3rd_party/c_sdk/public_sys-resources/warning_3.0-en-us.png differ