diff --git a/en/application-dev/reference/apis/js-apis-storage-statistics.md b/en/application-dev/reference/apis/js-apis-storage-statistics.md index 6a5ee3a36ab94c810f6ef9cc720ded250445f3de..a0b973cb896a595e5361d5a441ab184bf0339b3d 100644 --- a/en/application-dev/reference/apis/js-apis-storage-statistics.md +++ b/en/application-dev/reference/apis/js-apis-storage-statistics.md @@ -1,9 +1,11 @@ # App Storage Statistics -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> **NOTE**
> > - The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. -> - API version 9 is a canary release for trial use. The APIs of this version may be unstable. +> - API version 9 is a canary version for trial use. The APIs of this version may be unstable. + +Obtains storage space information, including the space of built-in and plug-in memory cards, space occupied by different types of data, and space of application data. ## Modules to Import @@ -15,10 +17,14 @@ import storagestatistics from "@ohos.storageStatistics"; getTotalSizeOfVolume(volumeUuid: string): Promise<number> -Asynchronously obtains the total space of the specified volume. This API uses a promise to return the result. +Asynchronously obtains the total size of the specified volume. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER **System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics +**System API**: This is a system API and cannot be called by third-party applications. + - Parameters | Name | Type | Mandatory| Description| @@ -29,7 +35,7 @@ Asynchronously obtains the total space of the specified volume. This API uses a | Type | Description | | --------------------- | ---------------- | - | Promise<number> | Promise used to return the total space of the volume.| + | Promise<number> | Promise used to return the total size of the volume.| - Example @@ -46,16 +52,20 @@ Asynchronously obtains the total space of the specified volume. This API uses a getTotalSizeOfVolume(volumeUuid: string, callback:AsyncCallback<number>):void -Asynchronously obtains the total space of the specified volume. This API uses a callback to return the result. +Asynchronously obtains the total size of the specified volume. This API uses a callback to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER **System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics +**System API**: This is a system API and cannot be called by third-party applications. + - Parameters | Name | Type | Mandatory| Description | | ---------- | ------------------------------------ | ---- | -------------------------- | | volumeUuid | string | Yes | UUID of the volume. | - | callback | callback:AsyncCallback<number> | Yes | Callback invoked to return the total space of the volume.| + | callback | callback:AsyncCallback<number> | Yes | Callback invoked to return the total size of the volume.| - Example @@ -75,8 +85,12 @@ getFreeSizeOfVolume(volumeUuid: string): Promise<number> Asynchronously obtains the available space of the specified volume. This API uses a promise to return the result. +**Required permissions**: ohos.permission.STORAGE_MANAGER + **System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics +**System API**: This is a system API and cannot be called by third-party applications. + - Parameters | Name | Type | Mandatory| Description| @@ -107,8 +121,12 @@ getFreeSizeOfVolume(volumeUuid: string, callback:AsyncCallback<number>):vo Asynchronously obtains the available space of the specified volume. This API uses a callback to return the result. +**Required permissions**: ohos.permission.STORAGE_MANAGER + **System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics +**System API**: This is a system API and cannot be called by third-party applications. + - Parameters | Name | Type | Mandatory| Description | @@ -130,21 +148,25 @@ Asynchronously obtains the available space of the specified volume. This API use getBundleStats(packageName: string): Promise<BundleStats> -Asynchronously obtains app information. This API uses a promise to return the result. +Asynchronously obtains space information of an application. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER **System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics +**System API**: This is a system API and cannot be called by third-party applications. + - Parameters | Name | Type | Mandatory| Description | | ----------- | ------ | ---- | -------- | - | packageName | string | Yes | Bundle name of the app.| + | packageName | string | Yes | Bundle name of the application.| - Return value | Type | Description | | ------------------------------------------ | -------------------------- | - | Promise<[Bundlestats](#bundlestats)> | Promise used to return the app information.| + | Promise<[Bundlestats](#bundlestats)> | Promise used to return the space information obtained.| - Example @@ -161,16 +183,20 @@ Asynchronously obtains app information. This API uses a promise to return the re getBundleStats(packageName: string, callback: AsyncCallback<BundleStats>): void -Asynchronously obtains app information. This API uses a callback to return the result. +Asynchronously obtains space information of an application. This API uses a callback to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER **System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics +**System API**: This is a system API and cannot be called by third-party applications. + - Parameters | Name | Type | Mandatory| Description | | -------- | --------------------------------------------------------- | ---- | ------------------------------------ | - | packageName | string | Yes | Bundle name of the app.| - | callback | callback:AsyncCallback<[Bundlestats](#bundlestats)> | Yes | Callback invoked to return the app information.| + | packageName | string | Yes | Bundle name of the application.| + | callback | callback:AsyncCallback<[Bundlestats](#bundlestats)> | Yes | Callback invoked to return the space information obtained.| - Example @@ -182,14 +208,310 @@ Asynchronously obtains app information. This API uses a callback to return the r }); ``` + + +## storagestatistics.getCurrentBundleStats9+ + +getCurrentBundleStats(): Promise + +Asynchronously obtains space information of the current third-party application. This API uses a promise to return the result. + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +- Return value + + | Type | Description | + | ------------------------------------------ | -------------------------- | + | Promise<[Bundlestats](#bundlestats)> | Promise used to return the space information obtained. | + +- Example + + ```js + let bundleStats = await storageStatistics.getCurrentBundleStats(); + console.info("getCurrentBundleStats successfully:"+ JSON.stringify(bundleStats)); + ``` + +## storagestatistics.getCurrentBundleStats9+ + +getCurrentBundleStats(callback: AsyncCallback): void + +Asynchronously obtains space information of the current third-party application. This API uses a callback to return the result. + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +- Parameters + + | Name | Type | Mandatory | Description | + | -------- | --------------------------------------------------------- | ---- | ------------------------------------ | + | callback | callback:AsyncCallback<[BundleStats](#bundlestats)> | Yes | Callback invoked to return the space information obtained. | + +- Example + + ```js + storagestatistics.getCurrentBundleStats(function(error, bundleStats){ + // Do something. + console.info("getCurrentBundleStats successfully:"+ JSON.stringify(bundleStats)); + }); + ``` + + + ## BundleStats9+ **System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics -### Attributes +- Attributes + +| Name | Type | Description | +| --------- | ------ | -------------- | +| appSize | number | Size of the application. | +| cacheSize | number | Cache size of the application. | +| dataSize | number | Total data size of the application.| + + + + +## storagestatistics.getTotalSize9+ + +getTotalSize(): Promise + +Obtains the total space of the built-in memory card. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +**System API**: This is a system API and cannot be called by third-party applications. + +- Return value + + | Type | Description | + | --------------------- | ------------------ | + | Promise<number> | Promise used to return the total space of the built-in memory card. | + +- Example + + ```js + let number = await storageStatistics.getTotalSize(); + console.info("getTotalSize successfully:"+ JSON.stringify(number)); + ``` + +## storagestatistics.getTotalSize9+ + +getTotalSize(callback: AsyncCallback): void + +Obtains the total space of the built-in memory card. This API uses a callback to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +**System API**: This is a system API and cannot be called by third-party applications. + +- Parameters + + | Name | Type | Mandatory | Description | + | -------- | ------------------------------------ | ---- | ------------------------ | + | callback | callback:AsyncCallback<number> | Yes | Callback invoked to return the total space of the built-in memory card.| + +- Example + + ```js + storagestatistics.getTotalSize(function(error, number){ + // Do something. + console.info("getTotalSize successfully:"+ JSON.stringify(number)); + }); + ``` + + +## storagestatistics.getFreeSize9+ + +getFreeSize(): Promise + +Obtains the available space of the built-in memory card. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +**System API**: This is a system API and cannot be called by third-party applications. + +- Return value + + | Type | Description | + | --------------------- | ------------------ | + | Promise<number> | Promise used to return the available space of the built-in memory card.| + +- Example + + ```js + let number = await storageStatistics.getFreeSize(); + console.info("getFreeSize successfully:"+ JSON.stringify(number)); + ``` + + +## storagestatistics.getFreeSize9+ + +getFreeSize(callback: AsyncCallback): void + +Obtains the available space of the built-in memory card. This API uses a callback to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +**System API**: This is a system API and cannot be called by third-party applications. + +- Parameters + + | Name | Type | Mandatory| Description | + | -------- | ------------------------------------ | ---- | ------------------------- | + | callback | callback:AsyncCallback<number> | Yes | Callback invoked to return the available space of the built-in memory card.| + +- Example + + ```js + storagestatistics.getFreeSize(function(error, number){ + // Do something. + console.info("getFreeSize successfully:"+ JSON.stringify(number)); + }); + ``` + + + +## storagestatistics.getSystemSize9+ + +getSystemSize(): Promise<number> + +Asynchronously obtains the system space. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +**System API**: This is a system API and cannot be called by third-party applications. + +- Return value + + | Type | Description | + | --------------------- | ---------------- | + | Promise<number> | Promise used to return the system space obtained.| + +- Example + + ```js + storagestatistics.getSystemSize().then(function(number){ + console.info("getSystemSize successfully:"+ number); + }).catch(function(err){ + console.info("getSystemSize failed with error:"+ err); + }); + ``` + +## storagestatistics.getSystemSize9+ + +getSystemSize(callback:AsyncCallback<number>):void + +Asynchronously obtains the system space. This API uses a callback to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +**System API**: This is a system API and cannot be called by third-party applications. + +- Parameters + + | Name | Type | Mandatory| Description | + | ---------- | ------------------------------------ | ---- | -------------------------- | + | callback | callback:AsyncCallback<number> | Yes | Callback used to return the system space obtained.| + +- Example + + ```js + storagestatistics.getSystemSize(function(error, number){ + // Do something. + console.info("getSystemSize successfully:"+ number); + }); + ``` + + + +## storagestatistics.getUserStorageStats9+ + +getUserStorageStats(userId?: string): Promise<StorageStats> + +Asynchronously obtains the space occupied by each type of user data. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +**System API**: This is a system API and cannot be called by third-party applications. + +- Parameters + + | Name | Type | Mandatory| Description| + | ---------- | ------ | ---- | ---- | + | userId | string | No | User ID.
-  Set this parameter to the ID of the user to be queried.
-  If no value is specified, information about the current user is queried.| + +- Return value + + | Type | Description | + | --------------------- | ---------------- | + | Promise<[StorageStats](#StorageStats)> | Promise used to return the information obtained.| + +- Example + + ```js + let userId = ""; + storagestatistics.getUserStorageStats(userId).then(function(StorageStats){ + console.info("getUserStorageStats successfully:"+ JSON.stringify(StorageStats)); + }).catch(function(err){ + console.info("getUserStorageStats failed with error:"+ err); + }); + ``` + +## storagestatistics.getUserStorageStats9+ + +getUserStorageStats(userId?: string, callback:AsyncCallback<StorageStats>):void + +Asynchronously obtains the space occupied by each type of user data. This API uses a callback to return the result. + +**Required permissions**: ohos.permission.STORAGE_MANAGER + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +**System API**: This is a system API and cannot be called by third-party applications. + +- Parameters + + | Name | Type | Mandatory| Description | + | ---------- | ------------------------------------ | ---- | -------------------------- | + | userId | string | No | User ID.
-  Set this parameter to the ID of the user to be queried.
-  If no value is specified, information about the current user is queried. | + | callback | callback:AsyncCallback<[StorageStats](#StorageStats)> | Yes | Callback invoked to return the information obtained.| + +- Example + + ```js + storagestatistics.getUserStorageStats(userId, function(error, StorageStats){ + // Do something. + console.info("getUserStorageStats successfully:"+ JSON.stringify(StorageStats)); + }); + ``` + + + +## StorageStats9+ + +**System capability**: SystemCapability.FileManagement.StorageService.SpatialStatistics + +- Attributes | Name | Type | Description | | --------- | ------ | -------------- | -| appSize9+ | number | Size of the app. | -| cacheSize9+ | number | Cache size of the app. | -| dataSize9+ | number | Total data size of the app.| +| total | number | Total space of the built-in memory card. | +| audio | number | Space occupied by audio data. | +| video | number | Space occupied by video data.| +| image | number | Space occupied by image data. | +| file | number | Space occupied by files. | +| app | number | Space occupied by application data.|