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 { systemParameterEnhance } from '@kit.BasicServicesKit';
16```
17
18## systemParameterEnhance.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. The value can contain a maximum of 128 bytes. Only letters, digits, periods (.), hyphens (-), at signs (@), colons (:), and underscores (_) are allowed.|
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| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.incorrect parameter types; 3.parameter verification failed. |
44| 14700101 | System parameter not found.                                          |
45| 14700103 | The operation on the system permission is denied.                    |
46| 14700104 | System internal error such as out memory or deadlock.                |
47
48For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
49
50**Example**
51
52```ts
53try {
54    let info: string = systemParameterEnhance.getSync("const.ohos.apiversion");
55    console.log(JSON.stringify(info));
56} catch(e) {
57    console.log("getSync unexpected error: " + e);
58}
59```
60
61## systemParameterEnhance.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. The value can contain a maximum of 128 bytes. Only letters, digits, periods (.), hyphens (-), at signs (@), colons (:), and underscores (_) are allowed.|
74| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the result.|
75
76**Error codes**
77
78| ID| Error Message                                                    |
79| -------- | ------------------------------------------------------------ |
80| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.incorrect parameter types; 3.parameter verification failed. |
81| 14700101 | System parameter not found.                                          |
82| 14700103 | The operation on the system permission is denied.                    |
83| 14700104 | System internal error such as out memory or deadlock.                |
84
85For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
86
87**Example**
88
89```ts
90import { BusinessError } from '@kit.BasicServicesKit';
91
92try {
93    systemParameterEnhance.get("const.ohos.apiversion", (err: BusinessError, data: string) => {
94    if (err == undefined) {
95        console.log("get test.parameter.key value success:" + data)
96    } else {
97        console.log(" get test.parameter.key value err:" + err.code)
98    }});
99} catch(e) {
100    console.log("get unexpected error: " + e);
101}
102```
103
104## systemParameterEnhance.get
105
106get(key: string, def: string, callback: AsyncCallback&lt;string&gt;): void
107
108Obtains the value of the system parameter with the specified key. This API uses an asynchronous callback to return the result.
109
110**System capability**: SystemCapability.Startup.SystemInfo
111
112**Parameters**
113
114| Name| Type| Mandatory| Description|
115| -------- | -------- | -------- | -------- |
116| key | string | Yes| Key of the system parameter. The value can contain a maximum of 128 bytes. Only letters, digits, periods (.), hyphens (-), at signs (@), colons (:), and underscores (_) are allowed.|
117| def | string | Yes| Default value.|
118| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the result.|
119
120**Error codes**
121
122| ID| Error Message                                                    |
123| -------- | ------------------------------------------------------------ |
124| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.incorrect parameter types; 3.parameter verification failed. |
125| 14700101 | System parameter not found.                                          |
126| 14700103 | The operation on the system permission is denied.                    |
127| 14700104 | System internal error such as out memory or deadlock.                |
128
129For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
130
131**Example**
132
133```ts
134import { BusinessError } from '@kit.BasicServicesKit';
135
136try {
137    systemParameterEnhance.get("const.ohos.apiversion", "default", (err: BusinessError, data: string) => {
138        if (err == undefined) {
139            console.log("get test.parameter.key value success:" + data)
140        } else {
141            console.log(" get test.parameter.key value err:" + err.code)
142        }
143    });
144} catch(e) {
145    console.log("get unexpected error:" + e)
146}
147```
148
149## systemParameterEnhance.get
150
151get(key: string, def?: string): Promise&lt;string&gt;
152
153Obtains the value of the system parameter with the specified key. This API uses a promise to return the result.
154
155**System capability**: SystemCapability.Startup.SystemInfo
156
157**Parameters**
158
159| Name| Type| Mandatory| Description|
160| -------- | -------- | -------- | -------- |
161| key | string | Yes| Key of the system parameter. The value can contain a maximum of 128 bytes. Only letters, digits, periods (.), hyphens (-), at signs (@), colons (:), and underscores (_) are allowed.|
162| 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.|
163
164**Return value**
165
166| Type| Description|
167| -------- | -------- |
168| Promise&lt;string&gt; | Promise used to return the execution result.|
169
170**Error codes**
171
172| ID| Error Message                                                    |
173| -------- | ------------------------------------------------------------ |
174| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.incorrect parameter types; 3.parameter verification failed. |
175| 14700101 | System parameter not found.                                          |
176| 14700103 | The operation on the system permission is denied.                    |
177| 14700104 | System internal error such as out memory or deadlock.                |
178
179For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
180
181**Example**
182
183```ts
184import { BusinessError } from '@kit.BasicServicesKit';
185
186try {
187    let p: Promise<string> = systemParameterEnhance.get("const.ohos.apiversion");
188    p.then((value: string) => {
189        console.log("get test.parameter.key success: " + value);
190    }).catch((err: BusinessError) => {
191        console.log("get test.parameter.key error: " + err.code);
192    });
193} catch(e) {
194    console.log("get unexpected error: " + e);
195}
196```
197
198## systemParameterEnhance.setSync
199
200setSync(key: string, value: string): void
201
202Sets a value for the system parameter with the specified key.
203
204**System capability**: SystemCapability.Startup.SystemInfo
205
206**Parameters**
207
208| Name| Type| Mandatory| Description|
209| -------- | -------- | -------- | -------- |
210| key | string | Yes| Key of the system parameter. The value can contain a maximum of 128 bytes. Only letters, digits, periods (.), hyphens (-), at signs (@), colons (:), and underscores (_) are allowed.|
211| value | string | Yes| Value of the system parameter to set. The value can contain a maximum of 96 bytes (including the end character).|
212
213**Error codes**
214
215| ID| Error Message                                                    |
216| -------- | ------------------------------------------------------------ |
217| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.incorrect parameter types; 3.parameter verification failed. |
218| 14700102 | Invalid system parameter value.                                          |
219| 14700103 | The operation on the system permission is denied.                        |
220| 14700104 | System internal error such as out memory or deadlock.                    |
221
222For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
223
224**Example**
225
226```ts
227import { BusinessError } from '@kit.BasicServicesKit';
228
229try {
230    systemParameterEnhance.setSync("test.parameter.key", "default");
231} catch(e) {
232    console.log("set unexpected error: " + e);
233}
234```
235
236## systemParameterEnhance.set
237
238set(key: string, value: string, callback: AsyncCallback&lt;void&gt;): void
239
240Sets a value for the system parameter with the specified key. This API uses an asynchronous callback to return the result.
241
242**System capability**: SystemCapability.Startup.SystemInfo
243
244**Parameters**
245
246| Name| Type| Mandatory| Description|
247| -------- | -------- | -------- | -------- |
248| key | string | Yes| Key of the system parameter. The value can contain a maximum of 128 bytes. Only letters, digits, periods (.), hyphens (-), at signs (@), colons (:), and underscores (_) are allowed.|
249| value | string | Yes| Value of the system parameter to set. The value can contain a maximum of 96 bytes (including the end character).|
250| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
251
252**Error codes**
253
254| ID| Error Message                                                    |
255| -------- | ------------------------------------------------------------ |
256| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.incorrect parameter types; 3.parameter verification failed. |
257| 14700102 | Invalid system parameter value.                                          |
258| 14700103 | The operation on the system permission is denied.                        |
259| 14700104 | System internal error such as out memory or deadlock.                    |
260
261For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
262
263**Example**
264
265```ts
266import { BusinessError } from '@kit.BasicServicesKit';
267
268try {
269    systemParameterEnhance.set("test.parameter.key", "testValue", (err: BusinessError, data: void) => {
270    if (err == undefined) {
271        console.log("set test.parameter.key value success :" + data)
272    } else {
273        console.log("set test.parameter.key value err:" + err.code)
274    }});
275} catch(e) {
276    console.log("set unexpected error: " + e);
277}
278```
279
280## systemParameterEnhance.set
281
282set(key: string, value: string): Promise&lt;void&gt;
283
284Sets a value for the system parameter with the specified key. This API uses a promise to return the result.
285
286**System capability**: SystemCapability.Startup.SystemInfo
287
288**Parameters**
289
290| Name| Type| Mandatory| Description|
291| -------- | -------- | -------- | -------- |
292| key | string | Yes| Key of the system parameter. The value can contain a maximum of 128 bytes. Only letters, digits, periods (.), hyphens (-), at signs (@), colons (:), and underscores (_) are allowed.|
293| value| string | Yes| Value of the system parameter to set. The value can contain a maximum of 96 bytes (including the end character).|
294
295**Return value**
296
297| Type| Description|
298| -------- | -------- |
299| Promise&lt;void&gt; | Promise used to return the execution result.|
300
301**Error codes**
302
303| ID| Error Message                                                    |
304| -------- | ------------------------------------------------------------ |
305| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.incorrect parameter types; 3.parameter verification failed. |
306| 14700102 | Invalid system parameter value.                                          |
307| 14700103 | The operation on the system permission is denied.                        |
308| 14700104 | System internal error such as out memory or deadlock.                    |
309
310For details about the error codes, see [System Parameter Error Codes](errorcode-system-parameterV9.md).
311
312**Example**
313
314```ts
315import { BusinessError } from '@kit.BasicServicesKit';
316
317try {
318    let p: Promise<void>  = systemParameterEnhance.set("test.parameter.key", "testValue");
319    p.then((value: void) => {
320        console.log("set test.parameter.key success: " + value);
321    }).catch((err: BusinessError) => {
322        console.log(" set test.parameter.key error: " + err.code);
323    });
324} catch(e) {
325    console.log("set unexpected error: " + e);
326}
327```
328