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
9## Modules to Import
10
11```ts
12import { securityLabel } from '@kit.CoreFileKit';
13```
14
15## Guidelines
16
17Before using the APIs provided by this module to perform operations on a file or directory, obtain the application sandbox path of the file or directory as follows:
18
19
20  ```ts
21  import { UIAbility } from '@kit.AbilityKit';
22  import { window } from '@kit.ArkUI';
23
24  export default class EntryAbility extends UIAbility {
25    onWindowStageCreate(windowStage: window.WindowStage) {
26      let context = this.context;
27      let pathDir = context.filesDir;
28    }
29  }
30  ```
31
32For details about how to obtain the application sandbox path, see [Obtaining Application File Paths](../../application-models/application-context-stage.md#obtaining-application-file-paths).
33
34## DataLevel
35
36type DataLevel = 's0' | 's1' | 's2' | 's3' | 's4' |
37
38Defines the data security level.
39
40**System capability**: SystemCapability.FileManagement.File.FileIO
41
42## securityLabel.setSecurityLabel
43
44setSecurityLabel(path:string, type:DataLevel):Promise<void>
45
46Sets the security label for a file. The security label cannot be changed from a higher level to a lower level. This API uses a promise to return the result.
47
48**System capability**: SystemCapability.FileManagement.File.FileIO
49
50**Parameters**
51
52| Name   | Type      | Mandatory| Description                                        |
53| --------- | ------    | ---- | -------------------------------------------- |
54| path      | string    | Yes  | Path of the target file.                                    |
55| type      | [DataLevel](#datalevel) | Yes  | Security label to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.|
56
57**Return value**
58
59  | Type               | Description            |
60  | ------------------- | ---------------- |
61  | Promise<void> | Promise that returns no value.|
62
63**Error codes**
64
65For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes).
66
67| ID| Error Message|
68| -------- | -------- |
69| 13900001 | Operation not permitted |
70| 13900007 | Arg list too long |
71| 13900015 | File exists |
72| 13900020 | Invalid argument |
73| 13900025 | No space left on device |
74| 13900037 | No data available |
75| 13900041 | Quota exceeded |
76| 13900042 | Unknown error |
77
78**Example**
79
80  ```ts
81  import { BusinessError } from '@kit.BasicServicesKit';
82  let filePath = pathDir + '/test.txt';
83  securityLabel.setSecurityLabel(filePath, "s0").then(() => {
84    console.info("setSecurityLabel successfully");
85  }).catch((err: BusinessError) => {
86    console.error("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
87  });
88  ```
89
90## securityLabel.setSecurityLabel
91
92setSecurityLabel(path:string, type:DataLevel, callback: AsyncCallback<void>):void
93
94Sets the security label for a file. The security label cannot be changed from a higher level to a lower level. This API uses an asynchronous callback to return the result.
95
96**System capability**: SystemCapability.FileManagement.File.FileIO
97
98**Parameters**
99
100| Name   | Type                     | Mandatory| Description                                        |
101| --------- | ------------------------- | ---- | -------------------------------------------- |
102| path      | string                    | Yes  | Path of the target file.                                    |
103| type      | DataLevel                 | Yes  | Security label to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.|
104| callback  | AsyncCallback<void> | Yes  | Callback used to return the result.                  |
105
106**Error codes**
107
108For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes).
109
110| ID| Error Message|
111| -------- | -------- |
112| 13900001 | Operation not permitted |
113| 13900007 | Arg list too long |
114| 13900015 | File exists |
115| 13900020 | Invalid argument |
116| 13900025 | No space left on device |
117| 13900037 | No data available |
118| 13900041 | Quota exceeded |
119| 13900042 | Unknown error |
120
121**Example**
122
123  ```ts
124  import { BusinessError } from '@kit.BasicServicesKit';
125  let filePath = pathDir + '/test.txt';
126  securityLabel.setSecurityLabel(filePath, "s0", (err: BusinessError) => {
127    if (err) {
128      console.error("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
129    } else {
130      console.info("setSecurityLabel successfully.");
131    }
132  });
133  ```
134
135## securityLabel.setSecurityLabelSync
136
137setSecurityLabelSync(path:string, type:DataLevel):void
138
139Sets the security label for a file. The security label cannot be changed from a higher level to a lower level. This API returns the result synchronously.
140
141**System capability**: SystemCapability.FileManagement.File.FileIO
142
143**Parameters**
144
145| Name   | Type  | Mandatory| Description                                        |
146| --------- | ------ | ---- | -------------------------------------------- |
147| path      | string | Yes  | Path of the target file.                                    |
148| type      | DataLevel | Yes  | Security label to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.|
149
150**Error codes**
151
152For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes).
153
154| ID| Error Message|
155| -------- | -------- |
156| 13900001 | Operation not permitted |
157| 13900007 | Arg list too long |
158| 13900015 | File exists |
159| 13900020 | Invalid argument |
160| 13900025 | No space left on device |
161| 13900037 | No data available |
162| 13900041 | Quota exceeded |
163| 13900042 | Unknown error |
164
165**Example**
166
167```ts
168let filePath = pathDir + '/test.txt';
169securityLabel.setSecurityLabelSync(filePath, "s0");
170```
171
172## securityLabel.getSecurityLabel
173
174getSecurityLabel(path:string):Promise<string>
175
176Obtains the security label. If no security label has been set for the file, **s3** is returned by default. This API uses a promise to return the result.
177
178**System capability**: SystemCapability.FileManagement.File.FileIO
179
180**Parameters**
181
182  | Name| Type  | Mandatory| Description    |
183  | ------ | ------ | ---- | -------- |
184  | path   | string | Yes  | Path of the target file.|
185
186**Return value**
187
188  | Type                 | Description        |
189  | --------------------- | ------------ |
190  | Promise<string> | Security label obtained.|
191
192**Error codes**
193
194For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes).
195
196| ID| Error Message|
197| -------- | -------- |
198| 13900001 | Operation not permitted |
199| 13900007 | Arg list too long |
200| 13900015 | File exists |
201| 13900020 | Invalid argument |
202| 13900025 | No space left on device |
203| 13900037 | No data available |
204| 13900041 | Quota exceeded |
205| 13900042 | Unknown error |
206
207**Example**
208
209  ```ts
210  import { BusinessError } from '@kit.BasicServicesKit';
211  let filePath = pathDir + '/test.txt';
212  securityLabel.getSecurityLabel(filePath).then((type: string) => {
213    console.log("getSecurityLabel successfully, Label: " + type);
214  }).catch((err: BusinessError) => {
215    console.error("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
216  });
217  ```
218
219## securityLabel.getSecurityLabel
220
221getSecurityLabel(path:string, callback:AsyncCallback<string>): void
222
223Obtains the security label. If no security label has been set for the file, **s3** is returned by default. This API uses an asynchronous callback to return the result.
224
225**System capability**: SystemCapability.FileManagement.File.FileIO
226
227**Parameters**
228
229  | Name  | Type                       | Mandatory| Description                      |
230  | -------- | --------------------------- | ---- | -------------------------- |
231  | path     | string                      | Yes  | Path of the target file.                  |
232  | callback | AsyncCallback<string> | Yes  | Callback used to return the security label obtained.|
233
234**Error codes**
235
236For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes).
237
238| ID| Error Message|
239| -------- | -------- |
240| 13900001 | Operation not permitted |
241| 13900007 | Arg list too long |
242| 13900015 | File exists |
243| 13900020 | Invalid argument |
244| 13900025 | No space left on device |
245| 13900037 | No data available |
246| 13900041 | Quota exceeded |
247| 13900042 | Unknown error |
248
249**Example**
250
251  ```ts
252  import { BusinessError } from '@kit.BasicServicesKit';
253  let filePath = pathDir + '/test.txt';
254  securityLabel.getSecurityLabel(filePath, (err: BusinessError, type: string) => {
255    if (err) {
256      console.error("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
257    } else {
258      console.log("getSecurityLabel successfully, Label: " + type);
259    }
260  });
261  ```
262
263## securityLabel.getSecurityLabelSync
264
265getSecurityLabelSync(path:string):string
266
267Obtains the security label. If no security label has been set for the file, **s3** is returned by default. This API returns the result synchronously.
268
269**System capability**: SystemCapability.FileManagement.File.FileIO
270
271**Parameters**
272
273| Name| Type  | Mandatory| Description    |
274| ------ | ------ | ---- | -------- |
275| path   | string | Yes  | Path of the target file.|
276
277**Return value**
278
279| Type  | Description        |
280| ------ | ------------ |
281| string | Security label obtained.|
282
283**Error codes**
284
285For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes).
286
287| ID| Error Message|
288| -------- | -------- |
289| 13900001 | Operation not permitted |
290| 13900007 | Arg list too long |
291| 13900015 | File exists |
292| 13900020 | Invalid argument |
293| 13900025 | No space left on device |
294| 13900037 | No data available |
295| 13900041 | Quota exceeded |
296| 13900042 | Unknown error |
297
298**Example**
299
300```ts
301let filePath = pathDir + '/test.txt';
302let type = securityLabel.getSecurityLabelSync(filePath);
303console.log("getSecurityLabel successfully, Label: " + type);
304```
305