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