1# @ohos.file.environment (Directory Environment Capability) (System API) 2<!--Kit: Core File Kit--> 3<!--Subsystem: FileManagement--> 4<!--Owner: @wangke25; @gsl_1234; @wuchengjun5--> 5<!--Designer: @gsl_1234; @wangke25--> 6<!--Tester: @liuhonggang123; @yue-ye2; @juxiaopang--> 7<!--Adviser: @foryourself--> 8 9The **Environment** module provides APIs for obtaining the root directories of the storage and user files. 10 11> **NOTE** 12> 13> - 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. 14> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.file.environment](js-apis-file-environment-sys.md). 15 16## Modules to Import 17 18```ts 19import { Environment } from '@kit.CoreFileKit'; 20``` 21 22## environment.getStorageDataDir 23 24getStorageDataDir():Promise<string> 25 26Obtains the root directory of the memory. This API uses a promise to return the result. 27 28**System capability**: SystemCapability.FileManagement.File.Environment 29 30**System API**: This is a system API. 31 32**Return value** 33 34| Type | Description | 35| --------------------- | ---------------- | 36| Promise<string> | Promise used to return the root directory of the memory.| 37 38**Error codes** 39 40For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md) and [Universal Error Codes](../errorcode-universal.md). 41| ID | Error Message | 42| ---------------------------- | ---------- | 43| 202 | The caller is not a system application | 44| 13900020 | Invalid argument | 45| 13900042 | Unknown error | 46 47**Example** 48 49 ```ts 50 import { BusinessError } from '@kit.BasicServicesKit'; 51 Environment.getStorageDataDir().then((path: string) => { 52 console.info("getStorageDataDir successfully, Path: " + path); 53 }).catch((err: BusinessError) => { 54 console.error("getStorageDataDir failed with error message: " + err.message + ", error code: " + err.code); 55 }); 56 ``` 57 58## environment.getStorageDataDir 59 60getStorageDataDir(callback:AsyncCallback<string>):void 61 62Obtains the root directory of the memory. This API uses an asynchronous callback to return the result. 63 64**System capability**: SystemCapability.FileManagement.File.Environment 65 66**System API**: This is a system API. 67 68**Parameters** 69 70| Name | Type | Mandatory| Description | 71| -------- | --------------------------- | ---- | -------------------------------- | 72| callback | AsyncCallback<string> | Yes | Callback used to return the root directory of the memory.| 73 74**Error codes** 75 76For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md) and [Universal Error Codes](../errorcode-universal.md). 77| ID | Error Message | 78| ---------------------------- | ---------- | 79| 202 | The caller is not a system application | 80| 13900020 | Invalid argument | 81| 13900042 | Unknown error | 82 83**Example** 84 85 ```ts 86 import { BusinessError } from '@kit.BasicServicesKit'; 87 Environment.getStorageDataDir((err: BusinessError, path: string) => { 88 if (err) { 89 console.error("getStorageDataDir failed with error message: " + err.message + ", error code: " + err.code); 90 } else { 91 console.info("getStorageDataDir successfully, Path: " + path); 92 } 93 }); 94 ``` 95 96## environment.getUserDataDir 97 98getUserDataDir():Promise<string> 99 100Obtains the root directory of user files. This API uses a promise to return the result. 101 102**System capability**: SystemCapability.FileManagement.File.Environment 103 104**System API**: This is a system API. 105 106**Return value** 107 108| Type | Description | 109| --------------------- | ------------------ | 110| Promise<string> | Promise used to return the root directory of user files.| 111 112**Error codes** 113 114For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md) and [Universal Error Codes](../errorcode-universal.md). 115| ID | Error Message | 116| ---------------------------- | ---------- | 117| 202 | The caller is not a system application | 118| 13900020 | Invalid argument | 119| 13900042 | Unknown error | 120 121**Example** 122 123 ```ts 124 import { BusinessError } from '@kit.BasicServicesKit'; 125 Environment.getUserDataDir().then((path: string) => { 126 console.info("getUserDataDir successfully, Path: " + path); 127 }).catch((err: BusinessError) => { 128 console.error("getUserDataDir failed with error message: " + err.message + ", error code: " + err.code); 129 }); 130 ``` 131 132## environment.getUserDataDir 133 134getUserDataDir(callback:AsyncCallback<string>): void 135 136Obtains the root directory of user files. This API uses an asynchronous callback to return the result. 137 138**System capability**: SystemCapability.FileManagement.File.Environment 139 140**System API**: This is a system API. 141 142**Parameters** 143 144| Name | Type | Mandatory| Description | 145| -------- | --------------------------- | ---- | -------------------------------- | 146| callback | AsyncCallback<string> | Yes | Callback used to return the root directory of user files.| 147 148**Error codes** 149 150For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md) and [Universal Error Codes](../errorcode-universal.md). 151| ID | Error Message | 152| ---------------------------- | ---------- | 153| 202 | The caller is not a system application | 154| 13900020 | Invalid argument | 155| 13900042 | Unknown error | 156 157**Example** 158 159 ```ts 160 import { BusinessError } from '@kit.BasicServicesKit'; 161 Environment.getUserDataDir((err: BusinessError, path: string) => { 162 if (err) { 163 console.error("getUserDataDir failed with error message: " + err.message + ", error code: " + err.code); 164 } else { 165 console.info("getUserDataDir successfully, Path: " + path); 166 } 167 }); 168 ``` 169 170## environment.getExternalStorageDir<sup>11+</sup> 171 172getExternalStorageDir(): string 173 174Obtains the sandbox path of the root directory of an external storage card. This API is available only to the devices with the SystemCapability.FileManagement.File.Environment.FolderObtain system capability. 175 176**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER 177 178**System capability**: SystemCapability.FileManagement.File.Environment.FolderObtain 179 180**System API**: This is a system API. 181 182**Return value** 183 184| Type | Description | 185| --------------------- |---------------| 186| string | Sandbox path of the root directory obtained.| 187 188**Error codes** 189 190For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md) and [Universal Error Codes](../errorcode-universal.md). 191 192| ID | Error Message | 193| ---------------------------- | --------- | 194| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 195| 202 | Permission verification failed, application which is not a system application uses system API. | 196| 801 | Capability not supported. | 197| 13900042 | Unknown error | 198 199**Example** 200 201```ts 202import { BusinessError } from '@kit.BasicServicesKit'; 203function getExternalStorageDirExample() { 204 try { 205 let path = Environment.getExternalStorageDir(); 206 console.info(`Succeeded in getExternalStorageDir, path is ${path}`); 207 } catch (err) { 208 console.error(`Failed to getExternalStorageDir. Code: ${err.code}, message: ${err.message}`); 209 } 210} 211``` 212 213## environment.getUserHomeDir<sup>11+</sup> 214 215getUserHomeDir(): string 216 217Obtains the sandbox path of the built-in card directory of the current user. This API is available only to the devices with the SystemCapability.FileManagement.File.Environment.FolderObtain system capability. 218 219**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER 220 221**System capability**: SystemCapability.FileManagement.File.Environment.FolderObtain 222 223**System API**: This is a system API. 224 225**Return value** 226 227| Type | Description | 228| --------------------- |-----------------| 229| string | Sandbox path of the built-in card directory obtained.| 230 231**Error codes** 232 233For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md) and [Universal Error Codes](../errorcode-universal.md). 234 235| ID | Error Message | 236| ---------------------------- | --------- | 237| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 238| 202 | Permission verification failed, application which is not a system application uses system API. | 239| 801 | Capability not supported. | 240| 13900042 | Unknown error | 241 242**Example** 243 244```ts 245import { BusinessError } from '@kit.BasicServicesKit'; 246function getUserHomeDirExample() { 247 try { 248 let path = Environment.getUserHomeDir(); 249 console.info(`Succeeded in getUserHomeDir, path is ${path}`); 250 } catch (err) { 251 console.error(`Failed to getUserHomeDir. Code: ${err.code}, message: ${err.message}`); 252 } 253} 254``` 255