js-apis-system-parameter.md 8.7 KB
Newer Older
E
ester.zhou 已提交
1
# @ohos.systemParameter (System Parameter)
Z
zengyawen 已提交
2

E
esterzhou 已提交
3
The **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.
E
ester.zhou 已提交
4 5 6 7
For details about the system parameter design principles and definitions, see
[Service Management](../../../device-dev/subsystems/subsys-boot-init-sysparam.md).

> **NOTE**
E
ester.zhou 已提交
8
> - The APIs of this module are no longer maintained since API version 9. It is recommended that you use [@ohos.systemParameterEnhance](js-apis-system-parameterEnhance.md) instead.
E
esterzhou 已提交
9
> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
E
ester.zhou 已提交
10 11 12
> - The APIs provided by this module are system APIs.
> - Third-party applications cannot use the APIs provided by this module, because system parameters each require specific discretionary access control (DAC) and MAC permissions.

E
esterzhou 已提交
13 14

## Modules to Import
Z
zengyawen 已提交
15

P
update  
Peter_1988 已提交
16
```ts
E
ester.zhou 已提交
17
import systemparameter from '@ohos.systemparameter'
Z
zengyawen 已提交
18 19
```

E
ester.zhou 已提交
20
## systemparameter.getSync<sup>(deprecated)</sup>
Z
zengyawen 已提交
21

E
ester.zhou 已提交
22
getSync(key: string, def?: string): string
Z
zengyawen 已提交
23

E
ester.zhou 已提交
24
Obtains the value of the system parameter with the specified key.
Z
zengyawen 已提交
25

E
ester.zhou 已提交
26
**System capability**: SystemCapability.Startup.SystemInfo
Z
zengyawen 已提交
27 28 29

**Parameters**

E
esterzhou 已提交
30 31
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
E
ester.zhou 已提交
32
| key | string | Yes| Key of the system parameter.|
E
ester.zhou 已提交
33
| 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. |
E
esterzhou 已提交
34 35 36 37 38

**Return value**

| Type| Description|
| -------- | -------- |
E
ester.zhou 已提交
39
| 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 empty string is returned. |
Z
zengyawen 已提交
40 41 42

**Example**

P
update  
Peter_1988 已提交
43
```ts
Z
zengyawen 已提交
44
try {
E
ester.zhou 已提交
45
    var info = systemparameter.getSync("const.ohos.apiversion");
Z
zengyawen 已提交
46
    console.log(JSON.stringify(info));
E
ester.zhou 已提交
47
} catch(e) {
Z
zengyawen 已提交
48 49 50 51
    console.log("getSync unexpected error: " + e);
}
```

E
ester.zhou 已提交
52
## systemparameter.get<sup>(deprecated)</sup>
Z
zengyawen 已提交
53

E
ester.zhou 已提交
54
get(key: string, callback: AsyncCallback&lt;string&gt;): void
E
esterzhou 已提交
55

E
esterzhou 已提交
56
Obtains the value of the system parameter with the specified key. This API uses an asynchronous callback to return the result. 
E
esterzhou 已提交
57

E
ester.zhou 已提交
58
**System capability**: SystemCapability.Startup.SystemInfo
Z
zengyawen 已提交
59 60 61

**Parameters**

E
esterzhou 已提交
62 63
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
E
ester.zhou 已提交
64
| key | string | Yes| Key of the system parameter.|
E
esterzhou 已提交
65
| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the result.|
Z
zengyawen 已提交
66 67 68

**Example**

P
update  
Peter_1988 已提交
69
```ts
Z
zengyawen 已提交
70
try {
E
ester.zhou 已提交
71
    systemparameter.get("const.ohos.apiversion", function (err, data) {
Z
zengyawen 已提交
72 73 74 75 76
    if (err == undefined) {
        console.log("get test.parameter.key value success:" + data)
    } else {
        console.log(" get test.parameter.key value err:" + err.code)
    }});
E
ester.zhou 已提交
77
} catch(e) {
Z
zengyawen 已提交
78 79 80 81
    console.log("get unexpected error: " + e);
}
```

E
ester.zhou 已提交
82
## systemparameter.get<sup>(deprecated)</sup>
E
esterzhou 已提交
83

E
ester.zhou 已提交
84
get(key: string, def: string, callback: AsyncCallback&lt;string&gt;): void
Z
zengyawen 已提交
85

E
ester.zhou 已提交
86
Obtains the value of the system parameter with the specified key. This API uses an asynchronous callback to return the result.
E
esterzhou 已提交
87

E
ester.zhou 已提交
88
**System capability**: SystemCapability.Startup.SystemInfo
Z
zengyawen 已提交
89 90 91

**Parameters**

E
esterzhou 已提交
92 93
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
E
ester.zhou 已提交
94
| key | string | Yes| Key of the system parameter.|
E
ester.zhou 已提交
95
| def | string | Yes| Default value.|
E
esterzhou 已提交
96
| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the result.|
Z
zengyawen 已提交
97 98 99

**Example**

P
update  
Peter_1988 已提交
100
```ts
Z
zengyawen 已提交
101
try {
E
ester.zhou 已提交
102
    systemparameter.get("const.ohos.apiversion", "default", function (err, data) {
Z
zengyawen 已提交
103 104 105 106 107 108
        if (err == undefined) {
            console.log("get test.parameter.key value success:" + data)
        } else {
            console.log(" get test.parameter.key value err:" + err.code)
        }
    });
E
ester.zhou 已提交
109
} catch(e) {
Z
zengyawen 已提交
110 111 112 113
    console.log("get unexpected error:" + e)
}
```

E
ester.zhou 已提交
114
## systemparameter.get<sup>(deprecated)</sup>
E
esterzhou 已提交
115

E
ester.zhou 已提交
116
get(key: string, def?: string): Promise&lt;string&gt;
E
esterzhou 已提交
117

E
ester.zhou 已提交
118
Obtains the value of the system parameter with the specified key. This API uses a promise to return the result.
Z
zengyawen 已提交
119

E
ester.zhou 已提交
120
**System capability**: SystemCapability.Startup.SystemInfo
Z
zengyawen 已提交
121 122 123

**Parameters**

E
esterzhou 已提交
124 125
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
E
ester.zhou 已提交
126
| key | string | Yes| Key of the system parameter.|
E
ester.zhou 已提交
127
| 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. |
E
esterzhou 已提交
128 129 130 131 132 133

**Return value**

| Type| Description|
| -------- | -------- |
| Promise&lt;string&gt; | Promise used to return the execution result.|
Z
zengyawen 已提交
134 135 136

**Example**

P
update  
Peter_1988 已提交
137
```ts
Z
zengyawen 已提交
138
try {
E
ester.zhou 已提交
139
    var p = systemparameter.get("const.ohos.apiversion");
Z
zengyawen 已提交
140 141 142 143 144
    p.then(function (value) {
        console.log("get test.parameter.key success: " + value);
    }).catch(function (err) {
        console.log("get test.parameter.key error: " + err.code);
    });
E
ester.zhou 已提交
145
} catch(e) {
Z
zengyawen 已提交
146 147 148 149
    console.log("get unexpected error: " + e);
}
```

E
ester.zhou 已提交
150
## systemparameter.setSync<sup>(deprecated)</sup>
E
esterzhou 已提交
151

E
ester.zhou 已提交
152
setSync(key: string, value: string): void
Z
zengyawen 已提交
153

E
ester.zhou 已提交
154
Sets a value for the system parameter with the specified key.
Z
zengyawen 已提交
155

E
ester.zhou 已提交
156
**System capability**: SystemCapability.Startup.SystemInfo
E
esterzhou 已提交
157

Z
zengyawen 已提交
158 159
**Parameters**

E
esterzhou 已提交
160 161
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
E
ester.zhou 已提交
162 163 164 165 166
| key | string | Yes| Key of the system parameter.|
| value | string | Yes| Value of the system parameter to set.|

> **NOTE**
> - This API can be used only for setting parameters of system applications.
E
esterzhou 已提交
167 168
> - SELinux and Discretionary Access Control (DAC) rules must be configured for authorized system applications. For details about how to configure SELinux and DAC rules, see [Parameter Management](../../../device-dev/subsystems/subsys-boot-init-sysparam.md).

Z
zengyawen 已提交
169 170 171

**Example**

P
update  
Peter_1988 已提交
172
```ts
Z
zengyawen 已提交
173
try {
E
ester.zhou 已提交
174
    systemparameter.setSync("test.parameter.key", "default");
E
ester.zhou 已提交
175
} catch(e) {
Z
zengyawen 已提交
176 177 178 179
    console.log("set unexpected error: " + e);
}
```

E
ester.zhou 已提交
180
## systemparameter.set<sup>(deprecated)</sup>
Z
zengyawen 已提交
181

E
ester.zhou 已提交
182
set(key: string, value: string, callback: AsyncCallback&lt;void&gt;): void
E
esterzhou 已提交
183

E
ester.zhou 已提交
184
Sets a value for the system parameter with the specified key. This API uses an asynchronous callback to return the result.
E
esterzhou 已提交
185

E
ester.zhou 已提交
186
**System capability**: SystemCapability.Startup.SystemInfo
Z
zengyawen 已提交
187 188 189

**Parameters**

E
esterzhou 已提交
190 191
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
E
ester.zhou 已提交
192 193
| key | string | Yes| Key of the system parameter.|
| value | string | Yes| Value of the system parameter to set.|
E
esterzhou 已提交
194
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
Z
zengyawen 已提交
195

E
ester.zhou 已提交
196 197
> **NOTE**
> - This API can be used only for setting parameters of system applications.
E
esterzhou 已提交
198
> - SELinux and Discretionary Access Control (DAC) rules must be configured for authorized system applications. For details about how to configure SELinux and DAC rules, see [Parameter Management](../../../device-dev/subsystems/subsys-boot-init-sysparam.md).
E
ester.zhou 已提交
199

Z
zengyawen 已提交
200 201
**Example**

P
update  
Peter_1988 已提交
202
```ts
Z
zengyawen 已提交
203
try {
E
ester.zhou 已提交
204
    systemparameter.set("test.parameter.key", "testValue", function (err, data) {
Z
zengyawen 已提交
205 206 207 208 209
    if (err == undefined) {
        console.log("set test.parameter.key value success :" + data)
    } else {
        console.log("set test.parameter.key value err:" + err.code)
    }});
E
ester.zhou 已提交
210
} catch(e) {
Z
zengyawen 已提交
211 212 213 214
    console.log("set unexpected error: " + e);
}
```

E
ester.zhou 已提交
215
## systemparameter.set<sup>(deprecated)</sup>
Z
zengyawen 已提交
216

E
ester.zhou 已提交
217
set(key: string, value: string): Promise&lt;void&gt;
E
esterzhou 已提交
218

E
ester.zhou 已提交
219
Sets a value for the system parameter with the specified key. This API uses a promise to return the result.
E
esterzhou 已提交
220

E
ester.zhou 已提交
221
**System capability**: SystemCapability.Startup.SystemInfo
Z
zengyawen 已提交
222 223 224

**Parameters**

E
esterzhou 已提交
225 226
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
E
ester.zhou 已提交
227 228
| key | string | Yes| Key of the system parameter.|
| value| string | Yes| Value of the system parameter to set.|
E
esterzhou 已提交
229 230 231 232 233

**Return value**

| Type| Description|
| -------- | -------- |
E
ester.zhou 已提交
234
| Promise&lt;void&gt; | Promise used to return the execution result.|
Z
zengyawen 已提交
235

E
ester.zhou 已提交
236 237
> **NOTE**
> - This API can be used only for setting parameters of system applications.
E
esterzhou 已提交
238
> - SELinux and Discretionary Access Control (DAC) rules must be configured for authorized system applications. For details about how to configure SELinux and DAC rules, see [Parameter Management](../../../device-dev/subsystems/subsys-boot-init-sysparam.md).
E
ester.zhou 已提交
239

Z
zengyawen 已提交
240 241
**Example**

P
update  
Peter_1988 已提交
242
```ts
Z
zengyawen 已提交
243
try {
E
ester.zhou 已提交
244
    var p = systemparameter.set("test.parameter.key", "testValue");
Z
zengyawen 已提交
245 246 247 248 249
    p.then(function (value) {
        console.log("set test.parameter.key success: " + value);
    }).catch(function (err) {
        console.log(" set test.parameter.key error: " + err.code);
    });
E
ester.zhou 已提交
250
} catch(e) {
Z
zengyawen 已提交
251 252 253
    console.log("set unexpected error: " + e);
}
```