• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.file.environment (Directory Environment Capability)
2
3The **Environment** module provides APIs for obtaining the root directories of the storage and user files.
4
5> **NOTE**
6>
7> 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.
8
9## Modules to Import
10
11```ts
12import environment from '@ohos.file.environment';
13```
14
15## environment.getUserDownloadDir<sup>11+</sup>
16
17getUserDownloadDir(): string
18
19Obtains the sandbox path of the pre-authorized **Download** directory of the current user. This API is available only to certain devices.
20
21**Required permissions**: ohos.permission.READ_WRITE_DOWNLOAD_DIRECTORY
22
23**System capability**: SystemCapability.FileManagement.File.Environment.FolderObtain
24
25**Return value**
26
27| Type                 | Description                 |
28| --------------------- |---------------------|
29| string | Sandbox path of the pre-authorized **Download** directory obtained.|
30
31**Error codes**
32
33For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md).
34
35| ID   | Error Message      |
36|----------| --------- |
37| 201      | Permission verification failed, usually the result returned by VerifyAccessToken. |
38| 801      | Capability not supported. |
39| 13900042 | Unknown error |
40
41**Example**
42
43```ts
44import { BusinessError } from '@ohos.base';
45function getUserDownloadDirExample() {
46  try {
47    let path = environment.getUserDownloadDir();
48    console.log(`success to getUserDownloadDir: ${JSON.stringify(path)}`);
49  } catch (error) {
50    console.error(`failed to getUserDownloadDir because: ${JSON.stringify(error)}`);
51  }
52}
53```
54
55## environment.getUserDesktopDir<sup>11+</sup>
56
57getUserDesktopDir(): string
58
59Obtains the sandbox path of the pre-authorized **Desktop** directory of the current user. This API is available only to certain devices.
60
61**Required permissions**: ohos.permission.READ_WRITE_DESKTOP_DIRECTORY
62
63**System capability**: SystemCapability.FileManagement.File.Environment.FolderObtain
64
65**Return value**
66
67| Type                 | Description                 |
68| --------------------- |---------------------|
69| string | Sandbox path of the **Desktop** directory obtained.|
70
71**Error codes**
72
73For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md).
74
75| ID   | Error Message      |
76|----------| --------- |
77| 201      | Permission verification failed, usually the result returned by VerifyAccessToken. |
78| 801      | Capability not supported. |
79| 13900042 | Unknown error |
80
81**Example**
82
83```ts
84import { BusinessError } from '@ohos.base';
85function getUserDesktopDirExample() {
86  try {
87    let path = environment.getUserDesktopDir();
88    console.log(`success to getUserDesktopDir: ${JSON.stringify(path)}`);
89  } catch (error) {
90    console.error(`failed to getUserDesktopDir because: ${JSON.stringify(error)}`);
91  }
92}
93```
94
95## environment.getUserDocumentDir<sup>11+</sup>
96
97getUserDocumentDir(): string
98
99Obtains the sandbox path of the pre-authorized **Documents** directory of the current user. This API is available only to certain devices.
100
101**Required permissions**: ohos.permission.READ_WRITE_DOCUMENTS_DIRECTORY
102
103**System capability**: SystemCapability.FileManagement.File.Environment.FolderObtain
104
105**Return value**
106
107| Type                 | Description                 |
108| --------------------- |---------------------|
109| string | Sandbox path of the pre-authorized **Documents** directory obtained.|
110
111**Error codes**
112
113For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md).
114
115| ID   | Error Message      |
116|----------| --------- |
117| 201      | Permission verification failed, usually the result returned by VerifyAccessToken. |
118| 801      | Capability not supported. |
119| 13900042 | Unknown error |
120
121**Example**
122
123```ts
124import { BusinessError } from '@ohos.base';
125function getUserDocumentDirExample() {
126  try {
127    let path = environment.getUserDocumentDir();
128    console.log(`success to getUserDocumentDir: ${JSON.stringify(path)}`);
129  } catch (error) {
130    console.error(`failed to getUserDocumentDir because: ${JSON.stringify(error)}`);
131  }
132}
133```
134