Uploading an Object - Text-Based (SDK for C)

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

Function

This API is used to upload text content directly to a specified OBS bucket as an object. Text-based upload is a simplified encapsulation of streaming upload (put_object). You do not need to provide the put_object_data_callback callback function. Instead, you can directly upload text content. This method is suitable for uploading small files or text data stored in memory.

Restrictions

To upload an object, you must be the bucket owner or have the required permission (obs:object:PutObject granted using IAM or PutObject granted using a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Configuring an Object Policy.
The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.
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

void put_object_content(const obs_options *options, const char *key,
    const char *content, 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: Context of the requested bucket. Configure options (SDK for C) and set the AK, SK, endpoint, bucket, timeout interval, and temporary credentials through obs_options. Restrictions: None
key	const char *	Yes	Explanation: Object name. An object name uniquely identifies an object in a bucket. Restrictions: None Value range: The value can contain 1 to 1,024 characters. Default value: None
content	const char *	Yes	Explanation: Text content to be uploaded. Restrictions: None Value range: None Default value: None
content_length	uint64_t	Yes	Explanation: Length of the text content, in bytes. Restrictions: None Value range: 0 GB to 5 GB Default value: None
put_properties	Table 5 *	No	Explanation: Upload properties, including configurations such as content_type, md5, ACL, metadata, and upload speed limit. You can use init_put_properties for initialization. Restrictions: None
encryption_params	Table 6*	No	Explanation: Parameters related to server-side encryption. Restrictions: None
handler	Table 2*	Yes	Explanation: Callback structure, including the response callback, data upload callback, and progress callback. Restrictions: When using put_object_content, you do not need to provide a put_object_data_callback because the SDK will handle it automatically.
callback_data	void *	No	Explanation: Custom callback data. Restrictions: None Value range: None Default value: None

**Table 2** obs_put_object_handler
Parameter	Type	Mandatory (Yes/No)	Description
response_handler	obs_response_handler	Yes	Explanation: Response callback function structure, including properties_callback and complete_callback. Restrictions: None
put_object_data_callback	Table 3*	No	Explanation: Pointer to the callback function for uploading data. When put_object_content is used, the SDK automatically sets this callback. Restrictions: None
progress_callback	Table 4*	No	Explanation: Pointer to the progress callback function, which is used to obtain the upload progress. Restrictions: None

**Table 3** 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 4** 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 5** obs_put_properties
Parameter	Type	Mandatory (Yes/No)	Description
content_type	char *	No	Explanation: Specifies the file type of the object to be downloaded. Restrictions: None Value range: See the Content-Type values defined in HTTP. Default value: None
md5	char *	No	Explanation: Base64-encoded MD5 value of the object data. It is provided for the OBS server to verify data integrity. Restrictions: The MD5 value of the object must be Base64 encoded. If this parameter 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. Default value: None
cache_control	char *	No	Explanation: 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 *	No	Explanation: Specifies the name of an object when it is downloaded. Restrictions: None Value range: See the Content-Disposition values defined in HTTP. Default value: None
content_encoding	char *	No	Explanation: 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 *	No	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. Restrictions: The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB. 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: 0: The bandwidth is not limited.
expires	int64_t	No	Explanation: Value of the Expires header in the OBS request. It specifies the expiration time of a cached web page when an 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 expiration time calculated based on the specified number of days cannot be earlier than the current time. Value range: The value is an integer greater than 0. Default value: None
canned_acl	Table 8	No	Explanation: Access control policy. Restrictions: None 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	Table 9*	No	Explanation: Custom metadata of an object. Restrictions: The total size of all custom metadata cannot exceed 8 KB. The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive. Value range: None Default value: None
metadata_action	Table 10	No	Explanation: Metadata operation indicator. Restrictions: None Value range: OBS_REPLACE: The metadata is replaced with the header included in the current request and the metadata not specified is deleted. OBS_REPLACE_NEW: The existing metadata value is replaced with a new one, the metadata lacking a value is assigned one, and the metadata not specified keeps unchanged. Default value: None
server_callback	Table 11	No	Explanation: Parameters related to server callback. Restrictions: None Value range: None Default value: None

**Table 6** 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: To obtain the key ID, see Viewing a CMK. 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 no 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 7** obs_encryption_type
Constant	Original Value	Description
OBS_ENCRYPTION_KMS	kms	Use the KMS encryption.
OBS_ENCRYPTION_SSEC	AES256	Use the SSE-C encryption.

**Table 8** obs_canned_acl
Constant	Original Value	Description
OBS_CANNED_ACL_PRIVATE	private	Private read and write. A bucket or object can only be accessed by its owner.
OBS_CANNED_ACL_PUBLIC_READ	public-read	Public read and private write. If this permission is granted for a bucket, anyone can read the object list, multipart uploads, bucket metadata, and object versions in the bucket. If this permission is granted for an object, everyone can obtain the content and metadata of the object.
OBS_CANNED_ACL_PUBLIC_READ_WRITE	public-read-write	Public read and write. If this permission is granted for a bucket, everyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart uploads, upload parts, assemble parts, copy parts, and abort multipart uploads. If this permission is granted for an object, everyone can obtain the content and metadata of the object.
OBS_CANNED_ACL_BUCKET_OWNER_FULL_CONTROL	bucket-owner-full-control	If this permission is granted for 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. This permission is supported only by S3 APIs.
OBS_CANNED_ACL_PUBLIC_READ_DELIVERED	public-read-delivered	Public read on a bucket and its objects. If this permission is granted for a bucket, everyone can read the object list, multipart uploads, and bucket metadata, and can also read the content and metadata of the objects in the bucket. This permission cannot be granted for objects.
OBS_CANNED_ACL_PUBLIC_READ_WRITE_DELIVERED	public-read-write-delivered	Public read and write on a bucket and its objects. If this permission is granted for a bucket, everyone can read the object list, multipart uploads, and bucket metadata, and can upload or delete objects, initiate multipart uploads, 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 for objects.

**Table 9** 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 10** metadata_action_indicator
Constant	Original Value	Description
OBS_NO_METADATA_ACTION	-	Default invalid value.
OBS_REPLACE	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	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 11** 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_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

Sample Code

This example calls the text upload API to upload text content.

#include "eSDKOBS.h"
#include <stdio.h>
#include <string.h>
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data);
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data);
int main()
{
    obs_initialize(OBS_INIT_ALL);
    obs_options options;
    init_obs_options(&options);
    // Enter the endpoint corresponding to the bucket for host_name. CN-Hong Kong is used here as an example. Replace it with the one currently in use.
    options.bucket_options.host_name = "obs.ap-southeast-1.myhuaweicloud.com";
    // Hard-coded or plaintext AK and SK are risky. For security purposes, encrypt your AK and SK and store them in the configuration file or environment variables.
    // In this example, the AK and SK are stored in environment variables for identity authentication. Before running the code in this example, configure local environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    options.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    options.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    options.bucket_options.bucket_name = "example-bucket-name";
    // Set upload properties.
    obs_put_properties put_properties;
    init_put_properties(&put_properties);
    put_properties.content_type = "text/plain";
    // Text content to be uploaded
    const char *content = "Hello, OBS!";
    uint64_t content_length = strlen(content);
    obs_response_handler response_handler = {&response_properties_callback, &response_complete_callback};
    obs_put_object_handler handler = {response_handler, NULL, NULL};
    obs_status ret_status = OBS_STATUS_BUTT;
    put_object_content(&options, "objectname", content, content_length,
                       &put_properties, NULL, &handler, &ret_status);
    if (OBS_STATUS_OK == ret_status) {
        printf("put object content successfully.\n");
    } else {
        printf("put object content failed(%s).\n", obs_get_status_name(ret_status));
    }
    obs_deinitialize();
}
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data)
{
    (void)properties; (void)callback_data;
    return OBS_STATUS_OK;
}
void response_complete_callback(obs_status status, const obs_error_details *error, void *callback_data)
{
    if (callback_data) { *(obs_status*)callback_data = status; }
    if (error && error->message) { printf("Error: %s\n", error->message); }
}