Help Center/ Object Storage Service/ SDK Reference/ C/ Bucket APIs (SDK for C)/ Other APIs (SDK for C)/ Using Custom Headers (SDK for C)
Updated on 2026-08-03 GMT+08:00
View PDF
Share

Using Custom Headers (SDK for C)

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

Function

The OBS SDK for C allows you to include custom HTTP headers in requests. You can set custom headers through the custom_headers field in obs_options.request_options. All operations (such as PUT, GET, DELETE, and LIST) support this function.

Restrictions

Header Prefix

Case Processing

Signed (Yes/No)

 
x-obs-*

Automatically converted to lowercase

Yes

Others

Remain unchanged

No
  • Header names starting with x-obs- are automatically converted to lowercase letters and included in request signature calculation.
  • Other headers remain unchanged and are sent only as HTTP headers. They are not included in the signature.
  • Standard signature headers such as Content-Type and Content-MD5 must be set using obs_put_properties. Do not pass them through custom headers.

Method

Table 1 obs_http_request_option

Parameter

Type

Mandatory (Yes/No)

Description

ustom_headers_count

int

No

Explanation:

Number of custom headers.

Restrictions:

The custom headers and user metadata (meta_data) share the internal array.

Value range:

An integer greater than or equal to 0. If the value is 0, no custom headers are sent. Negative values are treated as 0.

Default value:

0

custom_headers

Table 2*

No

Explanation:

Custom header array. Each element is a key-value pair. For details, see Table 2.

Restrictions:

If the value of custom_headers_count is greater than 0, this parameter cannot be set to NULL. The name and value of each element cannot be NULL. Otherwise, the element will be skipped. The total raw byte length of all headers must not exceed OBS_MAX_METADATA_SIZE (4096 bytes). If the length exceeds the limit, OBS_STATUS_MetadataHeadersTooLong is returned. Do not use this field to set standard signature headers such as Content-Type and Content-MD5. Instead, use the corresponding fields in obs_put_properties. Otherwise, signature inconsistency may occur.

Value range:

Pointer to the obs_name_value array. The array length must be greater than or equal to the value of custom_headers_count.

Default value:

NULL
Table 2 obs_name_value

Parameter

Type

Mandatory (Yes/No)

Description

name

char *

Yes

Explanation:

Name of the custom header.

Restrictions:

The value cannot be NULL. Otherwise, the item will be skipped.

Value range:

The value is a valid HTTP header name string. Names starting with x-obs- are automatically converted to lowercase letters and included in the signature. Other names remain unchanged and are not included in the signature.

Default value:

None

value

char *

Yes

Explanation:

Value of the custom header.

Restrictions:

The value cannot be NULL. Otherwise, the item will be skipped. The pointer must remain valid before the request is complete.

Value range:

The value is a valid HTTP header value string.

Default value:

None

Sample Code 1: Uploading an Object with Custom Headers

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
 
#include "eSDKOBS.h"
#include <stdlib.h>
// Response callback
void response_complete_callback(obs_status status,
    const obs_error_details *error, void *callback_data)
{
    if (status != OBS_STATUS_OK) {
        printf("request failed, status=%d\n", status);
        if (error && error->message) {
            printf("error: %s\n", error->message);
        }
    } else {
        printf("request succeeded\n");
    }
}
obs_status response_properties_callback(const obs_response_properties *properties,
    void *callback_data)
{
    return OBS_STATUS_OK;
}
int main()
{
    // 1. Initialize options.
    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";
    options.bucket_options.bucket_name = "your-bucket";
    // 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");
    // 2. Configure custom headers.
    obs_name_value headers[2];
    headers[0].name = "x-obs-request-source";
    headers[0].value = "sdk-custom-header";
    headers[1].name = "X-Client-Version";
    headers[1].value = "1.0.0";
    options.request_options.custom_headers = headers;
    options.request_options.custom_headers_count = 2;
    // 3. Set upload attributes.
    obs_put_properties put_properties;
    init_put_properties(&put_properties);
    put_properties.content_type = "text/plain";
    // 4. Construct a callback.
    obs_put_object_handler handler =
        {{&response_properties_callback, &response_complete_callback},
         NULL};
    // 5. Upload an object. (The custom headers will be automatically included.)
    char *key = "test-object.txt";
    char *data = "Hello OBS!";
    put_object(&options, key, strlen(data),
               &put_properties, NULL, &handler, NULL);
    return 0;
}

This request will contain the following HTTP headers:

x-obs-request-source: sdk-custom-header: This header is included in the signature and the name has been converted to lowercase letters.
X-Client-Version: 1.0.0: This header is not included in the signature and the original case is retained.

Sample Code 2: Downloading an Object with Custom Headers

obs_options options;
init_obs_options(&options);
// Set bucket_options.
// Configure custom headers.
obs_name_value headers[1];
headers[0].name = "x-obs-request-source";
headers[0].value = "download-with-custom-header";
options.request_options.custom_headers = headers;
options.request_options.custom_headers_count = 1;
// Download an object.
obs_object_info object_info;
object_info.key = "test-object.txt";
object_info.version_id = NULL;
obs_response_handler handler =
    {&response_properties_callback, &response_complete_callback};
get_object(&options, &object_info, NULL, &handler, NULL)
Parent topic: Other APIs (SDK for C)