• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.file.securityLabel (Data Label)
2
3The **securityLabel** module provides APIs for managing data security levels of files, including obtaining and setting file security levels.
4
5> **NOTE**
6>
7> - 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.
8> - The APIs of this module support processing of error codes. For details, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
9
10## Modules to Import
11
12```js
13import securityLabel from '@ohos.file.securityLabel';
14```
15
16## Guidelines
17
18Before 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:
19
20**Stage Model**
21
22 ```js
23import UIAbility from '@ohos.app.ability.UIAbility';
24
25export default class EntryAbility extends UIAbility {
26    onWindowStageCreate(windowStage) {
27        let context = this.context;
28        let pathDir = context.filesDir;
29    }
30}
31 ```
32
33**FA Model**
34
35 ```js
36 import featureAbility from '@ohos.ability.featureAbility';
37
38 let context = featureAbility.getContext();
39 context.getFilesDir().then((data) => {
40      let pathDir = data;
41 })
42 ```
43
44For details about how to obtain the FA model context, see [Context](js-apis-inner-app-context.md#context).
45
46## securityLabel.setSecurityLabel
47
48setSecurityLabel(path:string, type:DataLevel):Promise<void>
49
50Sets a security label for a file in asynchronous mode. This API uses a promise to return the result.
51
52**System capability**: SystemCapability.FileManagement.File.FileIO
53
54**Parameters**
55
56| Name   | Type      | Mandatory| Description                                        |
57| --------- | ------    | ---- | -------------------------------------------- |
58| path      | string    | Yes  | Path of the target file.                                    |
59| type      | DataLevel | Yes  | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.|
60
61**Return value**
62
63| Type               | Description            |
64| ------------------- | ---------------- |
65| Promise<void> | Promise that returns no value.|
66
67**Example**
68
69  ```js
70  let filePath = pathDir + '/test.txt';
71  securityLabel.setSecurityLabel(filePath, "s0").then(() => {
72      console.info("setSecurityLabel successfully");
73  }).catch((err) => {
74      console.info("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
75  });
76  ```
77
78## securityLabel.setSecurityLabel
79
80setSecurityLabel(path:string, type:DataLevel, callback: AsyncCallback<void>):void
81
82Sets a security label for a file in asynchronous mode. This API uses an asynchronous callback to return the result.
83
84**System capability**: SystemCapability.FileManagement.File.FileIO
85
86**Parameters**
87
88| Name   | Type                     | Mandatory| Description                                        |
89| --------- | ------------------------- | ---- | -------------------------------------------- |
90| path      | string                    | Yes  | Path of the target file.                                    |
91| type      | DataLevel                 | Yes  | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.|
92| callback  | AsyncCallback<void> | Yes  | Callback invoked to return the result.                  |
93
94**Example**
95
96  ```js
97  let filePath = pathDir + '/test.txt';
98  securityLabel.setSecurityLabel(filePath, "s0", (err) => {
99    if (err) {
100      console.info("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
101    } else {
102      console.info("setSecurityLabel successfully.");
103    }
104  });
105  ```
106
107## securityLabel.setSecurityLabelSync
108
109setSecurityLabelSync(path:string, type:DataLevel):void
110
111Sets a security label for a file in synchronous mode.
112
113**System capability**: SystemCapability.FileManagement.File.FileIO
114
115**Parameters**
116
117| Name   | Type  | Mandatory| Description                                        |
118| --------- | ------ | ---- | -------------------------------------------- |
119| path      | string | Yes  | Path of the target file.                                    |
120| type      | DataLevel | Yes  | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.|
121
122**Example**
123
124```js
125let filePath = pathDir + '/test.txt';
126securityLabel.setSecurityLabelSync(filePath, "s0");
127```
128
129## securityLabel.getSecurityLabel
130
131getSecurityLabel(path:string):Promise<string>
132
133Obtains the security label of a file in asynchronous mode. This API uses a promise to return the result.
134
135**System capability**: SystemCapability.FileManagement.File.FileIO
136
137**Parameters**
138
139| Name| Type  | Mandatory| Description    |
140| ------ | ------ | ---- | -------- |
141| path   | string | Yes  | Path of the target file.|
142
143**Return value**
144
145| Type                 | Description        |
146| --------------------- | ------------ |
147| Promise<string> | Security label obtained.|
148
149**Example**
150
151  ```js
152  let filePath = pathDir + '/test.txt';
153  securityLabel.getSecurityLabel(filePath).then((type) => {
154      console.log("getSecurityLabel successfully, Label: " + type);
155  }).catch((err) => {
156      console.log("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
157  });
158  ```
159
160## securityLabel.getSecurityLabel
161
162getSecurityLabel(path:string, callback:AsyncCallback<string>): void
163
164Obtains the security label of a file in asynchronous mode. This API uses a callback to return the result.
165
166**System capability**: SystemCapability.FileManagement.File.FileIO
167
168**Parameters**
169
170| Name  | Type                       | Mandatory| Description                      |
171| -------- | --------------------------- | ---- | -------------------------- |
172| path     | string                      | Yes  | Path of the target file.                  |
173| callback | AsyncCallback<string> | Yes  | Callback invoked to return the security label obtained.|
174
175**Example**
176
177  ```js
178  let filePath = pathDir + '/test.txt';
179  securityLabel.getSecurityLabel(filePath, (err, type) => {
180    if (err) {
181      console.log("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
182    } else {
183      console.log("getSecurityLabel successfully, Label: " + type);
184    }
185  });
186  ```
187## securityLabel.getSecurityLabelSync
188
189getSecurityLabelSync(path:string):string
190
191Obtains the security label of a file in synchronous mode.
192
193**System capability**: SystemCapability.FileManagement.File.FileIO
194
195**Parameters**
196
197| Name| Type  | Mandatory| Description    |
198| ------ | ------ | ---- | -------- |
199| path   | string | Yes  | Path of the target file.|
200
201**Return value**
202
203| Type  | Description        |
204| ------ | ------------ |
205| string | Security label obtained.|
206
207**Example**
208
209```js
210let filePath = pathDir + '/test.txt';
211let type = securityLabel.getSecurityLabelSync(filePath);
212console.log("getSecurityLabel successfully, Label: " + type);
213```
214