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