• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.systemParameterEnhance (System Parameter) (System API)
2
3The **SystemParameter** module provides system services with easy access to key-value pairs. You can use the APIs provided by this module to describe the service status and change the service behavior. The basic operation primitives are get and set. You can obtain the values of system parameters through getters and modify the values through setters.
4For details about the system parameter design principles and definitions, see [Parameter Management](../../../device-dev/subsystems/subsys-boot-init-sysparam.md).
5
6> **NOTE**
7>
8> - 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.
9> - The APIs provided by this module are system APIs.
10> - Third-party applications cannot use the APIs provided by this module, because system parameters each require specific discretionary access control (DAC) and mandatory access control (MAC) permissions.
11
12## Modules to Import
13
14```ts
15import systemparameter from '@ohos.systemParameterEnhance';
16```
17
18## systemparameter.getSync
19
20getSync(key: string, def?: string): string
21
22Obtains the value of the system parameter with the specified key.
23
24**System capability**: SystemCapability.Startup.SystemInfo
25
26**Parameters**
27
28| Name| Type| Mandatory| Description|
29| -------- | -------- | -------- | -------- |
30| key | string | Yes| Key of the system parameter.|
31| def | string | No| Default value of the system parameter.<br> It works only when the system parameter does not exist.<br> The value can be **undefined** or any custom value.|
32
33**Return value**
34
35| Type| Description|
36| -------- | -------- |
37| string | Value of the system parameter.<br> If the specified key exists, the set value is returned.<br> If the specified key does not exist and **def** is set to a valid value, the set value is returned. If the specified key does not exist and **def** is set to an invalid value (such as **undefined**) or is not set, an exception is thrown.|
38
39**Error codes**
40
41| ID| Error Message                                                    |
42| -------- | ------------------------------------------------------------ |
43| 14700101 | if key is not found                                          |
44| 14700103 | if permission denied                                         |
45| 14700104 | if system internal error                                     |
46
47For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
48
49**Example**
50
51```ts
52try {
53    let info: string = systemparameter.getSync("const.ohos.apiversion");
54    console.log(JSON.stringify(info));
55} catch(e) {
56    console.log("getSync unexpected error: " + e);
57}
58```
59
60## systemparameter.get
61
62get(key: string, callback: AsyncCallback&lt;string&gt;): void
63
64Obtains the value of the system parameter with the specified key.
65
66**System capability**: SystemCapability.Startup.SystemInfo
67
68**Parameters**
69
70| Name| Type| Mandatory| Description|
71| -------- | -------- | -------- | -------- |
72| key | string | Yes| Key of the system parameter.|
73| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the result.|
74
75**Error codes**
76
77| ID| Error Message                                                    |
78| -------- | ------------------------------------------------------------ |
79| 14700101 | if key is not found                                          |
80| 14700103 | if permission denied                                         |
81| 14700104 | if system internal error                                     |
82
83For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
84
85**Example**
86
87```ts
88import { BusinessError } from '@ohos.base';
89
90try {
91    systemparameter.get("const.ohos.apiversion", (err: BusinessError, data: string) => {
92    if (err == undefined) {
93        console.log("get test.parameter.key value success:" + data)
94    } else {
95        console.log(" get test.parameter.key value err:" + err.code)
96    }});
97} catch(e) {
98    console.log("get unexpected error: " + e);
99}
100```
101
102## systemparameter.get
103
104get(key: string, def: string, callback: AsyncCallback&lt;string&gt;): void
105
106Obtains the value of the system parameter with the specified key. This API uses an asynchronous callback to return the result.
107
108**System capability**: SystemCapability.Startup.SystemInfo
109
110**Parameters**
111
112| Name| Type| Mandatory| Description|
113| -------- | -------- | -------- | -------- |
114| key | string | Yes| Key of the system parameter.|
115| def | string | Yes| Default value.|
116| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the result.|
117
118**Error codes**
119
120| ID| Error Message                                                    |
121| -------- | ------------------------------------------------------------ |
122| 14700101 | if key is not found                                          |
123| 14700103 | if permission denied                                         |
124| 14700104 | if system internal error                                     |
125
126For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
127
128**Example**
129
130```ts
131import { BusinessError } from '@ohos.base';
132
133try {
134    systemparameter.get("const.ohos.apiversion", "default", (err: BusinessError, data: string) => {
135        if (err == undefined) {
136            console.log("get test.parameter.key value success:" + data)
137        } else {
138            console.log(" get test.parameter.key value err:" + err.code)
139        }
140    });
141} catch(e) {
142    console.log("get unexpected error:" + e)
143}
144```
145
146## systemparameter.get
147
148get(key: string, def?: string): Promise&lt;string&gt;
149
150Obtains the value of the system parameter with the specified key. This API uses a promise to return the result.
151
152**System capability**: SystemCapability.Startup.SystemInfo
153
154**Parameters**
155
156| Name| Type| Mandatory| Description|
157| -------- | -------- | -------- | -------- |
158| key | string | Yes| Key of the system parameter.|
159| def | string | No| Default value of the system parameter.<br> It works only when the system parameter does not exist.<br> The value can be **undefined** or any custom value.|
160
161**Return value**
162
163| Type| Description|
164| -------- | -------- |
165| Promise&lt;string&gt; | Promise used to return the execution result.|
166
167**Error codes**
168
169| ID| Error Message                                                    |
170| -------- | ------------------------------------------------------------ |
171| 14700101 | if key is not found                                          |
172| 14700103 | if permission denied                                         |
173| 14700104 | if system internal error                                     |
174
175For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
176
177**Example**
178
179```ts
180import { BusinessError } from '@ohos.base';
181
182try {
183    let p: Promise<string> = systemparameter.get("const.ohos.apiversion");
184    p.then((value: string) => {
185        console.log("get test.parameter.key success: " + value);
186    }).catch((err: BusinessError) => {
187        console.log("get test.parameter.key error: " + err.code);
188    });
189} catch(e) {
190    console.log("get unexpected error: " + e);
191}
192```
193
194## systemparameter.setSync
195
196setSync(key: string, value: string): void
197
198Sets a value for the system parameter with the specified key.
199
200**System capability**: SystemCapability.Startup.SystemInfo
201
202**Parameters**
203
204| Name| Type| Mandatory| Description|
205| -------- | -------- | -------- | -------- |
206| key | string | Yes| Key of the system parameter.|
207| value | string | Yes| Value of the system parameter to set.|
208
209**Error codes**
210
211| ID| Error Message                                                    |
212| -------- | ------------------------------------------------------------ |
213| 14700102 | if value is invalid                                          |
214| 14700103 | if permission denied                                         |
215| 14700104 | if system internal error                                     |
216
217For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
218
219**Example**
220
221```ts
222import { BusinessError } from '@ohos.base';
223
224try {
225    systemparameter.setSync("test.parameter.key", "default");
226} catch(e) {
227    console.log("set unexpected error: " + e);
228}
229```
230
231## systemparameter.set
232
233set(key: string, value: string, callback: AsyncCallback&lt;void&gt;): void
234
235Sets a value for the system parameter with the specified key. This API uses an asynchronous callback to return the result.
236
237**System capability**: SystemCapability.Startup.SystemInfo
238
239**Parameters**
240
241| Name| Type| Mandatory| Description|
242| -------- | -------- | -------- | -------- |
243| key | string | Yes| Key of the system parameter.|
244| value | string | Yes| Value of the system parameter to set.|
245| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
246
247**Error codes**
248
249| ID| Error Message                                                    |
250| -------- | ------------------------------------------------------------ |
251| 14700102 | if value is invalid                                          |
252| 14700103 | if permission denied                                         |
253| 14700104 | if system internal error                                     |
254
255For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
256
257**Example**
258
259```ts
260import { BusinessError } from '@ohos.base';
261
262try {
263    systemparameter.set("test.parameter.key", "testValue", (err: BusinessError, data: void) => {
264    if (err == undefined) {
265        console.log("set test.parameter.key value success :" + data)
266    } else {
267        console.log("set test.parameter.key value err:" + err.code)
268    }});
269} catch(e) {
270    console.log("set unexpected error: " + e);
271}
272```
273
274## systemparameter.set
275
276set(key: string, value: string): Promise&lt;void&gt;
277
278Sets a value for the system parameter with the specified key. This API uses a promise to return the result.
279
280**System capability**: SystemCapability.Startup.SystemInfo
281
282**Parameters**
283
284| Name| Type| Mandatory| Description|
285| -------- | -------- | -------- | -------- |
286| key | string | Yes| Key of the system parameter.|
287| value| string | Yes| Value of the system parameter to set.|
288
289**Return value**
290
291| Type| Description|
292| -------- | -------- |
293| Promise&lt;void&gt; | Promise used to return the execution result.|
294
295**Error codes**
296
297| ID| Error Message                                                    |
298| -------- | ------------------------------------------------------------ |
299| 14700102 | if value is invalid                                          |
300| 14700103 | if permission denied                                         |
301| 14700104 | if system internal error                                     |
302
303For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
304
305**Example**
306
307```ts
308import { BusinessError } from '@ohos.base';
309
310try {
311    let p: Promise<void>  = systemparameter.set("test.parameter.key", "testValue");
312    p.then((value: void) => {
313        console.log("set test.parameter.key success: " + value);
314    }).catch((err: BusinessError) => {
315        console.log(" set test.parameter.key error: " + err.code);
316    });
317} catch(e) {
318    console.log("set unexpected error: " + e);
319}
320```
321