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