提交 60a1ce31 编写于 作者: A Annie_wang

update docs

Signed-off-by: NAnnie_wang <annie.wangli@huawei.com>
上级 cc909914
...@@ -203,7 +203,6 @@ ...@@ -203,7 +203,6 @@
- [@system.cipher (Cipher Algorithm)](js-apis-system-cipher.md) - [@system.cipher (Cipher Algorithm)](js-apis-system-cipher.md)
- security - security
- [PermissionRequestResult](js-apis-permissionrequestresult.md) - [PermissionRequestResult](js-apis-permissionrequestresult.md)
- Data Management - Data Management
- [@ohos.data.dataAbility (DataAbility Predicates)](js-apis-data-ability.md) - [@ohos.data.dataAbility (DataAbility Predicates)](js-apis-data-ability.md)
- [@ohos.data.dataShare (DataShare)](js-apis-data-dataShare.md) - [@ohos.data.dataShare (DataShare)](js-apis-data-dataShare.md)
...@@ -215,11 +214,15 @@ ...@@ -215,11 +214,15 @@
- [@ohos.data.relationalStore (RDB Store)](js-apis-data-relationalStore.md) - [@ohos.data.relationalStore (RDB Store)](js-apis-data-relationalStore.md)
- [@ohos.data.ValuesBucket (Value Bucket)](js-apis-data-valuesBucket.md) - [@ohos.data.ValuesBucket (Value Bucket)](js-apis-data-valuesBucket.md)
- data/rdb - data/rdb
- [resultSet](js-apis-data-resultset.md) - [resultSet (Result Set)](js-apis-data-resultset.md)
- File Management - File Management
- [@ohos.environment](js-apis-environment.md) - [@ohos.file.environment (Directory Environment Capability)](js-apis-file-environment.md)
- [@ohos.file.fileAccess (User File Access and Management)](js-apis-fileAccess.md) - [@ohos.file.fileAccess (User File Access and Management)](js-apis-fileAccess.md)
- [@ohos.file.fileExtensionInfo (User File Extension Information)](js-apis-fileExtensionInfo.md) - [@ohos.file.fileExtensionInfo (User File Extension Information)](js-apis-fileExtensionInfo.md)
- [@ohos.file.fs (File Management)](js-apis-file-fs.md)
- [@ohos.file.hash (File Hash Processing)](js-apis-file-hash.md)
- [@ohos.file.securityLabel (Data Label)](js-apis-file-securityLabel.md)
- [@ohos.file.statvfs (File System Space Statistics)](js-apis-file-statvfs.md)
- [@ohos.filemanagement.userFileManager (User Data Management)](js-apis-userFileManager.md) - [@ohos.filemanagement.userFileManager (User Data Management)](js-apis-userFileManager.md)
- [@ohos.multimedia.medialibrary (Media Library Management)](js-apis-medialibrary.md) - [@ohos.multimedia.medialibrary (Media Library Management)](js-apis-medialibrary.md)
- [@ohos.storageStatistics (Application Storage Statistics)](js-apis-storage-statistics.md) - [@ohos.storageStatistics (Application Storage Statistics)](js-apis-storage-statistics.md)
......
# @ohos.environment (Directory Environment Capability) # @ohos.file.environment (Directory Environment Capability)
The **Environment** module provides APIs for obtaining the root directories of the storage and public files. The **Environment** module provides APIs for obtaining the root directories of the storage and public files.
> **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. > - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The APIs of this module are system APIs and cannot be called by third-party applications. > - The APIs of this module are system APIs and cannot be called by third-party applications.
> - The APIs of this module support processing of error codes. For details, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
## Modules to Import ## Modules to Import
```js ```js
import environment from '@ohos.environment'; import environment from '@ohos.file.environment';
``` ```
## environment.getStorageDataDir ## environment.getStorageDataDir
...@@ -30,10 +31,10 @@ Obtains the root directory of the storage. This API uses a promise to return the ...@@ -30,10 +31,10 @@ Obtains the root directory of the storage. This API uses a promise to return the
**Example** **Example**
```js ```js
environment.getStorageDataDir().then(function(path){ environment.getStorageDataDir().then((path) => {
console.info("getStorageDataDir successfully:"+ path); console.info("getStorageDataDir successfully, Path: " + path);
}).catch(function(error){ }).catch((err) => {
console.info("getStorageDataDir failed with error:"+ error); console.info("getStorageDataDir failed with error message: " + err.message + ", error code: " + err.code);
}); });
``` ```
...@@ -54,8 +55,12 @@ Obtains the root directory of the storage. This API uses an asynchronous callbac ...@@ -54,8 +55,12 @@ Obtains the root directory of the storage. This API uses an asynchronous callbac
**Example** **Example**
```js ```js
environment.getStorageDataDir(function(error, path){ environment.getStorageDataDir((err, path) => {
// do something if (err) {
console.info("getStorageDataDir failed with error message: " + err.message + ", error code: " + err.code);
} else {
console.info("getStorageDataDir successfully, Path: " + path);
}
}); });
``` ```
...@@ -76,10 +81,10 @@ Obtains the root directory of public files. This API uses a promise to return th ...@@ -76,10 +81,10 @@ Obtains the root directory of public files. This API uses a promise to return th
**Example** **Example**
```js ```js
environment.getUserDataDir().then(function(path){ environment.getUserDataDir().then((path) => {
console.info("getUserDataDir successfully:"+ path); console.info("getUserDataDir successfully, Path: " + path);
}).catch(function(error){ }).catch((err) => {
console.info("getUserDataDir failed with error:"+ error); console.info("getUserDataDir failed with error message: " + err.message + ", error code: " + err.code);
}); });
``` ```
...@@ -100,7 +105,11 @@ Obtains the root directory of public files. This API uses an asynchronous callba ...@@ -100,7 +105,11 @@ Obtains the root directory of public files. This API uses an asynchronous callba
**Example** **Example**
```js ```js
environment.getUserDataDir(function(error, path){ environment.getUserDataDir((err, path) => {
// do something if (err) {
console.info("getUserDataDir failed with error message: " + err.message + ", error code: " + err.code);
} else {
console.info("getUserDataDir successfully, Path: " + path);
}
}); });
``` ```
此差异已折叠。
# @ohos.file.hash (File Hash Processing)
The **fileHash** module implements hash processing on files.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The APIs of this module support processing of error codes. For details, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
## Modules to Import
```js
import Hash from '@ohos.file.hash';
```
## Guidelines
Before using the APIs provided by this module to perform operations on a file or directory, obtain the path of the file or directory in the application sandbox as follows:
**Stage Model**
```js
import UIAbility from '@ohos.app.ability.UIAbility';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
let context = this.context;
let pathDir = context.filesDir;
}
}
```
**FA Model**
```js
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
context.getFilesDir().then((data) => {
let pathDir = data;
})
```
For details about how to obtain the FA model context, see [Context](js-apis-inner-app-context.md#context).
## Hash.hash
hash(path: string, algorithm: string): Promise&lt;string&gt;
Calculates a hash value for a file. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------ | ---- | ------------------------------------------------------------ |
| path | string | Yes | Path of the file in the application sandbox. |
| algorithm | string | Yes | Algorithm used to calculate the hash value. The value can be **md5**, **sha1**, or **sha256**. **sha256** is recommended for security purposes.|
**Return value**
| Type | Description |
| --------------------- | -------------------------- |
| Promise&lt;string&gt; | Promise used to return the hash value. The hash value is a hexadecimal string consisting of digits and uppercase letters.|
**Example**
```js
let filePath = pathDir + "/test.txt";
Hash.hash(filePath, "sha256").then((str) => {
console.info("calculate file hash succeed:" + str);
}).catch((err) => {
console.info("calculate file hash failed with error message: " + err.message + ", error code: " + err.code);
});
```
## Hash.hash
hash(path: string, algorithm: string, callback: AsyncCallback&lt;string&gt;): void
Calculates a hash value for a file. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | --------------------------- | ---- | ------------------------------------------------------------ |
| path | string | Yes | Path of the file in the application sandbox. |
| algorithm | string | Yes | Algorithm used to calculate the hash value. The value can be **md5**, **sha1**, or **sha256**. **sha256** is recommended for security purposes.|
| callback | AsyncCallback&lt;string&gt; | Yes | Callback used to return the hash value obtained. The hash value is a hexadecimal string consisting of digits and uppercase letters.|
**Example**
```js
Hash.hash(filePath, "sha256", (err, str) => {
if (err) {
console.info("calculate file hash failed with error message: " + err.message + ", error code: " + err.code);
} else {
console.info("calculate file hash succeed:" + str);
}
});
```
# @ohos.file.securityLabel (Data Label)
The **securityLabel** module provides APIs for managing data security levels of files, including obtaining and setting file security levels.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>- The APIs of this module support processing of error codes. For details, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
## Modules to Import
```js
import securityLabel from '@ohos.file.securityLabel';
```
## Guidelines
Before using the APIs provided by this module to perform operations on files or directories, obtain the path of the file or directory in the application sandbox as follows:
**Stage Model**
```js
import UIAbility from '@ohos.app.ability.UIAbility';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
let context = this.context;
let pathDir = context.filesDir;
}
}
```
**FA Model**
```js
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
context.getFilesDir().then((data) => {
let pathDir = data;
})
```
For details about how to obtain the FA model context, see [Context](js-apis-inner-app-context.md#context).
## securityLabel.setSecurityLabel
setSecurityLabel(path:string, type:dataLevel):Promise&lt;void&gt;
Sets a security label for a file in asynchronous mode. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------ | ---- | -------------------------------------------- |
| path | string | Yes | Path of the target file. |
| type | dataLevel | Yes | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.|
**Return value**
| Type | Description |
| ------------------- | ---------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Example**
```js
securityLabel.setSecurityLabel(path, "s0").then(() => {
console.info("setSecurityLabel successfully");
}).catch((err) => {
console.info("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
});
```
## securityLabel.setSecurityLabel
setSecurityLabel(path:string, type:dataLevel, callback: AsyncCallback&lt;void&gt;):void
Sets a security label for a file in asynchronous mode. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------------------- | ---- | -------------------------------------------- |
| path | string | Yes | Path of the target file. |
| type | dataLevel | Yes | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. |
**Example**
```js
securityLabel.setSecurityLabel(path, "s0", (err) => {
if (err) {
console.info("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
} else {
console.info("setSecurityLabel successfully.");
}
});
```
## securityLabel.setSecurityLabelSync
setSecurityLabelSync(path:string, type:dataLevel):void
Sets a security label for a file in synchronous mode.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------ | ---- | -------------------------------------------- |
| path | string | Yes | Path of the target file. |
| type | dataLevel | Yes | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.|
**Example**
```js
securityLabel.setSecurityLabelSync(path, "s0");
```
## securityLabel.getSecurityLabel
getSecurityLabel(path:string):Promise&lt;string&gt;
Obtains the security label of a file in asynchronous mode. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------- |
| path | string | Yes | Path of the target file.|
**Return value**
| Type | Description |
| --------------------- | ------------ |
| Promise&lt;string&gt; | Security label obtained.|
**Example**
```js
securityLabel.getSecurityLabel(path).then((type) => {
console.log("getSecurityLabel successfully, Label: " + type);
}).catch((err) => {
console.log("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
});
```
## securityLabel.getSecurityLabel
getSecurityLabel(path:string, callback:AsyncCallback&lt;string&gt;): void
Obtains the security label of a file in asynchronous mode. This API uses a callback to return the result.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | -------------------------- |
| path | string | Yes | Path of the target file. |
| callback | AsyncCallback&lt;string&gt; | Yes | Callback invoked to return the security label obtained.|
**Example**
```js
securityLabel.getSecurityLabel(path, (err, type) => {
if (err) {
console.log("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
} else {
console.log("getSecurityLabel successfully, Label: " + type);
}
});
```
## securityLabel.getSecurityLabelSync
getSecurityLabelSync(path:string):string
Obtains the security label of a file in synchronous mode.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------- |
| path | string | Yes | Path of the target file.|
**Return value**
| Type | Description |
| ------ | ------------ |
| string | Security label obtained.|
**Example**
```js
let type = securityLabel.getSecurityLabelSync(path);
console.log("getSecurityLabel successfully, Label: " + type);
```
# @ohos.file.statvfs (File System Space Statistics)
The **statfs** module provides APIs for obtaining file system information, including the total number of bytes and the number of idle bytes of the file system.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The APIs of this module support processing of error codes. For details, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
## Modules to Import
```js
import statvfs from '@ohos.file.statvfs';
```
## statvfs.getFreeSize
getFreeSize(path:string):Promise&lt;number&gt;
Obtains the number of free bytes of the specified file system in asynchronous mode. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------------------- |
| path | string | Yes | File path of the file system.|
**Return value**
| Type | Description |
| --------------------- | -------------- |
| Promise&lt;number&gt; | Promise used to return the number of free bytes obtained.|
**Example**
```js
let path = "/dev";
statfs.getFreeSize(path).then((number) => {
console.info("getFreeSize promise successfully, Size: " + number);
}).catch((err) => {
console.info("getFreeSize failed with error message: " + err.message + ", error code: " + err.code);
});
```
## statfs.getFreeSize
getFreeSize(path:string, callback:AsyncCallback&lt;number&gt;): void
Obtains the number of free bytes of the specified file system in asynchronous mode. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ---------------------------- |
| path | string | Yes | File path of the file system.|
| callback | AsyncCallback&lt;number&gt; | Yes | Callback invoked to return the number of free bytes obtained.|
**Example**
```js
let path = "/dev";
statfs.getFreeSize(path, (err, number) => {
if (err) {
console.info("getFreeSize failed with error message: " + err.message + ", error code: " + err.code);
} else {
console.info("getFreeSize callback successfully, Size: " + number);
}
});
```
## statfs.getTotalSize
getTotalSize(path: string): Promise&lt;number&gt;
Obtains the total number of bytes of the specified file system in asynchronous mode. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name| Type | Mandatory| Description |
| ---- | ------ | ---- | ---------------------------- |
| path | string | Yes | File path of the file system.|
**Return value**
| Type | Description |
| --------------------- | ------------ |
| Promise&lt;number&gt; | Promise used to return the total number of bytes obtained.|
**Example**
```js
let path = "/dev";
statfs.getTotalSize(path).then((number) => {
console.info("getTotalSize promise successfully, Size: " + number);
}).catch((err) => {
console.info("getTotalSize with error message: " + err.message + ", error code: " + err.code);
});
```
## statfs.getTotalSize
getTotalSize(path: string, callback: AsyncCallback&lt;number&gt;): void
Obtains the total number of bytes of the specified file system in asynchronous mode. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.File.FileIO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ---------------------------- |
| path | string | Yes | File path of the file system.|
| callback | AsyncCallback&lt;number&gt; | Yes | Callback invoked to return the total number of bytes obtained. |
**Example**
```js
let path = "/dev";
statfs.getTotalSize(path, (err, number) => {
if (err) {
console.info("getTotalSize with error message: " + err.message + ", error code: " + err.code);
} else {
console.info("getTotalSize promise successfully, Size: " + number);
}
});
```
...@@ -4,7 +4,9 @@ The **statfs** module provides APIs for obtaining file system information, inclu ...@@ -4,7 +4,9 @@ The **statfs** module provides APIs for obtaining file system information, inclu
> **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. > - 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.
>
> - The APIs provided by this module are deprecated since API version 9. You are advised to use [@ohos.file.statvfs](js-apis-file-statvfs.md).
## Modules to Import ## Modules to Import
...@@ -21,15 +23,15 @@ Obtains the number of free bytes of the specified file system in asynchronous mo ...@@ -21,15 +23,15 @@ Obtains the number of free bytes of the specified file system in asynchronous mo
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------------------- | | ------ | ------ | ---- | ---------------------------- |
| path | string | Yes | File path of the file system.| | path | string | Yes | File path of the file system.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| --------------------- | -------------- | | --------------------- | -------------- |
| Promise&lt;number&gt; | Promise used to return the number of free bytes obtained.| | Promise&lt;number&gt; | Promise used to return the number of free bytes obtained.|
**Example** **Example**
...@@ -52,10 +54,10 @@ Obtains the number of free bytes of the specified file system in asynchronous mo ...@@ -52,10 +54,10 @@ Obtains the number of free bytes of the specified file system in asynchronous mo
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ---------------------------- | | -------- | --------------------------- | ---- | ---------------------------- |
| path | string | Yes | File path of the file system.| | path | string | Yes | File path of the file system.|
| callback | AsyncCallback&lt;number&gt; | Yes | Callback invoked to return the number of free bytes obtained.| | callback | AsyncCallback&lt;number&gt; | Yes | Callback invoked to return the number of free bytes obtained.|
**Example** **Example**
...@@ -79,15 +81,15 @@ Obtains the total number of bytes of the specified file system in asynchronous m ...@@ -79,15 +81,15 @@ Obtains the total number of bytes of the specified file system in asynchronous m
**Parameters** **Parameters**
| Name| Type | Mandatory| Description | | Name| Type | Mandatory| Description |
| ---- | ------ | ---- | ---------------------------- | | ---- | ------ | ---- | ---------------------------- |
| path | string | Yes | File path of the file system.| | path | string | Yes | File path of the file system.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| --------------------- | ------------ | | --------------------- | ------------ |
| Promise&lt;number&gt; | Promise used to return the total number of bytes obtained.| | Promise&lt;number&gt; | Promise used to return the total number of bytes obtained.|
**Example** **Example**
...@@ -110,10 +112,10 @@ Obtains the total number of bytes of the specified file system in asynchronous m ...@@ -110,10 +112,10 @@ Obtains the total number of bytes of the specified file system in asynchronous m
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ---------------------------- | | -------- | --------------------------- | ---- | ---------------------------- |
| path | string | Yes | File path of the file system.| | path | string | Yes | File path of the file system.|
| callback | AsyncCallback&lt;number&gt; | Yes | Callback invoked to return the total number of bytes obtained. | | callback | AsyncCallback&lt;number&gt; | Yes | Callback invoked to return the total number of bytes obtained. |
**Example** **Example**
......
# File Management Error Codes # File Management Error Codes
The error codes of the file management subsystem consist of the following: The error codes of the file management subsystem consist of the following:<br>- Basic file I/O error codes<br>- User data management error codes<br>- User file access error codes<br>- Spatial statistics error codes
- Basic file I/O error codes
- User data management error codes
- User file access error codes
- Spatial statistics error codes
## Basic File I/O Error Codes ## Basic File I/O Error Codes
...@@ -719,3 +714,41 @@ Fail to notify agent ...@@ -719,3 +714,41 @@ Fail to notify agent
**Solution** **Solution**
Check whether the client is normal. Check whether the client is normal.
## Error Code Adaptation
The APIs provided by the file management subsystem support exception handling.
Sample code for exception handling in a synchronous API:
```js
import fs from '@ohos.file.fs'
try {
let file = fs.openSync(path, fs.OpenMode.READ_ONLY);
} catch (err) {
console.error("openSync errCode:" + err.code + ", errMessage:" + err.message);
}
```
Sample code for exception handling in an asynchronous API (promise):
```js
import fs from '@ohos.file.fs'
try {
let file = await fs.open(path, fs.OpenMode.READ_ONLY);
} catch (err) {
console.error("open promise errCode:" + err.code + ", errMessage:" + err.message);
}
```
Sample code for exception handling in an asynchronous API (callback):
```js
import fs from '@ohos.file.fs'
try {
fs.open(path, fs.OpenMode.READ_ONLY, function(e, file){ // Asynchronous thread (such as the system call) errors are obtained via a callback.
if (e) {
console.error("open in async errCode:" + e.code + ", errMessage:" + e.message);
}
});
} catch (err) {// Main thread errors (such as invalid parameters) are obtained by try catch.
console.error("open callback errCode:" + err.code + ", errMessage:" + err.message);
}
```
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册