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 '@ohos.file.securityLabel'; 13``` 14 15## Guidelines 16 17Before 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: 18 19**Stage Model** 20 21 ```ts 22 import UIAbility from '@ohos.app.ability.UIAbility'; 23 import window from '@ohos.window'; 24 25 export default class EntryAbility extends UIAbility { 26 onWindowStageCreate(windowStage: window.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**Error codes** 68 69For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 70 71| ID| Error Message| 72| -------- | -------- | 73| 13900001 | Operation not permitted | 74| 13900007 | Arg list too long | 75| 13900015 | File exists | 76| 13900020 | Invalid argument | 77| 13900025 | No space left on device | 78| 13900037 | No data available | 79| 13900041 | Quota exceeded | 80| 13900042 | Unknown error | 81 82**Example** 83 84 ```ts 85 import { BusinessError } from '@ohos.base'; 86 let filePath = pathDir + '/test.txt'; 87 securityLabel.setSecurityLabel(filePath, "s0").then(() => { 88 console.info("setSecurityLabel successfully"); 89 }).catch((err: BusinessError) => { 90 console.info("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code); 91 }); 92 ``` 93 94## securityLabel.setSecurityLabel 95 96setSecurityLabel(path:string, type:DataLevel, callback: AsyncCallback<void>):void 97 98Sets a security label for a file in asynchronous mode. This API uses an asynchronous callback to return the result. 99 100**System capability**: SystemCapability.FileManagement.File.FileIO 101 102**Parameters** 103 104| Name | Type | Mandatory| Description | 105| --------- | ------------------------- | ---- | -------------------------------------------- | 106| path | string | Yes | Path of the target file. | 107| type | DataLevel | Yes | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.| 108| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 109 110**Error codes** 111 112For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 113 114| ID| Error Message| 115| -------- | -------- | 116| 13900001 | Operation not permitted | 117| 13900007 | Arg list too long | 118| 13900015 | File exists | 119| 13900020 | Invalid argument | 120| 13900025 | No space left on device | 121| 13900037 | No data available | 122| 13900041 | Quota exceeded | 123| 13900042 | Unknown error | 124 125**Example** 126 127 ```ts 128 import { BusinessError } from '@ohos.base'; 129 let filePath = pathDir + '/test.txt'; 130 securityLabel.setSecurityLabel(filePath, "s0", (err: BusinessError) => { 131 if (err) { 132 console.info("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code); 133 } else { 134 console.info("setSecurityLabel successfully."); 135 } 136 }); 137 ``` 138 139## securityLabel.setSecurityLabelSync 140 141setSecurityLabelSync(path:string, type:DataLevel):void 142 143Sets a security label for a file in synchronous mode. 144 145**System capability**: SystemCapability.FileManagement.File.FileIO 146 147**Parameters** 148 149| Name | Type | Mandatory| Description | 150| --------- | ------ | ---- | -------------------------------------------- | 151| path | string | Yes | Path of the target file. | 152| type | DataLevel | Yes | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.| 153 154**Error codes** 155 156For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 157 158| ID| Error Message| 159| -------- | -------- | 160| 13900001 | Operation not permitted | 161| 13900007 | Arg list too long | 162| 13900015 | File exists | 163| 13900020 | Invalid argument | 164| 13900025 | No space left on device | 165| 13900037 | No data available | 166| 13900041 | Quota exceeded | 167| 13900042 | Unknown error | 168 169**Example** 170 171```ts 172let filePath = pathDir + '/test.txt'; 173securityLabel.setSecurityLabelSync(filePath, "s0"); 174``` 175 176## securityLabel.getSecurityLabel 177 178getSecurityLabel(path:string):Promise<string> 179 180Obtains the security label of a file in asynchronous mode. This API uses a promise to return the result. 181 182**System capability**: SystemCapability.FileManagement.File.FileIO 183 184**Parameters** 185 186 | Name| Type | Mandatory| Description | 187 | ------ | ------ | ---- | -------- | 188 | path | string | Yes | Path of the target file.| 189 190**Return value** 191 192 | Type | Description | 193 | --------------------- | ------------ | 194 | Promise<string> | Security label obtained.| 195 196**Error codes** 197 198For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 199 200| ID| Error Message| 201| -------- | -------- | 202| 13900001 | Operation not permitted | 203| 13900007 | Arg list too long | 204| 13900015 | File exists | 205| 13900020 | Invalid argument | 206| 13900025 | No space left on device | 207| 13900037 | No data available | 208| 13900041 | Quota exceeded | 209| 13900042 | Unknown error | 210 211**Example** 212 213 ```ts 214 import { BusinessError } from '@ohos.base'; 215 let filePath = pathDir + '/test.txt'; 216 securityLabel.getSecurityLabel(filePath).then((type: string) => { 217 console.log("getSecurityLabel successfully, Label: " + type); 218 }).catch((err: BusinessError) => { 219 console.log("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code); 220 }); 221 ``` 222 223## securityLabel.getSecurityLabel 224 225getSecurityLabel(path:string, callback:AsyncCallback<string>): void 226 227Obtains the security label of a file in asynchronous mode. This API uses a callback to return the result. 228 229**System capability**: SystemCapability.FileManagement.File.FileIO 230 231**Parameters** 232 233 | Name | Type | Mandatory| Description | 234 | -------- | --------------------------- | ---- | -------------------------- | 235 | path | string | Yes | Path of the target file. | 236 | callback | AsyncCallback<string> | Yes | Callback invoked to return the security label obtained.| 237 238**Error codes** 239 240For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 241 242| ID| Error Message| 243| -------- | -------- | 244| 13900001 | Operation not permitted | 245| 13900007 | Arg list too long | 246| 13900015 | File exists | 247| 13900020 | Invalid argument | 248| 13900025 | No space left on device | 249| 13900037 | No data available | 250| 13900041 | Quota exceeded | 251| 13900042 | Unknown error | 252 253**Example** 254 255 ```ts 256 import { BusinessError } from '@ohos.base'; 257 let filePath = pathDir + '/test.txt'; 258 securityLabel.getSecurityLabel(filePath, (err: BusinessError, type: string) => { 259 if (err) { 260 console.log("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code); 261 } else { 262 console.log("getSecurityLabel successfully, Label: " + type); 263 } 264 }); 265 ``` 266 267## securityLabel.getSecurityLabelSync 268 269getSecurityLabelSync(path:string):string 270 271Obtains the security label of a file in synchronous mode. 272 273**System capability**: SystemCapability.FileManagement.File.FileIO 274 275**Parameters** 276 277| Name| Type | Mandatory| Description | 278| ------ | ------ | ---- | -------- | 279| path | string | Yes | Path of the target file.| 280 281**Return value** 282 283| Type | Description | 284| ------ | ------------ | 285| string | Security label obtained.| 286 287**Error codes** 288 289For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 290 291| ID| Error Message| 292| -------- | -------- | 293| 13900001 | Operation not permitted | 294| 13900007 | Arg list too long | 295| 13900015 | File exists | 296| 13900020 | Invalid argument | 297| 13900025 | No space left on device | 298| 13900037 | No data available | 299| 13900041 | Quota exceeded | 300| 13900042 | Unknown error | 301 302**Example** 303 304```ts 305let filePath = pathDir + '/test.txt'; 306let type = securityLabel.getSecurityLabelSync(filePath); 307console.log("getSecurityLabel successfully, Label: " + type); 308``` 309