@ohos.request (Upload and Download)

The request module provides applications with basic upload, download, and background transmission agent capabilities.

NOTE

The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import request from '@ohos.request';

Constants

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Network Types

You can set networkType in DownloadConfig to specify the network type for the download service.

Download Error Codes

The table below lists the values of err in the callback of on('fail')⁷⁺ and the values of failedReason returned by getTaskInfo⁹⁺.

Causes of Download Pause

The table below lists the values of pausedReason returned by getTaskInfo⁹⁺.

Download Task Status Codes

The table below lists the values of status returned by getTaskInfo⁹⁺.

request.uploadFile⁹⁺

uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask>

Uploads files. This API uses a promise to return the result. You can use on('complete'|'fail')⁹⁺ to obtain the upload error information.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Return value

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let uploadTask: request.UploadTask;
let uploadConfig: request.UploadConfig = {
  url: 'http://www.example.com', // Replace the example with the actual server address.
  header: { 'Accept': '*/*' },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
try {
  request.uploadFile(getContext(), uploadConfig).then((data: request.UploadTask) => {
    uploadTask = data;
  }).catch((err: BusinessError) => {
    console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
  });
} catch (err) {
  console.error(`Failed to request the upload. err: ${JSON.stringify(err)}`);
}

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

request.uploadFile⁹⁺

uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void

Uploads files. This API uses an asynchronous callback to return the result. You can use on('complete'|'fail')⁹⁺ to obtain the upload error information.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let uploadTask: request.UploadTask;
let uploadConfig: request.UploadConfig = {
  url: 'http://www.example.com', // Replace the example with the actual server address.
  header: { 'Accept': '*/*' },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
try {
  request.uploadFile(getContext(), uploadConfig, (err: BusinessError, data: request.UploadTask) => {
    if (err) {
      console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
      return;
    }
    uploadTask = data;
  });
} catch (err) {
  console.error(`Failed to request the upload. err: ${JSON.stringify(err)}`);
}

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

request.upload^(deprecated)

upload(config: UploadConfig): Promise<UploadTask>

Uploads files. This API uses a promise to return the result.

Model restriction: This API can be used only in the FA model.

NOTE

This API is deprecated since API version 9. You are advised to use request.uploadFile⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Return value

Example

let uploadTask;
let uploadConfig = {
  url: 'http://www.example.com', // Replace the example with the actual server address.
  header: { 'Accept': '*/*' },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
request.upload(uploadConfig).then((data) => {
  uploadTask = data;
}).catch((err) => {
  console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
})

request.upload^(deprecated)

upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void

Uploads files. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the FA model.

NOTE

This API is deprecated since API version 9. You are advised to use request.uploadFile⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Example

let uploadTask;
let uploadConfig = {
  url: 'http://www.example.com', // Replace the example with the actual server address.
  header: { 'Accept': '*/*' },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
request.upload(uploadConfig, (err, data) => {
  if (err) {
    console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  uploadTask = data;
});

UploadTask

Implements file uploads. Before using any APIs of this class, you must obtain an UploadTask object through request.uploadFile⁹⁺ in promise mode or request.uploadFile⁹⁺ in callback mode.

on('progress')

on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void

Subscribes to upload progress events. This API uses a callback to return the result asynchronously.

NOTE

To maintain a balance between power consumption and performance, this API cannot be called when the application is running in the background.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Parameters of the callback function

Example

let upProgressCallback = (uploadedSize: number, totalSize: number) => {
  console.info("upload totalSize:" + totalSize + "  uploadedSize:" + uploadedSize);
};
uploadTask.on('progress', upProgressCallback);

on('headerReceive')⁷⁺

on(type: 'headerReceive', callback: (header: object) => void): void

Subscribes to HTTP header events for the upload task. This API uses a callback to return the result asynchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Parameters of the callback function

Example

let headerCallback = (headers: object) => {
  console.info("upOnHeader headers:" + JSON.stringify(headers));
};
uploadTask.on('headerReceive', headerCallback);

on('complete' | 'fail')⁹⁺

on(type:'complete' | 'fail', callback: Callback<Array<TaskState>>): void;

Subscribes to upload completion or failure events. This API uses a callback to return the result asynchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Parameters of the callback function

Example

let upCompleteCallback = (taskStates: Array<request.TaskState>) => {
  for (let i = 0; i < taskStates.length; i++) {
    console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i]));
  }
};
uploadTask.on('complete', upCompleteCallback);

let upFailCallback = (taskStates: Array<request.TaskState>) => {
  for (let i = 0; i < taskStates.length; i++) {
    console.info("upOnFail taskState:" + JSON.stringify(taskStates[i]));
  }
};
uploadTask.on('fail', upFailCallback);

off('progress')

off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void

Unsubscribes from upload progress events.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Example

let upProgressCallback1 = (uploadedSize: number, totalSize: number) => {
  console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize);
};
let upProgressCallback2 = (uploadedSize: number, totalSize: number) => {
  console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize);
};
uploadTask.on('progress', upProgressCallback1);
uploadTask.on('progress', upProgressCallback2);
// Unsubscribe from upProgressCallback1.
uploadTask.off('progress', upProgressCallback1);
// Unsubscribe from all callbacks of upload progress events.
uploadTask.off('progress');

off('headerReceive')⁷⁺

off(type: 'headerReceive', callback?: (header: object) => void): void

This interface is used to unsubscribe from the HTTP header event of an upload task.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Example

let headerCallback1 = (header: object) => {
  console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`);
};
let headerCallback2 = (header: object) => {
  console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`);
};
uploadTask.on('headerReceive', headerCallback1);
uploadTask.on('headerReceive', headerCallback2);
// Unsubscribe from headerCallback1.
uploadTask.off('headerReceive', headerCallback1);
// Unsubscribe from all callbacks of the HTTP header events for the upload task.
uploadTask.off('headerReceive');

off('complete' | 'fail')⁹⁺

off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void;

Unsubscribes from upload completion or failure events.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Example

let upCompleteCallback1 = (taskStates: Array<request.TaskState>) => {
  console.info('Upload delete complete notification.');
  for (let i = 0; i < taskStates.length; i++) {
    console.info('taskState:' + JSON.stringify(taskStates[i]));
  }
};
let upCompleteCallback2 = (taskStates: Array<request.TaskState>) => {
  console.info('Upload delete complete notification.');
  for (let i = 0; i < taskStates.length; i++) {
    console.info('taskState:' + JSON.stringify(taskStates[i]));
  }
};
uploadTask.on('complete', upCompleteCallback1);
uploadTask.on('complete', upCompleteCallback2);
// Unsubscribe from headerCallback1.
uploadTask.off('complete', upCompleteCallback1);
// Unsubscribe from all callbacks of the upload completion events.
uploadTask.off('complete');

let upFailCallback1 = (taskStates: Array<request.TaskState>) => {
  console.info('Upload delete fail notification.');
  for (let i = 0; i < taskStates.length; i++) {
    console.info('taskState:' + JSON.stringify(taskStates[i]));
  }
};
let upFailCallback2 = (taskStates: Array<request.TaskState>) => {
  console.info('Upload delete fail notification.');
  for (let i = 0; i < taskStates.length; i++) {
    console.info('taskState:' + JSON.stringify(taskStates[i]));
  }
};
uploadTask.on('fail', upFailCallback1);
uploadTask.on('fail', upFailCallback2);
// Unsubscribe from headerCallback1.
uploadTask.off('fail', upFailCallback1);
// Unsubscribe from all callbacks of the upload failure events.
uploadTask.off('fail');

delete⁹⁺

delete(): Promise<boolean>

Deletes this upload task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Return value

Example

uploadTask.delete().then((result: boolean) => {
  console.info('Succeeded in deleting the upload task.');
}).catch((err: BusinessError) => {
  console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`);
});

delete⁹⁺

delete(callback: AsyncCallback<boolean>): void

Deletes this upload task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Example

uploadTask.delete((err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in deleting the upload task.');
});

remove^(deprecated)

remove(): Promise<boolean>

Removes this upload task. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use delete⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Return value

Example

uploadTask.remove().then((result) => {
  console.info('Succeeded in removing the upload task.');
}).catch((err) => {
  console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
});

remove^(deprecated)

remove(callback: AsyncCallback<boolean>): void

Removes this upload task. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use delete⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Example

uploadTask.remove((err, result) => {
  if (err) {
    console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in removing the upload task.');
  } else {
    console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
  }
});

UploadConfig⁶⁺

Describes the configuration of an upload task.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

TaskState⁹⁺

Implements a TaskState object, which is the callback parameter of the on('complete' | 'fail')⁹⁺ and off('complete' | 'fail')⁹⁺ APIs.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

File

Defines the file list in UploadConfig⁶⁺.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

RequestData

Defines the form data in UploadConfig⁶⁺.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

request.downloadFile⁹⁺

downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask>

Downloads files. This API uses a promise to return the result. You can use on('complete'|'pause'|'remove')⁷⁺ to obtain the download task state, which can be completed, paused, or removed. You can also use on('fail')⁷⁺ to obtain the task download error information.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Return value

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
     let downloadTask: request.DownloadTask = data;
  }).catch((err: BusinessError) => {
    console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
  })
} catch (err) {
  console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

request.downloadFile⁹⁺

downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void;

Downloads files. This API uses an asynchronous callback to return the result. You can use on('complete'|'pause'|'remove')⁷⁺ to obtain the download task state, which can be completed, paused, or removed. You can also use on('fail')⁷⁺ to obtain the task download error information.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  request.downloadFile(getContext(), {
    url: 'https://xxxx/xxxxx.hap',
    filePath: 'xxx/xxxxx.hap'
  }, (err: BusinessError, data: request.DownloadTask) => {
    if (err) {
      console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
      return;
    }
    let downloadTask: request.DownloadTask = data;
  });
} catch (err) {
  console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

request.download^(deprecated)

download(config: DownloadConfig): Promise<DownloadTask>

Downloads files. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use request.downloadFile⁹⁺ instead.

Model restriction: This API can be used only in the FA model.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Return value

Example

let downloadTask;
request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => {
  downloadTask = data;
}).catch((err) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})

request.download^(deprecated)

download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void

Downloads files. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use request.downloadFile⁹⁺ instead.

Model restriction: This API can be used only in the FA model.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

let downloadTask;
request.download({ url: 'https://xxxx/xxxxx.hap', 
filePath: 'xxx/xxxxx.hap'}, (err, data) => {
  if (err) {
    console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  downloadTask = data;
});

DownloadTask

Implements file downloads. Before using any APIs of this class, you must obtain a DownloadTask object through request.downloadFile⁹⁺ in promise mode or request.downloadFile⁹⁺ in callback mode.

on('progress')

on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void

Subscribes to download progress events. This API uses a callback to return the result asynchronously.

NOTE

To maintain a balance between power consumption and performance, this API cannot be called when the application is running in the background.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Parameters of the callback function

Example

import { BusinessError } from '@ohos.base';

try {
  request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
    let downloadTask: request.DownloadTask = data;
    let progressCallback = (receivedSize: number, totalSize: number) => {
      console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
    };
    downloadTask.on('progress', progressCallback);
  }).catch((err: BusinessError) => {
    console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
  })
} catch (err) {
  console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

off('progress')

off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void

Unsubscribes from download progress events.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  let progressCallback1 = (receivedSize: number, totalSize: number) => {
    console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize);
  };
  let progressCallback2 = (receivedSize: number, totalSize: number) => {
    console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize);
  };
  downloadTask.on('progress', progressCallback1);
  downloadTask.on('progress', progressCallback2);
  // Unsubscribe from progressCallback1.
  downloadTask.off('progress', progressCallback1);
  // Unsubscribe from all callbacks of download progress events.
  downloadTask.off('progress');
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

on('complete'|'pause'|'remove')⁷⁺

on(type: 'complete'|'pause'|'remove', callback:() => void): void

Subscribes to download events. This API uses a callback to return the result asynchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  let completeCallback = () => {
    console.info('Download task completed.');
  };
  downloadTask.on('complete', completeCallback);

  let pauseCallback = () => {
    console.info('Download task pause.');
  };
  downloadTask.on('pause', pauseCallback);

  let removeCallback = () => {
    console.info('Download task remove.');
  };
  downloadTask.on('remove', removeCallback);
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

off('complete'|'pause'|'remove')⁷⁺

off(type: 'complete'|'pause'|'remove', callback?:() => void): void

Unsubscribes from download events.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  let completeCallback1 = () => {
    console.info('Download delete complete notification.');
  };
  let completeCallback2 = () => {
    console.info('Download delete complete notification.');
  };
  downloadTask.on('complete', completeCallback1);
  downloadTask.on('complete', completeCallback2);
  // Unsubscribe from completeCallback1.
  downloadTask.off('complete', completeCallback1);
  // Unsubscribe from all callbacks of the download completion events.
  downloadTask.off('complete');

  let pauseCallback1 = () => {
    console.info('Download delete pause notification.');
  };
  let pauseCallback2 = () => {
    console.info('Download delete pause notification.');
  };
  downloadTask.on('pause', pauseCallback1);
  downloadTask.on('pause', pauseCallback2);
  // Unsubscribe from pauseCallback1.
  downloadTask.off('pause', pauseCallback1);
  // Unsubscribe from all callbacks of the download pause events.
  downloadTask.off('pause');

  let removeCallback1 = () => {
    console.info('Download delete remove notification.');
  };
  let removeCallback2 = () => {
    console.info('Download delete remove notification.');
  };
  downloadTask.on('remove', removeCallback1);
  downloadTask.on('remove', removeCallback2);
  // Unsubscribe from removeCallback1.
  downloadTask.off('remove', removeCallback1);
  // Unsubscribe from all callbacks of the download removal events.
  downloadTask.off('remove');
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

on('fail')⁷⁺

on(type: 'fail', callback: (err: number) => void): void

Subscribes to download failure events. This API uses a callback to return the result asynchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Parameters of the callback function

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  let failCallback = (err: number) => {
    console.error(`Failed to download the task. Code: ${err}`);
  };
  downloadTask.on('fail', failCallback);
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

off('fail')⁷⁺

off(type: 'fail', callback?: (err: number) => void): void

Unsubscribes from download failure events.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  let failCallback1 = (err: number) => {
    console.error(`Failed to download the task. Code: ${err}`);
  };
  let failCallback2 = (err: number) => {
    console.error(`Failed to download the task. Code: ${err}`);
  };
  downloadTask.on('fail', failCallback1);
  downloadTask.on('fail', failCallback2);
  // Unsubscribe from failCallback1.
  downloadTask.off('fail', failCallback1);
  // Unsubscribe from all callbacks of the download failure events.
  downloadTask.off('fail');
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

delete⁹⁺

delete(): Promise<boolean>

Deletes this download task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  downloadTask.delete().then((result: boolean) => {
    console.info('Succeeded in removing the download task.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

delete⁹⁺

delete(callback: AsyncCallback<boolean>): void

Deletes this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  downloadTask.delete((err: BusinessError, result: boolean) => {
    if (err) {
      console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in removing the download task.');
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

getTaskInfo⁹⁺

getTaskInfo(): Promise<DownloadInfo>

Obtains the information about this download task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  downloadTask.getTaskInfo().then((downloadInfo: request.DownloadInfo) => {
    console.info('Succeeded in querying the download task')
  }).catch((err: BusinessError) => {
    console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`)
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
} 

getTaskInfo⁹⁺

getTaskInfo(callback: AsyncCallback<DownloadInfo>): void

Obtains the information about this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  downloadTask.getTaskInfo((err: BusinessError, downloadInfo: request.DownloadInfo) => {
    if (err) {
      console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info('Succeeded in querying the download mimeType');
    }
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

getTaskMimeType⁹⁺

getTaskMimeType(): Promise<string>

Obtains the MimeType of this download task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  downloadTask.getTaskMimeType().then((data: string) => {
    console.info('Succeeded in querying the download MimeType');
  }).catch((err: BusinessError) => {
    console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`)
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

getTaskMimeType⁹⁺

getTaskMimeType(callback: AsyncCallback<string>): void;

Obtains the MimeType of this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  downloadTask.getTaskMimeType((err: BusinessError, data: string) => {
    if (err) {
      console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info('Succeeded in querying the download mimeType');
    }
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

suspend⁹⁺

suspend(): Promise<boolean>

Pauses this download task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  downloadTask.suspend().then((result: boolean) => {
    console.info('Succeeded in pausing the download task.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

suspend⁹⁺

suspend(callback: AsyncCallback<boolean>): void

Pauses this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  downloadTask.suspend((err: BusinessError, result: boolean) => {
    if (err) {
      console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in pausing the download task.');
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

restore⁹⁺

restore(): Promise<boolean>

Resumes this download task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  downloadTask.restore().then((result: boolean) => {
    console.info('Succeeded in resuming the download task.')
  }).catch((err: BusinessError) => {
    console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

restore⁹⁺

restore(callback: AsyncCallback<boolean>): void

Resumes this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

import { BusinessError } from '@ohos.base';

try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  downloadTask.restore((err: BusinessError, result: boolean) => {
    if (err) {
      console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in resuming the download task.');
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

remove^(deprecated)

remove(): Promise<boolean>

Removes this download task. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use delete⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Example

downloadTask.remove().then((result) => {
  console.info('Succeeded in removing the download task.');
}).catch ((err) => {
  console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
});

remove^(deprecated)

remove(callback: AsyncCallback<boolean>): void

Removes this download task. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use delete⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

downloadTask.remove((err, result)=>{
  if(err) {
    console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in removing the download task.');
});

query^(deprecated)

query(): Promise<DownloadInfo>

Queries this download task. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use getTaskInfo⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Example

downloadTask.query().then((downloadInfo) => {    
  console.info('Succeeded in querying the download task.')
}) .catch((err) => {
  console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`)
});

query^(deprecated)

query(callback: AsyncCallback<DownloadInfo>): void

Queries this download task. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use getTaskInfo⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

downloadTask.query((err, downloadInfo)=>{
  if(err) {
    console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
  } else {
    console.info('Succeeded in querying the download task.');
  }
});

queryMimeType^(deprecated)

queryMimeType(): Promise<string>

Queries the MimeType of this download task. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use getTaskMimeType⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Example

downloadTask.queryMimeType().then((data) => {    
  console.info('Succeeded in querying the download MimeType.');
}).catch((err) => {
  console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`)
});

queryMimeType^(deprecated)

queryMimeType(callback: AsyncCallback<string>): void;

Queries the MimeType of this download task. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use getTaskMimeType⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

downloadTask.queryMimeType((err, data)=>{
  if(err) {
    console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
  } else {
    console.info('Succeeded in querying the download mimeType.');
  }
});

pause^(deprecated)

pause(): Promise<void>

Pauses this download task. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use suspend⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Example

downloadTask.pause().then((result) => {    
  console.info('Succeeded in pausing the download task.');
}).catch((err) => {
  console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
});

pause^(deprecated)

pause(callback: AsyncCallback<void>): void

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use suspend⁹⁺ instead.

Pauses this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

downloadTask.pause((err, result)=>{
  if(err) {
    console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in pausing the download task.');
});

resume^(deprecated)

resume(): Promise<void>

Resumes this download task. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use restore⁹⁺ instead.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Example

downloadTask.resume().then((result) => {
  console.info('Succeeded in resuming the download task.')
}).catch((err) => {
  console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
});

resume^(deprecated)

resume(callback: AsyncCallback<void>): void

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use restore⁹⁺ instead.

Resumes this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Example

downloadTask.resume((err, result)=>{
  if (err) {
    console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in resuming the download task.');
});

DownloadConfig

Defines the download task configuration.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

DownloadInfo⁷⁺

Defines the download task information, which is the callback parameter of the getTaskInfo⁹⁺ API.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Action¹⁰⁺

Defines action options.

System capability: SystemCapability.Request.FileTransferAgent

Mode¹⁰⁺

Defines mode options.
After an application is switched to the background for a period of time, background tasks are not affected but foreground tasks will fail or pause.

System capability: SystemCapability.Request.FileTransferAgent

Network¹⁰⁺

Defines network options.
If the network does not meet the preset conditions, the tasks that have not been executed will await for execution, and the tasks that are being executed will fail or pause.

System capability: SystemCapability.Request.FileTransferAgent

BroadcastEvent¹¹⁺

Defines a custom system event. You can use a common event API to obtain the event. The upload and download SA has the ohos.permission.SEND_TASK_COMPLETE_EVENT permission. You can configure the level-2 configuration file to which the metadata of an event points to intercept other event senders.

You can use the CommonEventData type to transmit data related to common events. The members in CommonEventData are different from those described in CommonEventData. Specifically, CommonEventData.code indicates the task status, which is 0x40 COMPLETE or 0x41 FAILED, and CommonEventData.data indicates the task ID.

For details about event configuration information, see Subscribing to Common Events in Static Mode.

System capability: SystemCapability.Request.FileTransferAgent

FileSpec¹⁰⁺

Provides the file information of a table item.

System capability: SystemCapability.Request.FileTransferAgent

FormItem¹⁰⁺

Describes the form item of a task.

System capability: SystemCapability.Request.FileTransferAgent

Config¹⁰⁺

Provides the configuration information of an upload or download task.

System capability: SystemCapability.Request.FileTransferAgent

State¹⁰⁺

Defines the current task status.

System capability: SystemCapability.Request.FileTransferAgent

Progress¹⁰⁺

Describes the data structure of the task progress.

System capability: SystemCapability.Request.FileTransferAgent

Faults¹⁰⁺

Defines the cause of a task failure.

System capability: SystemCapability.Request.FileTransferAgent

Filter¹⁰⁺

Defines the filter criteria.

System capability: SystemCapability.Request.FileTransferAgent

TaskInfo¹⁰⁺

Defines the data structure of the task information for query. The fields available vary depending on the query type.

System capability: SystemCapability.Request.FileTransferAgent

Task¹⁰⁺

Implements an upload or download task. Before using this API, you must obtain a Task object, from a promise through request.agent.create¹⁰⁺ or from a callback through request.agent.create¹⁰⁺.

Attributes

Task attributes include the task ID and task configuration.

System capability: SystemCapability.Request.FileTransferAgent

on('progress')¹⁰⁺

on(event: 'progress', callback: (progress: Progress) => void): void

Subscribes to task progress changes. This API uses a callback to return the result asynchronously.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task progress.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('progress', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

on('completed')¹⁰⁺

on(event: 'completed', callback: (progress: Progress) => void): void

Subscribes to task completion events. This API uses a callback to return the result asynchronously.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task completed.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('completed', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

on('failed')¹⁰⁺

on(event: 'failed', callback: (progress: Progress) => void): void

Subscribes to task failure events. This API uses a callback to return the result asynchronously.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task failed.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('failed', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

on('pause')¹¹⁺

on(event: 'pause', callback: (progress: Progress) => void): void

Subscribes to task pause events. This API uses a callback to return the result asynchronously.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task pause.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('pause', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

on('resume')¹¹⁺

on(event: 'resume', callback: (progress: Progress) => void): void

Subscribes to task resume events. This API uses a callback to return the result asynchronously.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task resume.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('resume', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

on('remove')¹¹⁺

on(event: 'remove', callback: (progress: Progress) => void): void

Subscribes to task removal events. This API uses a callback to return the result asynchronously.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task remove.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('remove', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

off('progress')¹⁰⁺

off(event: 'progress', callback?: (progress: Progress) => void): void

Unsubscribes from task progress events.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task progress.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task progress.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('progress', createOffCallback1);
  task.on('progress', createOffCallback2);
  // Unsubscribe from createOffCallback1.
  task.off('progress', createOffCallback1);
  // Unsubscribe from all callbacks of task progress changes.
  task.off('progress');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

off('completed')¹⁰⁺

off(event: 'completed', callback?: (progress: Progress) => void): void

Unsubscribes from task completion events.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task completed.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task completed.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('completed', createOffCallback1);
  task.on('completed', createOffCallback2);
  // Unsubscribe from createOffCallback1.
  task.off('completed', createOffCallback1);
  // Unsubscribe from all callbacks of the task completion events.
  task.off('completed');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

off('failed')¹⁰⁺

off(event: 'failed', callback?: (progress: Progress) => void): void

Unsubscribes from task failure events.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task failed.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task failed.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('failed', createOffCallback1);
  task.on('failed', createOffCallback2);
  // Unsubscribe from createOffCallback1.
  task.off('failed', createOffCallback1);
  // Unsubscribe from all callbacks of the task failure events.
  task.off('failed');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

off('pause')¹¹⁺

off(event: 'pause', callback?: (progress: Progress) => void): void

Unsubscribes from the foreground task pause event.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task pause.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task pause.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('pause', createOffCallback1);
  task.on('pause', createOffCallback2);
  // Unsubscribe from createOffCallback1.
  task.off('pause', createOffCallback1);
  // Unsubscribe from all callbacks of the foreground task pause event.
  task.off('pause');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

off('resume')¹¹⁺

off(event: 'resume', callback?: (progress: Progress) => void): void

Unsubscribes from the foreground task resume event.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task resume.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task resume.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('resume', createOffCallback1);
  task.on('resume', createOffCallback2);
  // Unsubscribe from createOffCallback1.
  task.off('resume', createOffCallback1);
  // Unsubscribe from all callbacks of the foreground task resume event.
  task.off('resume');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

off('remove')¹¹⁺

off(event: 'remove', callback?: (progress: Progress) => void): void

Unsubscribes from the task removal event.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    mimeType: "application/octet-stream",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task remove.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task remove.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.on('remove', createOffCallback1);
  task.on('remove', createOffCallback2);
  // Unsubscribe from createOffCallback1.
  task.off('remove', createOffCallback1);
  // Unsubscribe from all callbacks of the task removal event.
  task.off('remove');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

start¹⁰⁺

start(callback: AsyncCallback<void>): void

Starts this task. This API cannot be used to start an initialized task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1',
  title: 'taskStartTest',
  description: 'Sample code for start the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.start((err: BusinessError) => {
    if (err) {
      console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info(`Succeeded in starting a download task.`);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

start¹⁰⁺

start(): Promise<void>

Starts this task. This API cannot be used to start an initialized task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Request.FileTransferAgent

Return value

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1',
  title: 'taskStartTest',
  description: 'Sample code for start the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.start().then(() => {
    console.info(`Succeeded in starting a download task.`);
  }).catch((err: BusinessError) => {
    console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

pause¹⁰⁺

pause(callback: AsyncCallback<void>): void

Pauses this task. This API can be used to pause a background task that is waiting, running, or retrying. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1',
  title: 'taskPauseTest',
  description: 'Sample code for pause the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.pause((err: BusinessError) => {
    if (err) {
      console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info(`Succeeded in pausing a download task. `);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

The error code 21900005 task mode error is removed from API version 11.

pause¹⁰⁺

pause(): Promise<void>

Pauses this task. This API can be used to pause a background task that is waiting, running, or retrying. This API uses a promise to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Return value

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1',
  title: 'taskPauseTest',
  description: 'Sample code for pause the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.pause().then(() => {
    console.info(`Succeeded in pausing a download task. `);
  }).catch((err: BusinessError) => {
    console.error(`Failed to pause the upload task, Code: ${err.code}, message: ${err.message}`);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

The error code 21900005 task mode error is removed from API version 11.

resume¹⁰⁺

resume(callback: AsyncCallback<void>): void

Resumes this task. This API can be used to resume a paused background task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1',
  title: 'taskResumeTest',
  description: 'Sample code for resume the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.resume((err: BusinessError) => {
    if (err) {
      console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info(`Succeeded in resuming a download task. `);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

The error code 21900005 task mode error is removed from API version 11.

resume¹⁰⁺

resume(): Promise<void>

Resumes this task. This API can be used to resume a paused background task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Request.FileTransferAgent

Return value

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1',
  title: 'taskResumeTest',
  description: 'Sample code for resume the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.resume().then(() => {
    console.info(`Succeeded in resuming a download task. `);
  }).catch((err: BusinessError) => {
    console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

The error code 21900005 task mode error is removed from API version 11.

stop¹⁰⁺

stop(callback: AsyncCallback<void>): void

Stops this task. This API can be used to stop a running, waiting, or retrying task. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1',
  title: 'taskStopTest',
  description: 'Sample code for stop the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.stop((err: BusinessError) => {
    if (err) {
      console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info(`Succeeded in stopping a download task. `);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

stop¹⁰⁺

stop(): Promise<void>

Stops this task. This API can be used to stop a running, waiting, or retrying task. This API uses a promise to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Return value

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1',
  title: 'taskStopTest',
  description: 'Sample code for stop the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  task.stop().then(() => {
    console.info(`Succeeded in stopping a download task. `);
  }).catch((err: BusinessError) => {
    console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

request.agent.create¹⁰⁺

create(context: BaseContext, config: Config, callback: AsyncCallback<Task>): void

Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 unfinished tasks. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "createTest",
  value: {
    filename: "createTest.avi",
    mimeType: "application/octet-stream",
    path: "./createTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'createTest',
  description: 'Sample code for create task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(getContext(), config, (err: BusinessError, task: request.agent.Task) => {
  if (err) {
    console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in creating a download task. result: ${task.config}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

request.agent.create¹⁰⁺

create(context: BaseContext, config: Config): Promise<Task>

Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 unfinished tasks. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Return value

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

let attachments: Array<request.agent.FormItem> = [{
  name: "createTest",
  value: {
    filename: "createTest.avi",
    mimeType: "application/octet-stream",
    path: "./createTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1',
  title: 'createTest',
  description: 'Sample code for create task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
  console.info(`Succeeded in creating a download task. result: ${task.config}`);
}).catch((err) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

NOTE

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

request.agent.getTask¹¹⁺

getTask(context: BaseContext, id: string, token?: string): Promise<Task>

Obtains task information based on the task ID. This API uses a promise to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Return value

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

request.agent.getTask(context, "123456").then((task: request.agent.Task) => {
  console.info(`Succeeded in querying a upload task. result: ${task.uid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`);
});

request.agent.remove¹⁰⁺

remove(id: string, callback: AsyncCallback<void>): void

Removes a specified task of the invoker. If the task is being executed, the task is forced to stop. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

request.agent.remove("123456", (err: BusinessError) => {
  if (err) {
    console.error(`Failed to removing a download task, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in creating a download task.`);
});

request.agent.remove¹⁰⁺

remove(id: string): Promise<void>

Removes a specified task of the invoker. If the task is being executed, the task is forced to stop. This API uses a promise to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Return value

Error codes

For details about the error codes, see Upload and Download Error Codes.

Example

request.agent.remove("123456").then(() => {
  console.info(`Succeeded in removing a download task. `);
}).catch((err: BusinessError) => {
  console.error(`Failed to remove a download task, Code: ${err.code}, message: ${err.message}`);
});

request.agent.show¹⁰⁺

show(id: string, callback: AsyncCallback<TaskInfo>): void

Queries a task details based on the task ID. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes For details about the error codes, see Upload and Download Error Codes.

Example

request.agent.show("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => {
  if (err) {
    console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in showing a upload task.`);
});

request.agent.show¹⁰⁺

show(id: string): Promise<TaskInfo>

Queries a task details based on the task ID. This API uses a promise to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Return value

Error codes For details about the error codes, see Upload and Download Error Codes.

Example

request.agent.show("123456").then((taskInfo: request.agent.TaskInfo) => {
  console.info(`Succeeded in showing a upload task.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`);
});

request.agent.touch¹⁰⁺

touch(id: string, token: string, callback: AsyncCallback<TaskInfo>): void

Queries the task details based on the task ID and token. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes For details about the error codes, see Upload and Download Error Codes.

Example

request.agent.touch("123456", "token", (err: BusinessError, taskInfo: request.agent.TaskInfo) => {
  if (err) {
    console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in touching a upload task.`);
});

request.agent.touch¹⁰⁺

touch(id: string, token: string): Promise<TaskInfo>

Queries the task details based on the task ID and token. This API uses a promise to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Return value

Error codes For details about the error codes, see Upload and Download Error Codes.

Example

request.agent.touch("123456", "token").then((taskInfo: request.agent.TaskInfo) => {
  console.info(`Succeeded in touching a upload task. `);
}).catch((err: BusinessError) => {
  console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`);
});

request.agent.search¹⁰⁺

search(callback: AsyncCallback<Array<string>>): void

Searches for task IDs based on Filter. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes For details about the error codes, see Upload and Download Error Codes.

Example

request.agent.search((err: BusinessError, data: Array<string>) => {
  if (err) {
    console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Upload task search succeeded. `);
});

request.agent.search¹⁰⁺

search(filter: Filter, callback: AsyncCallback<Array<string>>): void

Searches for task IDs based on Filter. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Error codes For details about the error codes, see Upload and Download Error Codes.

Example

let filter: request.agent.Filter = {
  bundle: "com.example.myapplication",
  action: request.agent.Action.UPLOAD,
  mode: request.agent.Mode.BACKGROUND
}
request.agent.search(filter, (err: BusinessError, data: Array<string>) => {
  if (err) {
    console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Upload task search succeeded. `);
});