tencent cloud

Cloud Object Storage

Single-Connection Bandwidth Limit

Download
Focus Mode
Font Size
Last updated: 2026-05-15 15:30:57

Introduction

This document provides example code and descriptions for the COS feature that limits link speed when the upload and download APIs are called via the Android SDK.

Must-Knows

The speed limit value can be set within the range of 819200 - 838860800 bits per second (800 Kb/s - 800 Mb/s) by default. A 400 error is returned if the value exceeds this range.
Note:
For more information about single-link speed limiting, see the Single-Link Speed Limiting developer guide.

Related Examples

Feature Name
Description
Example code
Upload Speed Limiting
Provides the capability to throttle a single connection during upload.
Download Speed Limiting
Provides the capability to throttle a single connection during download.

Preliminary Preparation

Creating a TransferManager

Before using the advanced API, you must first create a TransferManager instance. Before creating a TransferManager instance, you need to create a CosXmlService instance. For detailed code, see Creating CosXmlService.
// Initialize TransferConfig. The default configuration is used here. If you need to customize it, see the SDK API documentation.
// By default, files larger than or equal to 2 MB are automatically uploaded in parts, with a part size of -1 MB. You can modify the part size threshold using the following code.
TransferConfig transferConfig = new TransferConfig.Builder() // Set the minimum object size to enable multipart upload. The default is 2 MB. .setDivisionForUpload(2097152) // Set the part size for multipart upload. The default is 1 MB. .setSliceSizeForUpload(1048576) // Set whether to force simple upload and disable multipart upload. .setForceSimpleUpload(false) .build();
// Initialize TransferManager
TransferManager transferManager = new TransferManager(cosXmlService,
transferConfig);

Use Cases

Rate Limiting for Single-Link Uploads

// A bucket name consists of bucketname-appid. You must include the appid. You can view bucket names in the COS console. https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject"; // The location identifier of the object in the bucket, i.e., the object key.
String srcPath = new File(context.getCacheDir(), "exampleobject")
.toString(); // The absolute path of the local file.
// If an UploadId for initializing multipart upload exists, assign the corresponding uploadId value for resuming the upload. Otherwise, assign null.
String uploadId = null;

PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath, srcPath);
// Set the single-link speed limit in bits per second. The example sets it to 1 MB/s.
putObjectRequest.setTrafficLimit(1024 * 1024 * 8);

// Upload documents.
COSXMLUploadTask cosxmlUploadTask = transferManager.upload(putObjectRequest, uploadId);

// Set the upload progress callback
cosxmlUploadTask.setCosXmlProgressListener(new CosXmlProgressListener() {
@Override
public void onProgress(long complete, long target) {
// todo Do something to update progress...
}
});
// Set the result callback
cosxmlUploadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
COSXMLUploadTask.COSXMLUploadTaskResult uploadResult =
(COSXMLUploadTask.COSXMLUploadTaskResult) result;
}

// If you call the API using kotlin, note that the exception in the callback method must be nullable. Otherwise, the onFail method will not be called, as follows:
// The type of clientException is CosXmlClientException?, and the type of serviceException is CosXmlServiceException?
@Override
public void onFail(CosXmlRequest request,
@Nullable CosXmlClientException clientException,
@Nullable CosXmlServiceException serviceException) {
if (clientException != null) {
clientException.printStackTrace();
} else {
serviceException.printStackTrace();
}
}
});
// Set the task status callback to view the task progress.
cosxmlUploadTask.setTransferStateListener(new TransferStateListener() {
@Override
public void onStateChanged(TransferState state) {
// todo notify transfer state
}
});

Rate Limiting for Single-Link Downloads

//.cssg-snippet-body-start:[transfer-download-object]
// The advanced download API supports resumable transfer. Therefore, it sends a HEAD request before downloading to obtain file information.
// If you are using a temporary key or accessing with a sub-account, ensure that the permission list includes the HeadObject permission.

// A bucket name consists of bucketname-appid. You must include the appid. You can view bucket names in the COS console. https://console.tencentcloud.com/cos5/bucket
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject"; // The location identifier of the object in the bucket, i.e., the object key.
// Local directory path
String savePathDir = context.getExternalCacheDir().toString();
// The file name saved locally. If left blank (null), it will be the same as the file name on COS.
String savedFileName = "exampleobject";

GetObjectRequest getObjectRequest = new GetObjectRequest(bucket, cosPath, savePathDir, savedFileName);
// Set the single-link speed limit in bits per second. The example sets it to 1 MB/s.
getObjectRequest.setTrafficLimit(1024 * 1024 * 8);

Context applicationContext = context.getApplicationContext(); // application
// context
COSXMLDownloadTask cosxmlDownloadTask =
transferManager.download(applicationContext, getObjectRequest);

// Set the download progress callback
cosxmlDownloadTask.setCosXmlProgressListener(new CosXmlProgressListener() {
@Override
public void onProgress(long complete, long target) {
// todo Do something to update progress...
}
});
// Set the result callback
cosxmlDownloadTask.setCosXmlResultListener(new CosXmlResultListener() {
@Override
public void onSuccess(CosXmlRequest request, CosXmlResult result) {
COSXMLDownloadTask.COSXMLDownloadTaskResult downloadTaskResult =
(COSXMLDownloadTask.COSXMLDownloadTaskResult) result;
}

// If you call the API using kotlin, note that the exception in the callback method must be nullable. Otherwise, the onFail method will not be called, as follows:
// The type of clientException is CosXmlClientException?, and the type of serviceException is CosXmlServiceException?
@Override
public void onFail(CosXmlRequest request,
@Nullable CosXmlClientException clientException,
@Nullable CosXmlServiceException serviceException) {
if (clientException != null) {
clientException.printStackTrace();
} else {
serviceException.printStackTrace();
}
}
});
// Set the task status callback to view the task progress.
cosxmlDownloadTask.setTransferStateListener(new TransferStateListener() {
@Override
public void onStateChanged(TransferState state) {
// todo notify transfer state
}
});

SDK API Reference

For detailed parameters and method descriptions of all SDK interfaces, see SDK API Reference.

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback